Obtaining Device Location Information

When to Use

You can call location-related APIs in OpenHarmony to obtain the real-time location or last known location of a mobile device.

Real-time location of the device is recommended for location-sensitive services. If you want to lower power consumption when the real-time location of the device is not needed, you may consider obtaining the last known location of the device.

Available APIs

The following table describes APIs available for obtaining device location information.

Table1 APIs for obtaining device location information

How to Develop

1. Before using basic location capabilities, check whether your application has been granted the permission to access the device location information. If not, your application needs to obtain the permission from the user. For details, see . The system provides the following location permissions:

   • ohos.permission.LOCATION

   • ohos.permission.LOCATION_IN_BACKGROUND

   The ohos.permission.LOCATION permission is a must if your application needs to access the device location information.

   If your application needs to access the device location information when running on the background, it must be allowed to run on the background in the configuration file and also granted the ohos.permission.LOCATION_IN_BACKGROUND permission. In this way, the system continues to report device location information even when your application moves to the background.

   To allow your application to access device location information, you can declare the required permissions in the config.json file of your application. The sample code is as follows:

   {
       "module": {
           "reqPermissions": [{
               "name": "ohos.permission.LOCATION",
               "reason": "$string:reason_description",
               "usedScene": {
                   "ability": ["com.myapplication.LocationAbility"],
                   "when": "inuse"
               }, {
               ...
               }
           ]
       }
   }
   

   For details about the fields, see .

2. Import the geolocation module by which you can implement all APIs related to the basic location capabilities.

   import geolocation from '@ohos.geolocation';
   

3. Instantiate the LocationRequest object. This object provides APIs to notify the system of the location service type and the interval of reporting location information. Method 1:

   To better serve your needs for using APIs, the system has categorized APIs into different packages to match your common use cases of the location function. In this way, you can directly use the APIs specific to a certain use case, making application development much easier. The following table lists the use cases currently supported.

       export enum LocationRequestScenario {
            UNSET = 0x300,
            NAVIGATION,
            TRAJECTORY_TRACKING,
            CAR_HAILING,
            DAILY_LIFE_SERVICE,
            NO_POWER,
        }
   

   Table2 Common use cases of the location function

 The following example instantiates the **RequestParam** object for navigation:

var requestInfo = {'scenario': 0x301, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0};

Method 2:

If the predefined use cases do not meet your needs, you can also use the basic location priority policies provided by the system.

    export enum LocationRequestPriority {
         UNSET = 0x200,
         ACCURACY,
         LOW_POWER,
         FIRST_FIX,
     }

 **Table3** Location priority policies

 The following example instantiates the **RequestParam** object for the location accuracy priority policy:

var requestInfo = {'priority': 0x201, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0};

4. Instantiate the Callback object for the system to report location results. Your application needs to implement the callback interface defined by the system. When the system successfully obtains the real-time location of a device, it will report the location result to your application through the callback interface. Your application can implement the callback interface in such a way to complete your own service logic.

   var locationChange = (location) => {
       console.log('locationChanger: data: ' + JSON.stringify(location));
   };
   

5. Start device location.

   geolocation.on('locationChange', requestInfo, locationChange);
   

6. (Optional) Stop device location.

   geolocation.off('locationChange', locationChange);
   

   If your application does not need the real-time device location, it can use the last known device location cached in the system instead.

   geolocation.getLastLocation((data) => {
       console.log('getLastLocation: data: ' + JSON.stringify(data));
   });
   

   To call this method, your application needs to request the ohos.permission.LOCATION permission from the user.