Geolocation

The geolocation object 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 WebWorks (OS 5.0 and higher)
iPhone
Windows Phone 7 ( Mango )

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>
<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
    //
    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>
    <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.clearWatch to 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 WebWorks (OS 5.0 and higher)
iPhone
Windows Phone 7 ( Mango )

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>
<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
    //
    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>
    <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 watchPosition interval 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 WebWorks (OS 5.0 and higher)
iPhone
Windows Phone 7 ( Mango )

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>
<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
    //
    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>
    <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 WebWorks (OS 5.0 and higher)
iPhone
Windows Phone 7 ( Mango )

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>
<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
    //
    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>
    <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 coords in 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 WebWorks (OS 5.0 and higher)
iPhone
Windows Phone 7 ( Mango )

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>
<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
    //
    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>
    <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_DENIED
PositionError.POSITION_UNAVAILABLE
PositionError.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.getCurrentPosition or geolocation.watchPosition until the corresponding geolocationSuccess callback 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 }

Geolocation

API Reference

Guides