Geolocation
The
geolocationobject provides access to the device's GPS sensor.
Geolocation provides location information for the device, such as latitude and longitude. Common sources of location information include Global Positioning System (GPS) and location inferred from network signals such as IP address, RFID, WiFi and Bluetooth MAC addresses, and GSM/CDMA cell IDs. No guarantee is given that the API returns the device's actual location.
This API is based on the W3C Geo location API Specification. Some devices already provide an implementation of this spec. For those devices, the built-in support is used instead of replacing it with PhoneGap's implementation. For devices that don't have geolocation support, PhoneGap's implementation should be compatible with the W3C specification.
Methods
Arguments
Objects (Read-Only)
geolocation.getCurrentPosition
Returns the device's current position as a Position object.
navigator.geolocation.getCurrentPosition(geolocationSuccess,
[geolocationError],
[geolocationOptions]);
Parameters
- geolocationSuccess: The callback that is called with the current position.
- geolocationError: (Optional) The callback that is called if there was an error.
- geolocationOptions: (Optional) The geolocation options.
Description
Function geolocation.getCurrentPositon is an asynchronous function. It returns the device's current position to the geolocationSuccess callback with a Position object as the parameter. If there is an error, the geolocationError callback is invoked with a PositionError object.
Supported Platforms
- Android
- BlackBerry (OS 4.6)
- BlackBerry Widgets (OS 5.0 and higher)
- iPhone
Quick Example
// onSuccess Callback
// This method accepts a `Position` object, which contains
// the current GPS coordinates
//
var onSuccess = function(position) {
alert('Latitude: ' + position.coords.latitude + '\n' +
'Longitude: ' + position.coords.longitude + '\n' +
'Altitude: ' + position.coords.altitude + '\n' +
'Accuracy: ' + position.coords.accuracy + '\n' +
'Altitude Accuracy: ' + position.coords.altitudeAccuracy + '\n' +
'Heading: ' + position.coords.heading + '\n' +
'Speed: ' + position.coords.speed + '\n' +
'Timestamp: ' + new Date(position.timestamp) + '\n');
};
// onError Callback receives a PositionError object
//
function onError(error) {
alert('code: ' + error.code + '\n' +
'message: ' + error.message + '\n');
}
navigator.geolocation.getCurrentPosition(onSuccess, onError);
Full Example
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Device Properties Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Wait for PhoneGap to load
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap is ready
//
function onDeviceReady() {
navigator.geolocation.getCurrentPosition(onSuccess, onError);
}
// onSuccess Geolocation
//
function onSuccess(position) {
var element = document.getElementById('geolocation');
element.innerHTML = 'Latitude: ' + position.coords.latitude + '<br />' +
'Longitude: ' + position.coords.longitude + '<br />' +
'Altitude: ' + position.coords.altitude + '<br />' +
'Accuracy: ' + position.coords.accuracy + '<br />' +
'Altitude Accuracy: ' + position.coords.altitudeAccuracy + '<br />' +
'Heading: ' + position.coords.heading + '<br />' +
'Speed: ' + position.coords.speed + '<br />' +
'Timestamp: ' + new Date(position.timestamp) + '<br />';
}
// onError Callback receives a PositionError object
//
function onError(error) {
alert('code: ' + error.code + '\n' +
'message: ' + error.message + '\n');
}
</script>
</head>
<body onload="onLoad()">
<p id="geolocation">Finding geolocation...</p>
</body>
</html>
geolocation.watchPosition
Watches for changes to the device's current position.
var watchId = navigator.geolocation.watchPosition(geolocationSuccess,
[geolocationError],
[geolocationOptions]);
Parameters
- geolocationSuccess: The callback that is called with the current position.
- geolocationError: (Optional) The callback that is called if there was an error.
- geolocationOptions: (Optional) The geolocation options.
Returns
-
String: returns a watch id that references the watch position interval. The watch id can be used with
geolocation.clearWatchto stop watching for changes in position.
Description
Function geolocation.watchPosition is an asynchronous function. It returns the device's current position when a change in position has been detected. When the device has retrieved a new location, the geolocationSuccess callback is invoked with a Position object as the parameter. If there is an error, the geolocationError callback is invoked with a PositionError object.
Supported Platforms
- Android
- BlackBerry (OS 4.6)
- BlackBerry Widgets (OS 5.0 and higher)
- iPhone
Quick Example
// onSuccess Callback
// This method accepts a `Position` object, which contains
// the current GPS coordinates
//
function onSuccess(position) {
var element = document.getElementById('geolocation');
element.innerHTML = 'Latitude: ' + position.coords.latitude + '<br />' +
'Longitude: ' + position.coords.longitude + '<br />' +
'<hr />' + element.innerHTML;
}
// onError Callback receives a PositionError object
//
function onError(error) {
alert('code: ' + error.code + '\n' +
'message: ' + error.message + '\n');
}
// Options: retrieve the location every 3 seconds
//
var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { frequency: 3000 });
Full Example
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Device Properties Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Wait for PhoneGap to load
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
var watchID = null;
// PhoneGap is ready
//
function onDeviceReady() {
// Update every 3 seconds
var options = { frequency: 3000 };
watchID = navigator.geolocation.watchPosition(onSuccess, onError, options);
}
// onSuccess Geolocation
//
function onSuccess(position) {
var element = document.getElementById('geolocation');
element.innerHTML = 'Latitude: ' + position.coords.latitude + '<br />' +
'Longitude: ' + position.coords.longitude + '<br />' +
'<hr />' + element.innerHTML;
}
// onError Callback receives a PositionError object
//
function onError(error) {
alert('code: ' + error.code + '\n' +
'message: ' + error.message + '\n');
}
</script>
</head>
<body onload="onLoad()">
<p id="geolocation">Watching geolocation...</p>
</body>
</html>
geolocation.clearWatch
Stop watching for changes to the device's location referenced by the watchID parameter.
navigator.geolocation.clearWatch(watchID);
Parameters
-
watchID: The id of the
watchPositioninterval to clear. (String)
Description
Function geolocation.clearWatch stops watching changes to the device's location by clearing the geolocation.watchPosition referenced by watchID.
Supported Platforms
- Android
- BlackBerry (OS 4.6)
- BlackBerry Widgets (OS 5.0 and higher)
- iPhone
Quick Example
// Options: retrieve the location every 3 seconds
//
var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { frequency: 3000 });
// ...later on...
navigator.geolocation.clearWatch(watchID);
Full Example
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Device Properties Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Wait for PhoneGap to load
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
var watchID = null;
// PhoneGap is ready
//
function onDeviceReady() {
// Update every 3 seconds
var options = { frequency: 3000 };
watchID = navigator.geolocation.watchPosition(onSuccess, onError, options);
}
// onSuccess Geolocation
//
function onSuccess(position) {
var element = document.getElementById('geolocation');
element.innerHTML = 'Latitude: ' + position.coords.latitude + '<br />' +
'Longitude: ' + position.coords.longitude + '<br />' +
'<hr />' + element.innerHTML;
}
// clear the watch that was started earlier
//
function clearWatch() {
if (watchID != null) {
navigator.geolocation.clearWatch(watchID);
watchID = null;
}
}
// onError Callback receives a PositionError object
//
function onError(error) {
alert('code: ' + error.code + '\n' +
'message: ' + error.message + '\n');
}
</script>
</head>
<body onload="onLoad()">
<p id="geolocation">Watching geolocation...</p>
<button onclick="clearWatch();">Clear Watch</button>
</body>
</html>
Coordinates
A set of properties that describe the geographic coordinates of a position.
Properties
- latitude: Latitude in decimal degrees. (Number)
- longitude: Longitude in decimal degrees. (Number)
- altitude: Height of the position in meters above the ellipsoid. (Number)
- accuracy: Accuracy level of the latitude and longitude coordinates in meters. (Number)
- altitudeAccuracy: Accuracy level of the altitude coordinate in meters. (Number)
- heading: Direction of travel, specified in degrees counting clockwise relative to the true north. (Number)
- speed: Current ground speed of the device, specified in meters per second. (Number)
Description
The Coordinates object is created and populated by PhoneGap, and attached to the Position object. The Position object is then returned to the user through a callback function.
Supported Platforms
- Android
- BlackBerry (OS 4.6)
- BlackBerry Widgets (OS 5.0 and higher)
- iPhone
Quick Example
// onSuccess Callback
//
var onSuccess = function(position) {
alert('Latitude: ' + position.coords.latitude + '\n' +
'Longitude: ' + position.coords.longitude + '\n' +
'Altitude: ' + position.coords.altitude + '\n' +
'Accuracy: ' + position.coords.accuracy + '\n' +
'Altitude Accuracy: ' + position.coords.altitudeAccuracy + '\n' +
'Heading: ' + position.coords.heading + '\n' +
'Speed: ' + position.coords.speed + '\n' +
'Timestamp: ' + new Date(position.timestamp) + '\n');
};
// onError Callback
//
var onError = function() {
alert('onError!');
};
navigator.geolocation.getCurrentPosition(onSuccess, onError);
Full Example
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Geolocation Position Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Set an event to wait for PhoneGap to load
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap is loaded and Ready
//
function onDeviceReady() {
navigator.geolocation.getCurrentPosition(onSuccess, onError);
}
// Display `Position` properties from the geolocation
//
function onSuccess(position) {
var div = document.getElementById('myDiv');
div.innerHTML = 'Latitude: ' + position.coords.latitude + '<br/>' +
'Longitude: ' + position.coords.longitude + '<br/>' +
'Altitude: ' + position.coords.altitude + '<br/>' +
'Accuracy: ' + position.coords.accuracy + '<br/>' +
'Altitude Accuracy: ' + position.coords.altitudeAccuracy + '<br/>' +
'Heading: ' + position.coords.heading + '<br/>' +
'Speed: ' + position.coords.speed + '<br/>';
}
// Show an alert if there is a problem getting the geolocation
//
function onError() {
alert('onError!');
}
</script>
</head>
<body onload="onLoad()">
<div id="myDiv"></div>
</body>
</html>
Android Quirks
altitudeAccuracy: This property is not support by Android devices, it will always return null.
Position
Contains Position coordinates that are created by the geolocation API.
Properties
- coords: A set of geographic coordinates. (Coordinates)
-
timestamp: Creation timestamp for
coordsin milliseconds. (DOMTimeStamp)
Description
The Position object is created and populated by PhoneGap, and returned to the user through a callback function.
Supported Platforms
- Android
- BlackBerry (OS 4.6)
- BlackBerry Widgets (OS 5.0 and higher)
- iPhone
Quick Example
// onSuccess Callback
//
var onSuccess = function(position) {
alert('Latitude: ' + position.coords.latitude + '\n' +
'Longitude: ' + position.coords.longitude + '\n' +
'Altitude: ' + position.coords.altitude + '\n' +
'Accuracy: ' + position.coords.accuracy + '\n' +
'Altitude Accuracy: ' + position.coords.altitudeAccuracy + '\n' +
'Heading: ' + position.coords.heading + '\n' +
'Speed: ' + position.coords.speed + '\n' +
'Timestamp: ' + new Date(position.timestamp) + '\n');
};
// onError Callback receives a PositionError object
//
function onError(error) {
alert('code: ' + error.code + '\n' +
'message: ' + error.message + '\n');
}
navigator.geolocation.getCurrentPosition(onSuccess, onError);
Full Example
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Device Properties Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Wait for PhoneGap to load
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap is ready
//
function onDeviceReady() {
navigator.geolocation.getCurrentPosition(onSuccess, onError);
}
// onSuccess Geolocation
//
function onSuccess(position) {
var element = document.getElementById('geolocation');
element.innerHTML = 'Latitude: ' + position.coords.latitude + '<br />' +
'Longitude: ' + position.coords.longitude + '<br />' +
'Altitude: ' + position.coords.altitude + '<br />' +
'Accuracy: ' + position.coords.accuracy + '<br />' +
'Altitude Accuracy: ' + position.coords.altitudeAccuracy + '<br />' +
'Heading: ' + position.coords.heading + '<br />' +
'Speed: ' + position.coords.speed + '<br />' +
'Timestamp: ' + new Date(position.timestamp) + '<br />';
}
// onError Callback receives a PositionError object
//
function onError(error) {
alert('code: ' + error.code + '\n' +
'message: ' + error.message + '\n');
}
</script>
</head>
<body onload="onLoad()">
<p id="geolocation">Finding geolocation...</p>
</body>
</html>
iPhone Quirks
- timestamp: Uses seconds instead of milliseconds.
A workaround is to manually convert the timestamp to milliseconds (x 1000):
var onSuccess = function(position) {
alert('Latitude: ' + position.coords.latitude + '\n' +
'Longitude: ' + position.coords.longitude + '\n' +
'Timestamp: ' + new Date(position.timestamp * 1000) + '\n');
};
PositionError
A PositionError object is returned to the geolocationError callback when an error occurs.
Properties
- code: One of the predefined error codes listed below.
- message: Error message describing the details of the error encountered.
Constants
PositionError.PERMISSION_DENIEDPositionError.POSITION_UNAVAILABLEPositionError.TIMEOUT
Description
The PositionError object is returned to the user through the geolocationError callback function when an error occurs with geolocation.
geolocationSuccess
The user's callback function that is called when a geolocation position is available.
function(position) {
// Do something
}
Parameters
-
position: The geolocation position returned by the device. (
Position)
Example
function geolocationSuccess(position) {
alert('Latitude: ' + position.coords.latitude + '\n' +
'Longitude: ' + position.coords.longitude + '\n' +
'Altitude: ' + position.coords.altitude + '\n' +
'Accuracy: ' + position.coords.accuracy + '\n' +
'Altitude Accuracy: ' + position.coords.altitudeAccuracy + '\n' +
'Heading: ' + position.coords.heading + '\n' +
'Speed: ' + position.coords.speed + '\n' +
'Timestamp: ' + new Date(position.timestamp) + '\n');
}
geolocationError
The user's callback function that is called when there is an error for geolocation functions.
function(error) {
// Handle the error
}
Parameters
-
error: The error returned by the device. (
PositionError)
geolocationOptions
Optional parameters to customize the retrieval of the geolocation.
{ maximumAge: 3000, timeout: 5000, enableHighAccuracy: true };
Options
- frequency: How often to retrieve the position in milliseconds. This option is not part of the W3C spec and will be removed in the future. maximumAge should be used instead. (Number) (Default: 10000)
- enableHighAccuracy: Provides a hint that the application would like to receive the best possible results. (Boolean)
-
timeout: The maximum length of time (msec) that is allowed to pass from the call to
geolocation.getCurrentPositionorgeolocation.watchPositionuntil the correspondinggeolocationSuccesscallback is invoked. (Number) - maximumAge: Accept a cached position whose age is no greater than the specified time in milliseconds. (Number)
Android Quirks
The Android 2.x simulators will not return a geolocation result unless the enableHighAccuracy option is set to true.
{ enableHighAccuracy: true }