Oh browser, where art thou

The Geolocation API gives us access to the users position from JavaScript. When called the browser will ask the user for permission, retrieve the position from GPS, Wi-Fi, IP address or anything else it has available and return it. The API is supported in all current browsers. Just be aware that Internet Explorer require you to use a proper doctype. Note that the Geolocation API is not part of HTML5 even though it is often discussed alongside it.

I have created an example page where you can see how it works from a user perspective and see what your browser returns.

The geolocation object

Before you can use geolocation you must make sure that the browser supports it.

if (navigator.geolocation) {
  // Geolocation is supported
}
else {
  // Geolocation is NOT supported
}

Then you can ask for the user’s position with the following call.

navigator.geolocation.getCurrentPosition(
  function (position) {
    // Use the position data
  },
  function (error) {
    switch (error.code) {
      case 1:
        // Permission was denied
        break;
      case 2:
        // Position was not available
        break;
      case 3:
        // Position request timed out
        break;
      default:
        // Unknown error
        break;
    }
  },
  { enableHighAccuracy: true, maximumAge: 0, timeout: 60000 });

This asks for a high accuracy position fix that has not been cached with a timeout of one minute. We will look at what is returned in the position object soon. If you need to continuously update the user’s position you can use the following call instead.

var watchId = navigator.geolocation.watchPosition(
  function (position) {
    // Use the position data
  });
 
// When you are done
navigator.geolocation.clearWatch(watchId);

The watchPosition method takes the same parameters as the getCurrentPosition method. Here I have only given it a function to call on success which is the only argument that is required (for both methods). With the watchPosition method the browser will call our function whenever the position changes until we tell it to stop.

The position object

The position object that is returned has the following data.

position.timestamp;               // Milliseconds since 1 January 1970
position.coords.latitude;         // Decimal degrees (WGS84)
position.coords.longitude;        // Decimal degrees (WGS84)
position.coords.accuracy;         // Decimal meters, 95% confidence level
position.coords.altitude;         // Decimal meters above the WGS84 ellipsoid
position.coords.altitudeAccuracy; // Decimal meters, 95% confidence level
position.coords.speed;            // Decimal meters per second
position.coords.heading;          // Decimal degrees from true north clockwise

All decimal values are of type double. Only the timestamp, latitude, longitude and accuracy are guaranteed to be returned. But if the altitude is returned then the altitude accuracy must also be present. This is according to the specification, real browsers may behave otherwise. Values that are not provided may be 0, NaN or null.

Gecko browsers (i.e. Firefox) will also return the user’s address.

position.address.premises;
position.address.street;
position.address.streetNumber;
position.address.postalCode;
position.address.city;
position.address.region;
position.address.county;
position.address.country;
position.address.countryCode;

All address values are of type string.