This is a snapshot of the frontpage from Feb 11 2008. Please use the Geoclue home page if you're looking for current information.


GeoClue - geographic information service.

GeoClue is a D-Bus API and library that provides all kinds of geographic information to applications. The information may originally come in various forms from many sources (backends), but GeoClue offers it to applications in a simple, abstracted form.

GeoClue is Free Software. It is developed for Linux, but should be portable to any platform that uses the D-Bus messaging bus.

The following APIs (and backend types) are supported or planned:

  • Positioning
  • Routing
  • Geocoding
  • Map
  • Track Logs Some reference backends are included, but creating your own is encouraged.

There is a lot of ideas you can implement with this service. For example we could automatically set a weather forecast program to show the weather of your current location.

Getting the code

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

  • git clone git://
    GeoClue is still in early stages of development, so be prepared for hickups. For help with Git, see Usage notes here on and documentation on Git homepage.

Iain Holmes and Jussi Kukkonen are working on a rewrite at -- we believe a fairly total API change is needed to make geoclue really work as intended. We're hoping this will be the "main branch" soon.

Contacting the developers

The mailing list is a good place for questions and comments. If you've found a bug or have a feature request, file a bug in our bugzilla. You are also welcome to join the ad-hoc irc channel #geoclue on GimpNet ( If you are behind a restrictive firewall, try IRC@Work.


GeoClue for Application Writers -- D-Bus service or C library

There are two methods to accessing this service. You can use the raw D-Bus API through any prospective bindings or you can use the utility C wrapper provided with the package.


The idea is to have several different backends. A GPS is naturally the most accurate source, but it does not work well indoors, and a device might not always be available. Yet, even without a GPS, a bit less accurate position is easily available using other methods, and this information will in most cases be just as useful. Also sometimes you might not want to expose your exact coordinates ("send nukes here"-problem) - thus the API will have ways to serve different types of location data.

Also since there are several web services to provide you with street address -> coordinate (and backwards) coding, this will be one useful service GeoClue will make accessible through itself. A street address or a "plaze" name (see below for plazes) might be more useful to show to your IM buddies for example, since it is more human readable than a lat,lon coordinate pair. Yet for mapping uses etc, it should be good that both are always made available, plus some way to determine the accuracy of the data. Sure, "Boston" is located in W+71°+3'+37"&ie=UTF8&z=16&ll=42.358211,-71.060278&spn=0.006961,0.021415&om=1&iwloc=A N 42° 21' 29" W 71° 3' 37" but the area is a lot larger than the actual coordinate reference point, which points to a street corner between Tremont and Beacon Street.

  • gpsd - to talk to real gps devices.
  • - a website that tracks your location based on the network topology, wifi hotspots etc. It has a XMLRPC API. Requires login, lets users tag "places" with names also. "MIT Media Lab" instead of "20 Ames St, Cambridge, MA 02142".
  • - a similar thing to plazes, but requires no login, and returns a city based on your IP. In many cases accurate enough for most non-mapping uses like timezone etc.
  • Manual - user sets position by hand, using a panel applet or something similar. A fallback when there is no other method, or if the other methods fail to provide correct information. Online Geocoding services can be used to convert street and city names etc to location.
  • A flight tracker to find your position if you set your location to "Lufthansa 421" for example ;-) (only half-joking, for example Aeroseek gives you also a google earth (KML) file for the flight's location and route..)

Work that needs to be done

short TODO items:

  • Change org.foinse.project references to org.geoclue?
  • Old FSF adresses in the source files
  • is backend/geocluemaster_ deprecated? should remove it if it is...
  • remove references to Geomap (an old project name?) in comments and messages
  • review backends for copy-paste errors (in code, strings and comments)
  • remove dependency on gpsd

Developer docs

Document the D-Bus interfaces -- both provider and application API.

gnome applet

  • Make a small applet that can pop up an info box when a location is first reported. "You are in Olathe, KS". When left clicked on brings up a 320x240 image (can just be a static image for now I will add map to it.) with an entry below it that you can type in an address along with a search button. When you left click the applet it would bring up a menu with a properties box. This box would allow you to set preference for what service to use. basically a drop down for "Manual entry", "", "Gps device" There can be five of these for position, mapping, geocoding, tracking, routing.


Something like this could pop up from the notification system once GeoClue finds we are in a significantly new place. How and when this happens needs to be determined somehow. Perhaps like, when moving to a new city or switching networks etc. We shouldnt pop these up repeatedly while moving around with GPS location though, that'd be annoying.

|                                  [x]|
|  *New Location*                     |
|                                     |
|  Helsinki, FINLAND                  |
|                                     |
|  Is this wrong?  [ Correct it! ]    | <- gives a correction dialog
|                                     |
|  [ ] Stop tracking my location      |
|      automatically.                 |
|                                     |
Correction dialog:
.-( Set Location )-------------------------------(x)-.
|                                                    |
| Address: [ 20 Ames St, Cambridge, MA ] [ Look up ] |
|                                                    |
||                                                  ||
||                                                  ||
||                                                  ||
||                                                  ||
||                                                  ||
||                                                  ||
||                                                  ||
||                                                  ||
||               m a p   w i d g e t                ||
||                                                  ||
||                                                  ||
||                                                  ||
||                                                  ||
||                                                  ||
||                                                  ||
||                                                  ||
||                                                  ||
|                                                    |
|                                   [ Set Location ] |
|                                                    |


Already Implemented

  1. maps yahoo
  2. position manual
  3. position
  4. geocode yahoo Needs

  5. maps static image (big world image or svg of world)

  6. position
  7. track turtle
  8. routing ?
  9. position GPSD

Application ideas

  • Applications like Evolution could set their timezone automatically
  • Contacts and Instant Messaging could extend the idea of presence to also include the concept of geographic location. "Bob is in Singapore, and it's 4am there, so you should not call him right now". see loopt, for example:
  • Blogging software could query the location and add "geotags" to the post metadata.
  • Groupware and collaboration tools could track project participants to see which technician is closest to a client with a support ticket
  • Applications like Turtle could store track log of movement, and could then mesh it with timestamps of documents, photographs etc, to define where they were created and possibly make a map-based timeline/track of events, thus...
  • ...Using position as metadata for content ("where is the document I wrote at Tigert's place?")
  • Using position for desktop settings (timezone, printers, SMTP servers, whatever). Marco Polo looks like a good implementation on OS X.
  • Finding WiFi networks based on position ("I'm in Aleksanterinkatu in Helsinki, where are the nearest free WiFis?")
  • interacting with/supporting the minimo's geolocation standard:
  • It would be nice to for example add and use bookmarks with geo-tags, or etc, to pull a feed for "stuff near me"
  • Many sites publish google earth KML files like RSS. This is for example current earthquakes, overlaid on Google Maps. A lot of other stuff can also be found.
  • Amateur Radio - both APRS Automatic Position Reporting System and for automatically filling in the grid square location for contact logging.
  • etc etc..


Add yourself here if you are interested, so its easier to keep track of us.. :)

  • TuomasKuosmanen
  • HenriBergius
  • KeithPreston
  • SeanKelley
  • KentBolton
  • RussNelson
  • DanieleDiMauro
  • AndrewTurner
  • EeroHeurlin
  • Jussi Kukkonen

