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:
Geolocation not supported
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 |
---|