1# Obtaining Device Location Information
2
3## When to Use
4
5You can call location APIs in OpenHarmony to obtain the real-time location or last known location and keep track of location changes of a device.
6
7Real-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.
8
9## Available APIs
10
11The following table lists the APIs used to obtain the device location information. For details, see (../../reference/apis-location-kit/js-apis-geoLocationManager.md).
12
13This module supports only the WGS-84 coordinate system.
14
15**Table 2** APIs for obtaining device location information
16
17| API| Description|
18| -------- | -------- |
19| [on(type: 'locationChange', request: LocationRequest | ContinuousLocationRequest, callback: Callback<Location>): void](../../reference/apis-location-kit/js-apis-geoLocationManager.md#geolocationmanageronlocationchange) | Registers a listener for location changes with a location request initiated.|
20| [off(type: 'locationChange', callback?: Callback<Location>): void](../../reference/apis-location-kit/js-apis-geoLocationManager.md#geolocationmanagerofflocationchange) | Unregisters the listener for location changes with the corresponding location request deleted.|
21| [getCurrentLocation(request: CurrentLocationRequest | SingleLocationRequest, callback: AsyncCallback<Location>): void](../../reference/apis-location-kit/js-apis-geoLocationManager.md#geolocationmanagergetcurrentlocation) | Obtains the current location. This API uses an asynchronous callback to return the result. |
22| [getCurrentLocation(request?: CurrentLocationRequest | SingleLocationRequest): Promise<Location>](../../reference/apis-location-kit/js-apis-geoLocationManager.md#geolocationmanagergetcurrentlocation-2) | Obtains the current location. This API uses a promise to return the result. |
23| [getLastLocation(): Location](../../reference/apis-location-kit/js-apis-geoLocationManager.md#geolocationmanagergetlastlocation) | Obtains the last known device location.|
24| [isLocationEnabled(): boolean](../../reference/apis-location-kit/js-apis-geoLocationManager.md#geolocationmanagerislocationenabled) | Checks whether the location switch is enabled.|
25
26## How to Develop
27
281. Before using system basic location capabilities, check whether your application has been granted the permission to access the device location information. If not, your application first needs to apply for the required permission. For details, see [Applying for Location Permissions](location-permission-guidelines.md).
29
302. Import the **geoLocationManager** module by which you can implement all APIs related to the basic location capabilities.
31
32   ```ts
33   import { geoLocationManager } from '@kit.LocationKit';
34   ```
353. Call **isLocationEnabled** to check whether the location switch is enabled.
36   The return result is a Boolean value. The value **true** indicates that the location switch is enabled, and the value **false** indicates the opposite.
37
38   ```ts
39   import { geoLocationManager } from '@kit.LocationKit';
40   try {
41       let locationEnabled = geoLocationManager.isLocationEnabled();
42   } catch (err) {
43       console.error("errCode:" + err.code + ", message:"  + err.message);
44   }
45   ```
46   If the location switch is not enabled, launch a dialog box asking the user to enable the switch. For details, see [Setting the Global Switch](../../reference/apis-ability-kit/js-apis-abilityAccessCtrl.md#requestglobalswitch12).
47
484. Obtain the current location of the device. It is mainly used in scenarios such as viewing of the current location, signing in/out, and service recommendation.
49   - Method 1: Obtain the latest location in the system cache.<br>
50      If the system does not have a cached location, an error code is returned.<br>
51      Using this API to obtain the device location can reduce the system power consumption.<br>
52      If a fresh location is expected, your application can first obtain the cached location and then compare the timestamp in it with the current time. If the location is not fresh, try method 2.<br>
53
54      ```ts
55      import { geoLocationManager } from '@kit.LocationKit';
56      import { BusinessError } from '@kit.BasicServicesKit'
57      try {
58          let location = geoLocationManager.getLastLocation();
59      } catch (err) {
60          console.error("errCode:" + JSON.stringify(err));
61      }
62      ```
63
64   - Method 2: Obtain the current location.<br>
65      Instantiate a [SingleLocationRequest](../../reference/apis-location-kit/js-apis-geoLocationManager.md#singlelocationrequest12) object to notify the system of the type of location service to be provided for applications and the timeout interval for a single location.<br>
66      - Set the location priority by using **LocatingPriority**.<br>
67         If a precise location is required, set **LocatingPriority** to **PRIORITY_ACCURACY**. The most accurate location result within the specified period of time will be provided for the application.<br>
68         If fast location is expected, you are advised to set **LocatingPriority** to **PRIORITY_LOCATING_SPEED**. The first obtained location result will be provided for the application.<br>
69         Both the GNSS positioning and the network positioning technologies are used in the two location policies. This can lead to significant hardware resource consumption and power consumption.<br>
70      - Set the location timeout interval by using **locatingTimeoutMs**.<br>
71         Due to the impact of the ambient environment, device status, and system power consumption control policy, the location response delay may fluctuates greatly. You are advised to set the timeout interval for a single location to 10 seconds.<br>
72
73      The following code snippet uses **PRIORITY_LOCATING_SPEED** as an example.<br>
74
75      ```ts
76      import { geoLocationManager } from '@kit.LocationKit';
77      import { BusinessError } from '@kit.BasicServicesKit'
78      let request: geoLocationManager.SingleLocationRequest = {
79         'locatingPriority': geoLocationManager.LocatingPriority.PRIORITY_LOCATING_SPEED,
80         'locatingTimeoutMs': 10000
81      }
82      try {
83         geoLocationManager.getCurrentLocation(request).then((result) => { // Call getCurrentLocation to obtain the current device location by using a promise.
84            console.log('current location: ' + JSON.stringify(result));
85         })
86         .catch((error:BusinessError) => { // Receive the reported error code.
87            console.error('promise, getCurrentLocation: error=' + JSON.stringify(error));
88         });
89       } catch (err) {
90         console.error("errCode:" + JSON.stringify(err));
91       }
92      ```
93   The coordinates obtained by this module are in the WGS-84 coordinate system. If you need to use coordinates in other coordinate systems, perform a coordinate system conversion.
94
95   <!--RP1-->   You can use the SDK capabilities provided by a third-party map to implement coordinate system conversion.<!--RP1End-->
96
975. Obtain the device location continuously. It is mainly used in scenarios such as navigation, movement track, and travel.<br>
98   Instantiate a [ContinuousLocationRequest](../../reference/apis-location-kit/js-apis-geoLocationManager.md#continuouslocationrequest12) object to notify the system of the type of location service to be provided for applications and the interval for reporting location information.<br>
99   - Set the location scenario by using **locationScenario**.<br>
100      You are advised to set **locationScenario** based on the application scenario. For details about the enum values of this parameter, see [UserActivityScenario](../../reference/apis-location-kit/js-apis-geoLocationManager.md#useractivityscenario12). For example, if **locationScenario** is set to **NAVIGATION**, the application will obtain the device location in both the indoor and outdoor scenarios for navigation.<br>
101   - Set the interval for reporting location information by using **interval**.<br>
102      The interval for reporting location information is in unit of seconds. The default value is **1**. Leave this parameter unspecified if there is no special requirement for the location reporting interval.
103
104   The following code snippet uses the map navigation scenario as an example.
105
106   ```ts
107   import { geoLocationManager } from '@kit.LocationKit';
108   let request: geoLocationManager.ContinuousLocationRequest= {
109      'interval': 1,
110      'locationScenario': geoLocationManager.UserActivityScenario.NAVIGATION
111   }
112   let locationCallback = (location:geoLocationManager.Location):void => {
113      console.log('locationCallback: data: ' + JSON.stringify(location));
114   };
115   try {
116      geoLocationManager.on('locationChange', request, locationCallback);
117   } catch (err) {
118      console.error("errCode:" + JSON.stringify(err));
119   }
120   ```
121   If your application no longer needs the device location, stop obtaining the device location to avoid high power consumption.
122   ```ts
123   geoLocationManager.off('locationChange', locationCallback);
124   ```
125