Location

Introduction

People take their mobile devices wherever they go. Mobile devices have become a necessity in people's daily routines, whether it be for looking at the weather forecast, browsing news, hailing a taxi, navigating, or recording data from a workout. All these activities are so much associated with the location services on mobile devices.

With the location awareness capability offered by OpenHarmony, mobile devices will be able to obtain real-time, accurate location data. Building location awareness into your application can also lead to a better contextual experience for application users.

Your application can call location-specific APIs to obtain the location information of a mobile device for offering location-based services such as drive navigation and motion track recording.

Basic Concepts

Location awareness helps determine where a mobile device locates. The system identifies the location of a mobile device with its coordinates, and uses location technologies such as Global Navigation Satellite System (GNSS) and network positioning (for example, base station positioning or WLAN/Bluetooth positioning) to provide diverse location-based services. These advanced location technologies make it possible to obtain the accurate location of the mobile device, regardless of whether it is indoors or outdoors.

• Coordinate

  A coordinate describes a location on the earth using the longitude and latitude in reference to the World Geodetic Coordinate System 1984.

• GNSS positioning

  GNSS positioning locates a mobile device by using the location algorithm offered by the device chip to compute the location information provided by the Global Navigation Satellite System, for example, GPS, GLONASS, BeiDou, and Galileo. Whichever positioning system will be used during the location process depends on a hardware capability of the device.

• Base station positioning

  Base station positioning estimates the current location of a mobile device based on the location of the resident base station in reference to the neighboring base stations. This technology provides only a low accuracy and requires access to the cellular network.

• WLAN or Bluetooth positioning

  WLAN or Bluetooth positioning estimates the current location of a mobile device based on the locations of WLANs and Bluetooth devices that can be discovered by the device. The location accuracy of this technology depends on the distribution of fixed WLAN access points (APs) and Bluetooth devices around the device. A high density of WLAN APs and Bluetooth devices can produce a more accurate location result than base station positioning. This technology also requires access to the network.

Figure 1 Location subsystem architecture**

Directory Structure

/base/location               # Source code of the location subsystem
├── etc                   # Code for the service startup configuration
├── interfaces            # APIs
├── profile               # Code for service declaration
├── location_common       # Common code
├── location_locator      # Location service management code
├── location_gnss         # GNSS positioning service code
├── location_network      # Network positioning service code
├── location_passive      # Passive positioning service code
├── location_geocode      # Geocoding service code
├── test                  # Test code
├── utils                 # Common utility code

Constraints

Your application can use the location function only after the user has granted the permission and turned on the function. If the location function is off, the system will not provide the location service for any application.

Since the location information is considered sensitive, your application still needs to obtain the location access permission from the user even if the user has turned on the location function. The system will provide the location service for your application only after it has been granted the permission to access the device location information.

Usage

Available APIs

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

Table 1 APIs for obtaining device location information

How to Use

Obtaining the device location information:

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.

   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.

   You can declare the required permission in your application's configuration file. For details, see Access Control (Permission) Development.

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,
        }
   

   Table 2 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,
     }

 **Table 3** 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 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.

Converting the coordinates and geocoding information:

NOTE

The GeoConvert instance needs to access backend services to obtain information. Therefore, before performing the following steps, ensure that your device is connected to the network.

1. Import the geolocation module by which you can implement all APIs related to the geocoding and reverse geocoding conversion capabilities.

   import geolocation from '@ohos.geolocation';
   

2. Obtain the conversion result.

   • Call getAddressesFromLocation to convert coordinates into geographical location information.

     var reverseGeocodeRequest = {"latitude": 31.12, "longitude": 121.11, "maxItems": 1};
     geolocation.getAddressesFromLocation(reverseGeocodeRequest, (data) => {
         console.log('getAddressesFromLocation: ' + JSON.stringify(data));
     });
     

     Your application can obtain the GeoAddress list that matches the specified coordinates and then read location information from it. For details, see the API Reference.

   • Call getAddressesFromLocationName to convert geographic description into coordinates.

     var geocodeRequest = {"description": "No. xx, xx Road, Pudong District, Shanghai", "maxItems": 1};
     geolocation.getAddressesFromLocationName(geocodeRequest, (data) => {
         console.log('getAddressesFromLocationName: ' + JSON.stringify(data));
     });
     

     Your application can obtain the GeoAddress list that matches the specified location information and read coordinates from it. For details, see the API Reference.

     To improve the accuracy of location results, you can set the longitude and latitude ranges in GeoCodeRequest.

Repositories Involved

Location subsystem

base_location