Ed Spencer is a developer for ExtJS.

One of the more immediately useful components of HTML5 is Geolocation. Various imprecise forms of geolocation have been in use on the web for some time, usually in the form of a crude best-guess based on your IP address. Today we have a plethora of new location-aware devices using a variety of location sensing techniques. The HTML5 Geolocation API provides a way to find a device's location without caring how that information is discovered.

The first thing to say about HTML5 Geolocation is that the spec is a working draft and may be subject to change. Support is already in Firefox 3.5+, Safari 5+, Chrome 5+ and Opera 10+. Thankfully, detecting support for it is easy:

if (navigator.geolocation) {
  // do your magic
} else {
  // geolocation is not available... have you considered a forward-thinking browser?
}

With that caveat out of the way, let's take a look at how we can use it. Geolocation has two main modes of operation -- "one-shot" mode and continuous update mode. Both modes are asynchronous and accept a callback -- here's how we might use one-shot mode to fetch nearby tweets from Twitter:

// our callback function, let's fetch some nearby tweets:
function fetchTweets(position) {
  alert("Fetch tweets from " + position.coords.latitude + ", " + position.coords.longitude);

  // use JSONP to fetch local tweets from twitter
};

// get the location
navigator.geolocation.getCurrentPosition(fetchTweets);

The implementation of getting the tweets from Twitter's API is left to the reader but given the coords object it is a relatively simple operation.

A More Complete Example

We have a couple of additional options -- we can provide an error callback if the device's location could not be found for some reason, and an options object giving the geolocation some constraints:

function locationNotFound() {
  alert("Oh noes! We couldn't find you");
};

var options = {
  timeout: 10000,
  maximumAge: 20000,
  enableHighAccuracy: true
};

navigator.geolocation.getCurrentPosition(fetchTweets, locationNotFound, options);

The options object API is straightforward: maximumAge tells the browser that if the last location was found less than 20 seconds ago, we will reuse it; otherwise find the location again. The timeout option tells the browser that it should only wait 10 seconds for a location fix before calling the error callback. Finally, enableHighAccuracy is a hint to the browser that we'd like the most accurate location it can give us. The effect of this will vary between devices but usually involves a trade-off, where increased accuracy is paid for with slower response time.

Our success callback is always called with a single object that contains two properties: coords and timestamp. The timestamp is the time that the location was discovered, and coords is the object we used in our fetchTweets function above. As well as latitude and longitude (in degrees), devices may provide altitude (in meters above the reference ellipsoid), the accuracy (in meters) of the latitude and longitude, altitudeAccuracy (again in meters), heading (in degrees relative to true north) and speed (in meters per second).

The error callback gets a much simpler object consisting of a code number and a message string. The code tells the application whether the request failed due to lack of user permission, because the geolocation hardware couldn't find its position or because the operation timed out.

Continuous Updates

The second way to interact with HTML5 Geolocation is through the watchPosition API. Its signature is identical to getCurrentPosition, as are the objects passed to the success and error callbacks that you provide. The only difference is that your success callback will be called every time the device detects that its location has changed. When you no longer need to receive these updates just use the clearWatch function:

//start continuous watching
var watchId = navigator.geolocation.watchPosition(fetchTweets, locationNotFound, options);

//stop watching for updates
navigator.geolocation.clearWatch(watchId);

HTML5 Geolocation is a young but promising part of HTML5 with a large number of potential applications. It's currently in last call status in the W3C, but seems reasonably settled.