GeoClue: The Geoinformation Service

Geoclue is a modular geoinformation service built on top of the D-Bus messaging system. The goal of the Geoclue project is to make creating location-aware applications as simple as possible.

Geoclue is Free Software, licensed under GNU LGPL. It is developed for Linux, but should be portable to any platform that uses D-Bus.

Geoclue defines a set of geoinformation APIs, but it also includes some providers that implement those APIs. Here is a list of services provided through Geoclue with the currently included implementations:
Position: gpsd, gypsy, hostip, plazes, gsmloc
Address: hostip, plazes, manual, localnet
Velocity: gpsd, gypsy
Geocode: geonames, yahoo
ReverseGeocode: geonames

Geoclue source code contains:

D-Bus definitions for the above APIs
C bindings for Geoclue clients
C bindings for data providers
a set of provider implementations
(experimental) master provider implementation.

Discuss & contribute

Discuss on mailing list
Chat on #geoclue on irc.gimp.org
File bugs and requests in bugzilla
Get notified of new Geoclue bugs ("watch" geoclue-bugs@freedesktop.org)

Learn more

The documentation includes

D-Bus API Interface reference (not finished)
Client C API reference
Provider C API reference (not finished)
How to use geoclue in an application (not finished)
How to implement a geoclue provider Below is a higher level description of Geoclue interfaces, providers and master provider.

Interfaces

Geoclue has three interfaces for querying "current situation": Position, Address and Velocity. They all include a method and a signal to acquire the information in question along with the time and accuracy of the measurement.

There are also interfaces Geocode (for getting a Position from an Address) and ?ReverseGeocode (for getting an Address from a Position).

Possible future interfaces include Map and Route.

Providers

All Geoclue providers are D-Bus services, and can be accessed either via "raw" D-Bus or the C API. A provider may implement more than one Geoclue interface if that makes sense internally. Providers do not have to run as daemons, as D-Bus will start them when needed (providers may also shut down when they're no longer used).

There are several reasons for this structure:

No single provider will be useful in all situations (GPS does not work indoors, webservices require an internet connection, GSM cell positioning accuracy is not too good, etc.)
No single set of providers will be best for all people.
Modularity means that anyone can develop and distribute a provider: Adding new providers requires no changes to Geoclue master. In fact a single geoclue provider is fully self-contained (although libgeoclue will make life easier for clients)
It also means a master provider (see below) can use all installed providers, not just the ones that were installed with the master. Providers must naturally implement the methods in the interfaces they support. However, not all providers support signals: E.g. web service based providers usually do not. A client accessing providers directly should be aware of this.

Master provider

Geoclue includes a master provider, which implements the same interfaces and is used in the same manner as any other provider. The difference is that internally master uses the best Geoclue provider (based on client requirements and provider availability, accuracy and resource requirements). The provider that is actually used may change over time as conditions change, but the client can just ignore this.

Using the Master provider is favourable for several reasons:

Client does not need to know about the accuracy and availability of a specific data source
Client does not need to depend on specific providers
Master caches data so responses will usually be faster
Master understands network connectivity and basically makes all web service based providers "support signals" The master implementation is currently experimental.

Get the source

The code is licensed under the GNU LGPL and is available in a Git repository. You can browse the source or clone the repository:

```
git clone git://anongit.freedesktop.org/git/geoclue
```
For help with Git, see Usage notes here on freedesktop.org and documentation on Git homepage.

The included providers and the C bindings depend on GLib, GObject and Libxml.

Miscellany

History

Geoclue got started during GNOME Summit 2006 in Boston. At least Keith Preston and Tuomas Kuosmanen can be blamed.

There was a total rewrite after version 0.9. Use tag "0.9" (as in git checkout 0.9) if you need the old code. A copy of the Geoclue wiki page from that time is preserved here.

Application ideas

F-Spot / GThumb: tag photos with location data
Stars / ?MaemoStars: show night sky simulation in correct place
Map applications (?MaemoMapper) show correct location on application open
Jabber / Telepathy: support XEP-0080, add location info to Presence
Blog software: add geotags to posts
Yahoo Fire Eagle could use Geoclue as data provider
Use position/address for desktop settings (timezone, printers, SMTP servers, whatever). Marco Polo looks like a good implementation on OS X
disable-screensaver-lock-when-at-home
Find closest free wifi access point
Tracking application (save location history). Could be used later for tagging photos etc.
browser, calendar: autofill address form fields (not sure if current location is wanted that often, though?)
Browser could let websites know user address/position: http://locationaware.org/ . Other options include Google Gears or a geo-extension to http

Possible data sources

Google Maps Geocoding API -- License says "only for showing places on Google Maps"
Wigle.net-- WIFI location database (10 million networks). License requires users to login.
geocoder.us -- geocoder for the USA (TIGER data)
gsmloc-provider could easily get the GSM information using AT commands on the ?OpenMoko platform
We really should have a free network location database (like gsmloc.org, but for WLAN, GSM, BT, ethernet gateway, ...)