Cordova Plugin Geolocation

The Geolocation plugin is used to determine the device location in terms of latitude and longitude. It offers the common sources of location information including GPS location and the network signals i.e., IP address, WiFi, Bluetooth, MAC addresses, RFID, and GSM/CDMA cell IDs. It should be noted that there is no guarantee of getting the actual device location.

Basically, the plugin API is based on standard W3C Geolocation API Specification. It will be executed only on the specific devices that don't already provide an implementation.

A global navigator.geolocation object is defined by this plugin (for platforms where it is missing). If it is in the global scope, in spite, this plugin is not available until after the deviceready event. This plugin is supported in various platforms such as iOS, Android, Windows.

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

Installation:

If you want to add this plugin in your app, you have to install it. The below command is applied for the cordova 5.0+ version.

cordova plugin add cordova-plugin-geolocation

If you have an older version of Cordova installed, you can still install this plugin via the deprecated id.

cordova plugin add org.apache.cordova.geolocation

We can also install the plugin via repo url directly:

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

Methods:

There are various methods used in the geolocation plugin, which are as follows:

geolocation.getCurrentPosition
geolocation.watchPosition
geolocation.clearWatch

navigator.geolocation.getCurrentPosition:

By using this method, the current position of the device is returned to the geolocationSuccess callback with a Position object passed as the parameter.

If in case any error is encountered, then the geolocationError callback pass a PositionError object

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

Parameters:

geolocationSuccess: It is a callback method that is passed as a parameter. It passes the current position.

geolocationError (optional): It is a callback method that is passed as a parameter. It executes when any error is encountered.

geolocationOptions (optional): It is used to refer the geolocation options.

Example:

    // This method accepts the Position object, which contains current GPS coordinates
    var onSuccess = function(position) {
        alert('Latitude: '          + position.coords.latitude          + '\n' +
              'Longitude: '         + position.coords.longitude         + '\n' +
              'Altitude: '          + position.coords.altitude          + '\n' +
              'Timestamp: '         + position.timestamp                + '\n');
              'Accuracy: '          + position.coords.accuracy          + '\n' +
              'Altitude Accuracy: ' + position.coords.altitudeAccuracy  + '\n' +
              'Heading: '           + position.coords.heading           + '\n' +
              'Speed: '             + position.coords.speed             + '\n' +
    };
    // When any error is encountered, onError Callback receives a PositionError object
    function onError(error) {
        alert('code: '    + error.code    + '\n' +
                   'message: ' + error.message + '\n');
    }
    navigator.geolocation.getCurrentPosition(onSuccess, onError);

navigator.geolocation.watchPosition

This method is used to return the current position of the device when any change is detected in the position. If a new device location is retrieved, then the geolocationSuccess callback method is executed in which Position object is passed as a parameter.

If any error is encountered, then the geolocationError callback method is executed with PositionError object passed as a parameter.

var watchId = navigator.geolocation.watchPosition(geolocationSuccess,
                                                  [geolocationError],
                                                  [geolocationOptions]);

Parameters:

geolocationSuccess: It is a callback method that is passed as a parameter. It passes the current position.

geolocationError (optional): It is a callback method that is passed as a parameter. It executes when any error is encountered.

geolocationOptions (optional): It is used to refer the geolocation options.

Returns

String: A watch id is being returned that provide a reference to the watch position interval. To stop watching for changes in the position, the watch id should be used with navigator.geolocation.clearWatch.

Example:

     //   onSuccess method accepts position object that contains 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;
    }
    // When any error is encountered, onError Callback receives a PositionError object
    function onError(error) {
        alert('code: '    + error.code    + '\n' +
              'message: ' + error.message + '\n');
    }
    // Options: It throws an error if no update is received in every 50 seconds.
    var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { timeout: 50000 });

geolocationOptions:

It is an optional parameter that customizes the retrieval of the Position object.

{ maximumAge: 2000, timeout: 6000, enableHighAccuracy: true };

Options:

enableHighAccuracy: By using this option, we get a hint for an application to get the best possible results. By default, the network-based methods are attempted by the device to retrieve the Position object. To use more accurate methods, we have to set the property to true.

timeout: This option refers to the maximum time length allowed to pass from the call to navigator.geolocation.getCurrentPosition or geolocation.watchposition until execute the corresponding geolocationSuccess callback. The PositionError.TIMEOUT error code is passed from the geolocationError callback method when the geolocationSuccess callback method is not invoked within the specified time.

maximumAge: It refers to a number that accepts a cached position whose age should not be greater than the specified time represented in milliseconds.

navigator.gelocation.clearWatch

It is an option that has the main task to stop watching for any change to the device's location referenced by watchID parameter.

Parameters:

watchID: To clear the watchPosition interval, we need its id. This parameter refers to a string value that contains this particular id.

Example:

    // Watch for the changes in position
   // use the available method that have most accurate position acquisition method available.
    var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { enableHighAccuracy: true });
    // some code
    navigator.geolocation.clearWatch(watchID);

Position:

It mainly refers the position coordinates and the timestamp created by the geolocation API.

Properties

coords: Refers the set of geographic coordinates.

timestamp: It creates the timestamp for the coords.

Coordinates

It is an object that is attached with a Position object. In request for the current position, it is available to callback functions. For defining the position's geographic coordinates, it includes a set of properties that are as follows:

Properties:

latitude: It consists a number value that defines the latitude of the position represented in decimal degrees.

longitude: It consists a number value that defines the longitude of the position represented in decimal degrees.

altitude: It defines the height of the position above the ellipsoid represented in meters.

accuracy: It is used to define the accuracy level of the coordinates of latitude and longitude. It is represented in meters.

altitudeAccuracy: It mainly defines the accuracy level of the altitude coordinates. It is represented in meters.

heading: It represents the direction of the travel. It is specified in degrees that count clockwise relative to the true north.

speed: It refers a number value that defines the current ground speed of the device. Specified in meters per second.

PositionError

When any error is encountered with navigator.geolocation, the PositionError object is passed to geolocationError callback function.

Properties

message: It defines the error message.

code: It is one of the predefined error code.

Constants:

PositionError.PERMISSION_DENIED:

When the users do not want to allow an app to retrieve the information of position, it is returned. Basically, it mainly depends on the platform.

PositionError.POSITION_UNAVAILABLE:

When the device is not connected to the network, or can't get the satellite fix, the device becomes unavailable to retrieve the position and returned this.

PositionError.TIMEOUT

When the device is unable to retrieve the position within the time specified by the timeout (included in geolocationOptions), this error will returned. This error can be repeatedly passed to the geolocationError callback in every timeout milliseconds, when used with navigator.geolocation.watchPosition.

Next TopicCordova Plugin Vibration

← prev next →