📍

Geolocation

cordova-plugin-geolocation

iOS Android 🌐 Browser

This official Apache Cordova plugin reads the device's current GPS position and lets you subscribe to location changes as the user moves. Its interface mirrors the W3C Geolocation API, so the methods and the data they return will feel familiar if you have used geolocation in the browser.

Installation

Add the plugin to your Cordova project from the command line:

terminal

cordova plugin add cordova-plugin-geolocation

Methods

The plugin attaches its methods to navigator.geolocation. Call them after the deviceready event has fired:

Method	Description
`navigator.geolocation.getCurrentPosition(success, error, options)`	Fetches a single, one-shot reading of the device's current position.
`navigator.geolocation.watchPosition(success, error, options)`	Returns a watch id and keeps calling `success` each time the device moves.
`navigator.geolocation.clearWatch(watchId)`	Stops the active watch identified by `watchId`.

The position object

The success callback receives a position object whose location data lives under coords:

Property	Type	Description
`coords.latitude`	Number	Latitude in decimal degrees.
`coords.longitude`	Number	Longitude in decimal degrees.
`coords.altitude`	Number	Height above sea level in metres.
`coords.accuracy`	Number	Accuracy of the latitude and longitude, in metres.
`coords.altitudeAccuracy`	Number	Accuracy of the altitude reading, in metres.
`coords.heading`	Number	Direction of travel in degrees, measured clockwise from north.
`coords.speed`	Number	Current ground speed in metres per second.
`timestamp`	Number	When the reading was taken, as a millisecond timestamp.

Options

Pass an options object to tune how the position is read:

Property	Type	Description
`enableHighAccuracy`	Boolean	Request the most precise fix the device can provide.
`timeout`	Number	How long, in milliseconds, to wait for a reading before failing.
`maximumAge`	Number	Accept a cached fix up to this many milliseconds old.

Usage example

Read the device's current location once and log the coordinates:

www/js/app.js

navigator.geolocation.getCurrentPosition(onSuccess, onError, {
  enableHighAccuracy: true
});

function onSuccess(position) {
  console.log("Lat: " + position.coords.latitude);
  console.log("Lng: " + position.coords.longitude);
}

function onError(error) {
  console.log("Code: " + error.code);
  console.log("Message: " + error.message);
}

Tips

Register location calls inside deviceready — the plugin isn't available before then.
High-accuracy fixes drain more battery, so only enable them when you really need precision.
Always call clearWatch when leaving a screen so the GPS keeps running no longer than necessary.
On Android 6 and later, and on iOS, the OS asks the user for location permission at runtime.

📚 Source: the technical reference on this page (the methods, the position object and the install command) is based on the official Apache Cordova geolocation documentation. Descriptions and examples have been rewritten in DedrisFramework's own words. Apache Cordova documentation is published by the Apache Software Foundation under the Apache License 2.0.

← Back to plugins Start a project