Description

The Geolocation API enables a web application to access the current geographical location of the device running the browser. Location information is returned in terms of latitude and longitude coordinates.

The API is designed to allow both "one-shot" position requests and repeated position updates. It also includes the ability to query cached positions.

This location information is obtained through a Global Positioning System (GPS) and/or a location inferred mechanism using network signals such as IP address, RFID, WiFi / Bluetooth MAC addresses, and GSM/CDMA cell IDs. The information could also be provided via user input.

Note: It is important to note that there is no guarantee that the API returns the device's actual location.

Note: When using the HTML5 Geolocation API, coordinates are always returned in decimal degrees.

HTML5 and HTML4.01 Differences

This API is new for HTML5.

Single Location Query

The "one-shot" API call has the form:

void getCurrentPosition(in PositionCallback successCallback,
  in optional PositionErrorCallback errorCallback,
  in optional PositionOptions options);

Parameters

Parameter	Description
successCallback	(required) Specifies which function to call when the location data is made available
errorCallback	Specifies which function to call when there is an error
options	Specifies additional options for changing the operation enableHighAccuracy: Request the HTML5 Geolocation service to use a higher accuracy-detection mode (default: false) timeout: Specifies (in milliseconds) the maximum amount of time allowed to calculate the current location. If the timeout is exceeded, the errorCallback function is called (default: infinity) maximumAge: Specifies (in milliseconds) how old a location value can be before the browser must attempt to recalculate (default: 0)

Repeated Location Query

The repeated update API call has the form:

void watchPosition(in PositionCallback successCallback,
  in optional PositionErrorCallback errorCallback);

Parameters

Parameter	Description
successCallback	(required) Specifies which function to call when the location data is made available
errorCallback	(required) Specifies which function to call when there is an error

To cancel the location updates, the API call has the form:

void clearWatch(in long watchID);

Parameters

Parameter	Description
watchID	(required) Specifies the unique ID of the watchPosition call to cancel. The ID is returned from the watchPosition call

Examples

The following example shows how to check for support of this API:

function loadDemo()
{
 if(navigator.geolocation) {
  document.getElementById("support").innerHTML="Geolocation supported";
 }
 else {
  document.getElementById("support").innerHTML="Geolocation not supported";
 }
}

window.addEventListener("load", loadDemo, true);

This code along with some HTML produces the following result:

This shows an example call to the "one-shot" API with an error handler and a 30 second timeout:

navigator.geolocation.getCurrentPosition(updateLocation, handleLocationError, {timeout:30000});

successCallback:

function updateLocation(position) {
  var latitude = position.coords.latitude;
  var longitude = position.coords.longitude;
  var accuracy = position.coords.accuracy;

  // do something with values
}

errorCallback:

function handleLocationError(error) {
switch(error.code) {
  case 0:
   // UNKNOWN_ERROR
   //Error retrieving location
   break;
  case 1:
   // PERMISSION_DENIED
   //User denied permission
   break;
  case 2:
   // POSITION_UNAVAILABLE
   //Location technique failed
  case 3:
    // TIMEOUT
    //Specified timeout reached
  break;
 }
}

This shows an example of the repeated update call using the callbacks in the previous example:

//create the watch
var watchId = navigator.geolocation.watchPosition(updateLocation, handleLocationError);

//process location updates

//cancel the updates
navigator.geolocation.clearWatch(watchId);

Browser Support

Chrome	Firefox	IE	Safari	Opera

Miscellaneous Information

Defined In:	HTML5