The geoloc URI scheme

The hompage for this document is

I wrote this. Simon Slavin, email


The use of GPS is (as of mid-2008) growing rapidly, especially in automotive SatNav units and cameras which automatically geocode their photographs. Use of Google Maps and Google Earth is now prevalent. The concepts and uses of GPS are now appreciated not just by people who have related hobbies, but by many members of the general public. It is becoming increasingly useful to be able to refer to geolocations in various types of message.

Various formats and microformats have arisen to allow people to express GPS coordinates. However, many of them require users to understand the syntax of XML or some similarly complicated notation, and none of them are automatically interpreted by existing web browsers, mail software, and other internet applications. On the other hand, the use of URIs, especially URLs, is understood by most internet software and familiar to most internet users. Creating a URI scheme to express a geolocation seems to be an appropriate way forward.

My hope is that people who want to supply a location simply will use this new URI format to do so. If it is adopted I would expect to see something like the following in a blog entry:

On Saturday we took a trip to the new shopping
which opened just south of our city.

Implementations should do whatever the computer's (or device's) user wants to do with geolocations. An implementation on a conventional computer might use Google Maps or Google Earth to indicate the point (and radius and/or direction) supplied. Some people might prefer other mapping web sites, or to use another program which does something with location information. An implementation on a navigation device would probably indicate the point on the device's mapping system and allow the user to use it as a destination point.


The parameters of a geoloc URI are specified in this order:


latitudelatitude according to WGS84degrees from -90 to 90 inclusive
longitudelongitude according to WGS84degrees from -180 to 180 inclusive
altitudeheight above geoid or height above ground, depending on applicationmeters
radiusdepends on applicationmeters
directionangle clockwise of local north according to WGS84degrees from -180 to 180 inclusive
tiltangle upwards of directly aheaddegrees from -180 to 180 inclusive

The first three parameters are used to indicate a position. The fourth, radius, is used by a number of different applications for various purposes. The fifth and six are intended for use by photographers and people involved in surveying.

The radius parameter is intentionally ambiguous. It might refer either to the uncertainty in the coordinates (including altitude if an altitude is supplied), or to a notional size of the object to be found at those coordinates.

From the above, it should be possible to deduce that ...


Demonstration implementation for Mac OS X

I have prepared a handler for geoloc URIs for Mac OS X. All you need to do to make the handler work is download it and unzip it. geoloc URIs will then work in any document that URIs like 'mailto:' and 'http:' work in. This demonstration hander does one of two things:

The demonstration program is written in AppleScript, to encourage non-programmers to edit the handler so it does what they want rather than what my demonstration version does. An AppleScript editor is included with every copy of Mac OS X. The simplest way to edit the application (or view the source) is to run the application with the control key down, then choose 'Edit Script' from the 'Edit' menu.

AppleScript is easily readable by programmers who don't know it, so the code should be useful to people writing implementations for other platforms. A copy of the source for the code can be found here.

Other platforms

An implementation for the iPhone is forthcoming, though you're welcome to beat me to it. Small simple implementations with source for other platforms, especially Windows and Linux, are welcome. I don't know how to implement URI handlers on those platforms.


My thanks to Hal Mueller who suggested the 'radius' parameter.

Corrections, contributions, and criticism are all welcome. Eventually I intent to propose that this specification could be released as an RFC using the procedure explained in RFC2717.

History of this document

2008/07/050.0.1Work on this documentation begun

Terms of use

This document is copyright ©2008 Simon Slavin. I'm copyrighting it because this is a preliminary version of the documentation, with a preliminary version of the specification, and I don't want a non-final version of the format out in the wild. Please point to it rather than copying it. Once version 1.0 of the specification is settled it'll be released on the same terms as RFCs.