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 : nominatim, geonames, yahoo

ReverseGeocode : nominatim, 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
Bugs are handled in freedesktop.org Bugzilla
- File a bug
- see open bugs
- Get notified of new Geoclue bugs (add geoclue-bugs@freedesktop.org to your watchlist)

Learn more

The documentation includes

D-Bus API Interface reference (not finished)
Client C API reference
Examples on how to use geoclue in an application The documentation source also contains documentation on provider API and writing providers, but these are not finished.

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 as a tar-ball and in a Git repository. You can also browse the source.

Latest release: Geoclue 0.12.99

Git repository:

[[!format txt """ 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.

Getting started

There is a nice UI to see available providers and configure some of them. One can e.g. configure the "manual" provider with a static address. You can get the code here.

Also check out the Python API that python-geoclue provides.

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 expose location to websites: Webkit may support Locationaware in the future.
Google Gears

Possible data sources

Geocoding for phone numbers - use countries telephone number dial plans to convert phone numbers to general locations (obviously less accuracy with mobiles and world-wide roaming/etc)
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, ..
- A free network location database project has begun at http://geomena.org