cordova-plugin-geolocation: the W3C geolocation API for Cordova apps

A browser API that a webview would not otherwise have

The plugin provides information about the device's location, such as latitude and longitude, and it does so by defining a global navigator.geolocation object for platforms where it is otherwise missing. The API is based on the W3C Geolocation API Specification, which is the point of the design. A Cordova application is a webview, and a webview on a phone may or may not ship with a geolocation implementation, so the plugin provides the standard one, with the standard method names, the standard callback shape and the standard error codes. For a developer moving code from a browser to a hybrid app, that means the geolocation calls in the application do not change. The plugin also lists the objects it exposes as read-only, which are Position, PositionError and Coordinates, and the three methods are getCurrentPosition, watchPosition and clearWatch. The intended audience is Cordova and Ionic developers building an application that needs to know where the user is, from a nearby search to a delivery estimate to a geotagged photo.

Nothing works until deviceready fires

There is a caveat that catches out everybody once. Although the object is in the global scope, features provided by this plugin are not available until after the deviceready event. The documentation shows the shape of the guard:

    document.addEventListener("deviceready", onDeviceReady, false);
    function onDeviceReady() {
        console.log("navigator.geolocation works well");
    }

The reason is the Cordova architecture rather than the plugin. In a hybrid application the JavaScript bundle is loaded before the native side has finished loading, so the geolocation methods that depend on the native implementation are not yet able to answer. Calling them earlier either does nothing or throws, depending on the platform, and both outcomes are hard to debug because the error surfaces far from the cause. The practical rule is that any code touching the position has to live inside the deviceready handler or run after it, and the position itself is still a future, so the callback pattern is unavoidable. That is a design constraint of the platform rather than a defect in this plugin, and it is worth knowing before you write the code, not after.

Installing the plugin, and the two legacy routes

Installation is a single command, and the README notes that it requires cordova 5.0 or later:

    cordova plugin add cordova-plugin-geolocation

There are two alternatives for older projects, and the documentation is candid about their status. The deprecated plugin id, which is stale at 0.3.12, still installs on older versions of Cordova:

    cordova plugin add org.apache.cordova.geolocation

and installing straight from the repository URL is possible but marked unstable:

    cordova plugin add https://github.com/apache/cordova-plugin-geolocation.git

The distinction between the current id and the deprecated one is the kind of detail that causes silent version confusion, since an application that still refers to the old id keeps an old copy of the plugin with old behaviour and no obvious error. The manifest gives the compatibility rules in a more precise form than the prose does, with a cordovaDependencies table that maps platform versions to the plugin, the 3.0.0 line needs cordova-android 6.3.0 or later, while the 5.0.0 line needs cordova-android 10.0.0 and cordova-ios 6.0.0 or later, matching the supported platforms list.

Getting a position, and what the callbacks receive

The core call is getCurrentPosition, which returns the device's current position to the geolocationSuccess callback with a Position object. If there is an error, the geolocationError callback is passed a PositionError object, and the geolocationOptions parameter is optional. The signature in the documentation is deliberately the browser one:

    navigator.geolocation.getCurrentPosition(geolocationSuccess,
                                             [geolocationError],
                                             [geolocationOptions]);

The example in the README shows what a caller does with the result, reading latitude, longitude, altitude, accuracy, altitudeAccuracy, heading, speed and the timestamp from the position, and the error callback prints the code and the message. The reason the position object carries so many fields is that a phone rarely has a single clean answer to where the user is. The value comes from a network signal, from WiFi, from the cell tower, or from the satellite receiver, and the accuracy field tells the application how much to trust the rest. The README makes the corresponding point about the data itself, listing GPS and location inferred from network signals such as IP address, RFID, WiFi and Bluetooth MAC addresses, and GSM and CDMA cell identifiers, and then saying plainly that there is no guarantee the API returns the device's actual location.

The iOS usage description or a crash

The iOS quirks section contains the single most important operational fact in the documentation. Since iOS 10 it is mandatory to provide a usage description in the info.plist if you are trying to access privacy-sensitive data. The usage description string is displayed as part of the system permission dialog, and if you did not provide it, the app will crash before showing the dialog. Apple will also reject applications that access private data without a usage description, so this is a build and review problem as well as a runtime one. The plugin requires two of them. NSLocationWhenInUseUsageDescription describes the reason the app accesses the user's location, and is used while the app is running in the foreground. NSLocationAlwaysAndWhenInUseUsageDescription covers the other case. Getting this wrong produces a crash on launch with no permission prompt, which is the worst possible failure mode for a developer who is testing on a device for the first time, because the app never gets far enough to ask.

Geolocation data is sensitive, and the plugin says so

The README carries a warning block about collection and use of geolocation data, and it is unusually specific. Your app's privacy policy should discuss how the app uses geolocation data, whether it is shared with any other parties, and the level of precision of the data, coarse, fine or ZIP code level for example. The reasoning given is that geolocation data is generally considered sensitive because it can reveal the user's whereabouts and, if stored, the history of their travels. The recommendation is to provide a just-in-time notice before the app accesses geolocation data, in addition to the privacy policy, unless the operating system already does so, and that notice should carry the same information plus obtain the user's permission, presented as choices such as OK and No Thanks. The plugin links the Cordova privacy guide for the longer version of the argument. For an engineer this is a checklist item before the first release rather than a philosophical point, since store review and privacy policies are where a geolocation feature usually stalls.

Platform coverage, maintenance and the project layout

The supported platforms list is short. Android 10.0.0 or later and iOS 6.0.0 or later, while the manifest lists the plugin as usable on android, ios and windows, and the badges show test suites for Android, iOS and Chrome alongside a lint workflow. The repository is an Apache Software Foundation project with the usual Apache layout, a NOTICE file, a licence_checker.yml, a CONTRIBUTING.md and RELEASENOTES.md, plus plugin.xml, the src/ directory for the JavaScript implementation and www/ for the web facing side. The package version in the manifest is 5.0.1-dev, and the licence is Apache-2.0, with the copyright held by the Apache Software Foundation. On maintenance, the repository publishes no GitHub releases, so RELEASENOTES.md in the tree is the version history, and the last push to the master branch was on 2026-07-27. The home page is the Cordova site, cordova.apache.org, and the topics list hacktoberfest, which is consistent with a plugin that takes outside contributions.

Editorial conclusion

cordova-plugin-geolocation suits a Cordova or Ionic application that needs a one-off position or a continuous watch and wants the familiar browser API rather than a native plugin of its own. It is the wrong tool if you need background tracking while the app is closed, since the plugin exposes only the foreground API, and it is unusable on iOS until the usage description strings are in the info.plist, because the app crashes before the permission dialog appears. Before you add it, confirm your Cordova platform versions meet the manifest's minimums, cordova-android 10.0.0 and cordova-ios 6.0.0, and write the privacy notice the plugin's own documentation asks for, since the position data it returns is sensitive by nature.

Frequently asked questions

Official sources

1. apache/cordova-plugin-geolocation on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README