Cordova Geolocation Plugin

Location-aware features — maps, "find nearby," delivery tracking, check-ins — all start with the Geolocation plugin. Cordova's cordova-plugin-geolocation exposes the same navigator.geolocation API defined by the W3C Geolocation standard used in regular browsers, so if you've used geolocation on the web before, this will feel familiar. This page covers a one-time position read, the shape of the data you get back, continuously watching position changes, and the errors you need to handle.

Installing the Plugin

cordova plugin add cordova-plugin-geolocation

Once installed, navigator.geolocation is available globally in your app's JavaScript after deviceready fires.

Getting a One-Time Position

For a single read of the device's current location — "where is the user right now" — use navigator.geolocation.getCurrentPosition(successCallback, errorCallback, options). It's asynchronous: the device may need a moment to acquire a GPS or network-based fix before your success callback runs.

navigator.geolocation.getCurrentPosition(onSuccess, onError, {
    enableHighAccuracy: true,
    timeout: 10000,
    maximumAge: 0
});

function onSuccess(position) {
    console.log('Latitude: ' + position.coords.latitude);
    console.log('Longitude: ' + position.coords.longitude);
}

function onError(error) {
    console.log('Location error (' + error.code + '): ' + error.message);
}

The Position Object

The object passed to your success callback carries a nested coords object with the actual location data:

Useful Options

Watching Position Continuously

For features like live location tracking on a map, a single reading isn't enough — you need to know whenever the device moves. navigator.geolocation.watchPosition() takes the same arguments as getCurrentPosition(), but instead of firing once, it calls your success callback repeatedly as the device's position changes. It returns a watch ID that you must hold on to so you can stop watching later with navigator.geolocation.clearWatch(watchId) — forgetting to clear a watch keeps the GPS active and drains the battery even after your feature is no longer visible on screen.

var watchId = null;

function startWatch() {
    watchId = navigator.geolocation.watchPosition(onPositionUpdate, onWatchError, {
        enableHighAccuracy: true,
        timeout: 15000,
        maximumAge: 5000
    });
}

function onPositionUpdate(position) {
    console.log('Updated position: ' + position.coords.latitude + ', ' + position.coords.longitude);
}

function onWatchError(error) {
    console.log('Watch error: ' + error.message);
}

function stopWatch() {
    if (watchId !== null) {
        navigator.geolocation.clearWatch(watchId);
        watchId = null;
    }
}

Wire startWatch() to a "Start Tracking" button and stopWatch() to a "Stop Tracking" button, and you have a complete, safe start/stop location-watching feature that never leaves the GPS running unnecessarily.

Handling Location Errors

The error object passed to your error callback has a numeric code property. The Geolocation spec defines three possible values: