The geoloc URI scheme

The hompage for this document is http://www.bigfraud.org/geoloc/.

I wrote this. Simon Slavin, email thread@bigfraud.org

Introduction

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:

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.

Format

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

<geoloc:latitude,longitude,altitude,radius,direction,tilt>

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.

• Each parameter is a decimal number expressed in no characters apart from digits, the negative symbol, and the decimal point.
• Parameters are separated by one comma. Whitespace before or after the comma is not permitted.
• A parameter may be missing, yielding, for example, ',,' in the URI. This is a statement that its value is unknown, not that it is zero.
• Any number of parameters may be supplied.
• If less than six parameters are supplied, the n supplied represent the first n of the six.
• If more than six parameters are supplied, those after the sixth are ignored.
• A zero radius has meaning. Until I can think of an interpretation for it, a negative radius has no meaning and should be interpreted as the radius parameter being missing.

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

• <geoloc:> is a valid URI. It indicates that all details are unknown.
• <geoloc:1> indicates a line of latitude.
• <geoloc:,-30> indicates a line of longitude.
• <geoloc:,,,,180> means the same thing as <geoloc:,,,,-180>: a direction of South.
• <geoloc:52,1,,100,,,,,,,,,,,,> means the same thing as <geoloc:52,1,,100>.

Implementations

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:

• If Google Earth is running it shifts its view to the indicated location
• Otherwise it tells your preferred browser to bring up a Google Map showing the location.

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.

Notes

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

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.