# Location

Geolocation operations.

# Manifest Declaration

You need to declare the use of this API in the manifest's features member:

{"name": "system.geolocation"}

# Module Import

Before using this service in a component, you need to import the module in the script section of the UX document.

import geolocation from '@system.geolocation' 

Or

let geolocation = require("@system.geolocation")

World Geodetic System

This service uses World Geodetic System (WGS) coordinates in the version WGS 84 (opens new window).

# Methods

This service has the following methods:

# getLocation({timeout,success,fail,complete})

Method to get the current location.

# Arguments

This method requires an object with the following attributes:

  • timeout (long). Optional attribute with the timeout interval, in milliseconds. The value by default is 30000. Upon timeout, the fail callback is triggered.
  • success (function). Optional callback function corresponding to the successful execution. The argument of the callback function is an object with the members:
    • longitude (float). Longitude component of the coordinates.
    • latitude (float). Latitude component of the coordinates.
    • accuracy (float). Accuracy of the longitude and latitude.
    • time (float). Current time.
  • fail (function(msg,code)). Optional callback function corresponding to a failed execution. The codes could be as follows:
    • 201: The user has rejected the request of obtaining a location.
    • 202: Invalid parameter.
    • 203: Service unavailable.
    • 205: The country or region is not within the service scope.
    • 1000: The location feature is disabled in the system settings of the device.
  • complete (function). Optional callback function corresponding to the end of the execution.

Example:

geolocation.getLocation({ 
  success:function(data){ 
    console.log("handling success: longitude=" + data.longitude + ", latitude=" + data.latitude); 
  }, 
  fail: function(data, code) { 
    console.log("handling fail, code=" + code); 
  } 
})

# subscribe({callback,fail})

Method to listen to the current location changes.

If you call this method more than once, only the last call will take effect.

WARNING

Do not call the getLocation method after you have called this method. The system will produce a timeout error.

# Arguments

This method requires an object with the following attributes:

  • callback (function). Mandatory callback function corresponding to changes in the location. The argument of the callback function is an object with the members:
    • longitude (float). Longitude component of the coordinates.
    • latitude (float). Latitude component of the coordinates.
    • accuracy (float). Accuracy of the longitude and latitude.
    • time (float). Current time.
  • fail (function(msg,code)). Optional callback function corresponding to a failed execution. The codes could be as follows:
    • 201: The user has rejected the request of obtaining a location.
    • 204: Timeout.
    • 1000: The location feature is disabled in the system settings of the device.

Example:

geolocation.subscribe({ 
    callback:function(data) { 
        console.log("handling success: longitude=" + data.longitude + ", latitude=" + data.latitude); 
    }, 
    fail: function(data, code) { 
        console.log("handling fail, code=" + code); 
    } 
})

# unsubscribe()

Method to cancel the listener for location changes.

Example:

geolocation.unsubscribe()

# getLocationType({success,fail,complete})

Method to get the types of methods supported by the system to get the location.

# Arguments

This method requires an object with the following attributes:

  • success (function). Optional callback function corresponding to the successful execution of the method. The argument of the callback function is an object with the member:
    • type (array) with the values of the supporting methods (e.g., ['gps', 'network']).
  • fail (function(msg,code)). Optional callback function corresponding to a failed execution.
  • complete (function). Optional callback function corresponding to the end of the execution.

Example:

geolocation.getLocationType({ 
    success: function (data) { 
        console.log("data - "+data.types) 
    }, 
    fail: function (erromsg, errocode) { 
        console.log('getLocationType: ' + errocode + ': ' + erromsg) 
    } 
})