GeoClue Hack session 1 at Boston2006

  1. Mapping 1. Position 1. Geocoding 1. Routing 1. Track

Mapping - Gtk+/D-Bus interface to retrieve map data from using a plugin. Other sources of mapping could be used. On a mapping backend you may not always have a map backend. So it might be a good idea to cache that map data.

Position - Provides position, velocity, and time data. One backend currently supported is gpsd, connected to a GPS sensor.

Geocoding - Find nearest points of interest based on current location. Will have a backend.

Routing - Ability to submit desitinations to a backend like in order to generate a route.

Track - Ability to leave a cookie crumb trail.


Gossip / Jabber

  • - implement the location stuff correctly
  • Share position with your buddies. Perhaps different accuracy for some buddy groups ("Friends see my street address, others just the city I am in")
  • Share position information between clients
  • Share interesting places between IM buddies ("Awesome icecream here!", "I'll be going [to the library] to read, lets meet there at 6" )
  • Display contacts on a map

Gnome Blog

  • Look-up standard XMLRPC and see if postion information is a part of the spec.
  • Otherwise add position to XML as a tags
  • Blog sites could pick up those tags and have creative ways of presenting location.
  • Wikipedia has some info about how to tag blog entries - apparently you need three tags: one "geotagged" to generally make others aware your post is geotagged, and then the coords in two tags: geo:latitude and geo:longitude eg: geo:lat=51.4989 geo:lon=-0.1786



  • Embed a map into the application to display the locations of photos
  • Add geotags and export them correctly (ie, Flickr)
  • Talk with Toshok to get Turtle as part of this effort

Stars (and Maemo Stars)

  • Stars and Maemo Stars are GTK applications displaying a map of the night sky. Both of them would benefit from automatically displaying stars of user's current position as default based on the GeoClue information.


Keith - Conglomerate (code) Sean - backend

    • lookup other choices Tuomas - looking up XMLRPC
    • looking up jabber - gossip client Sean - gnome blogger

Datasources and APIs

  • -- free database project that maps geographical names to coordinates. (Gnome Mine, Idaho, USA is N 45° 44' 26_ W 115° 31' 12_ etc..) - the database is free, under Creative Commons Attribution 2.5 License).
    • I have a geocoder implementation kind-of-working. The problem is that the geocoding api is not usable... If someone wants it, I'll upload. Otherwise I'll wait for a better API. --Jussi Kukkonen
  • GEONet Names Server -- another worldwide placename database. Included (and cleaned) in geonames.
  • Yahoo Geocoding API (US addresses only). Somewhat implemented.
  • Google Maps Geocoding API
  • -- Location database with a social networking twist. A plazes-backend is included, there's also a Python implementation.
  • -- WIFI hotspot location database (10 million networks)

    • There's a semi-official API. SSID data queries look like this:
        The result is delivered in a not-set-in-stone format:
      • netid~ssid~comment~name~type~freenet~paynet~firsttime~flags~wep~trilat~trilong~dhcp~lastupdt~channel~active~bcninterval~qos~userfound
        00:11:95:20:DF:11~atmosphere~ ~ ~infrastruc~?~?~2005-08-17 16:01:56~0001~N~60.19763184~24.87971687~?~20060404054848~12~Y~100~2~N
        The API is technically available to all, but the license does require users to login (see EULA), so I do not think this is a viable source of position data for geoclue. There's a thread on their forum about this.
  • HostIP -- IP address location database and lookup (returns city-level data at best, often just country). Implemented.

  • GSMLoc -- GSM cell location database
  • -- geocoder for the USA (TIGER data)

Related information

These links need sorting out: