README.en.md
1# Location<a name="EN-US_TOPIC_0000001080646118"></a>
2
3- [Introduction](#section11660541593)
4- [Directory Structure](#section161941989596)
5- [Constraints](#section119744591305)
6- [Usage](#section1312121216216)
7 - [Available APIs](#section1551164914237)
8 - [Usage Guidelines](#section129654513264)
9
10- [Repositories Involved](#section1371113476307)
11
12## Introduction<a name="section11660541593"></a>
13
14People 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.
15
16With 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.
17
18Your 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.
19
20**Basic Concepts**
21
22Location 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.
23
24- **Coordinate**
25
26 A coordinate describes a location on the earth using the longitude and latitude in reference to the World Geodetic Coordinate System 1984.
27
28- **GNSS positioning**
29
30 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.
31
32- **Base station positioning**
33
34 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.
35
36- **WLAN or Bluetooth positioning**
37
38 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.
39
40
41**Figure 1** Location subsystem architecture<a name="fig4460722185514"></a>
42
43
44
45
46## Directory Structure<a name="section161941989596"></a>
47
48```
49/base/location # Source code
50├── etc # Code for the service startup configuration
51├── interfaces # APIs
52├── profile # Code for service declaration
53├── location_common # Common code
54├── location_locator # Location service management code
55├── location_gnss # GNSS positioning service code
56├── location_network # Network positioning service code
57├── location_passive # Passive positioning service code
58├── location_geocode # Geocoding service code
59├── test # Test code
60├── utils # Common utility code
61```
62
63## Constraints<a name="section119744591305"></a>
64
65Your 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.
66
67Since 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.
68
69## Usage<a name="section1312121216216"></a>
70
71### Available APIs<a name="section1551164914237"></a>
72
731. The following table describes APIs available for obtaining device location information.
74
75**Table 1** APIs for obtaining device location information
76
77| Interface Name | function description |
78| -------- | -------- |
79| on(type: 'locationChange', request: LocationRequest, callback: Callback<Location>) : void | Enable location change subscription and initiate a location request. |
80| off(type: 'locationChange', callback?: Callback<Location>) : void | Disable the location change subscription and delete the corresponding location request. |
81| on(type: 'locationServiceState', callback: Callback<boolean>) : void | The subscription location service status changes. |
82| off(type: 'locationServiceState', callback: Callback<boolean>) : void | Unsubscribe from location service status changes. |
83| on(type: 'cachedGnssLocationsReporting', request: CachedGnssLocationsRequest, callback: Callback<Array<Location>>) : void; | Subscribe to cache GNSS location reporting. |
84| off(type: 'cachedGnssLocationsReporting', callback?: Callback<Array<Location>>) : void; | Unsubscribe from cached GNSS location reporting. |
85| on(type: 'gnssStatusChange', callback: Callback<SatelliteStatusInfo>) : void; | Subscribe to satellite status update events. |
86| off(type: 'gnssStatusChange', callback?: Callback<SatelliteStatusInfo>) : void; | Unsubscribe from satellite status update events. |
87| on(type: 'nmeaMessageChange', callback: Callback<string>) : void; | Subscribe to GNSS NMEA information reporting. |
88| off(type: 'nmeaMessageChange', callback?: Callback<string>) : void; | Unsubscribe to GNSS NMEA information reporting. |
89| on(type: 'fenceStatusChange', request: GeofenceRequest, want: WantAgent) : void; | Add a fence and subscribe to the event reporting of the fence. |
90| off(type: 'fenceStatusChange', request: GeofenceRequest, want: WantAgent) : void; | Delete the fence and unsubscribe from the fence event. |
91| getCurrentLocation(request: CurrentLocationRequest, callback: AsyncCallback<Location>) : void | Obtain the current location and use the callback callback to return the result asynchronously. |
92| getCurrentLocation(request?: CurrentLocationRequest) : Promise<Location> | Obtains the current location and returns the result asynchronously in Promise mode. |
93| getLastLocation(callback: AsyncCallback<Location>) : void | Obtain the last location and use the callback callback to return the result asynchronously. |
94| getLastLocation() : Promise<Location> | Obtains the last location and returns the result asynchronously in Promise mode. |
95| isLocationEnabled(callback: AsyncCallback<boolean>) : void | Check whether the location service is enabled and callback is used to return the result asynchronously. |
96| isLocationEnabled() : Promise<boolean> | Check whether the location service is enabled and return the result asynchronously in Promise mode. |
97| requestEnableLocation(callback: AsyncCallback<boolean>) : void | Request to enable the location service and use the callback callback to return the result asynchronously. |
98| requestEnableLocation() : Promise<boolean> | Request to enable the location service and return the result asynchronously in Promise mode. |
99| enableLocation(callback: AsyncCallback<boolean>) : void | Enable the location service and use the callback callback to return the result asynchronously. |
100| enableLocation() : Promise<boolean> | Start the location service and return the result asynchronously in Promise mode. |
101| disableLocation(callback: AsyncCallback<boolean>) : void | Disable the location service and use the callback callback to return the result asynchronously. |
102| disableLocation() : Promise<boolean> | Stop the location service and return the result asynchronously in Promise mode. |
103| getCachedGnssLocationsSize(callback: AsyncCallback<number>) : void; | Obtains the number of cached GNSS locations and uses the callback callback to return the result asynchronously. |
104| getCachedGnssLocationsSize() : Promise<number>; | Obtains the number of cached GNSS locations and returns the result asynchronously in Promise mode. |
105| flushCachedGnssLocations(callback: AsyncCallback<boolean>) : void; | Obtains all GNSS cache locations, clears the GNSS cache queue, and invokes callback to return results asynchronously. |
106| flushCachedGnssLocations() : Promise<boolean>; | Obtains all GNSS cache locations, clears the GNSS cache queue, and returns results asynchronously in Promise mode. |
107| sendCommand(command: LocationCommand, callback: AsyncCallback<boolean>) : void; | Send an extended command to the location service subsystem and use the callback callback to return the result asynchronously. |
108| sendCommand(command: LocationCommand) : Promise<boolean>; | Sends extended commands to the location service subsystem and returns results asynchronously in Promise mode. |
109| isLocationPrivacyConfirmed(type : LocationPrivacyType, callback: AsyncCallback<boolean>) : void; | This interface is used to query whether a user agrees with the privacy statement of the LCS service. The callback callback interface is used to return the result asynchronously. |
110| isLocationPrivacyConfirmed(type : LocationPrivacyType,) : Promise<boolean>; | This interface is used to query whether a user agrees with the privacy statement of the LCS service. The result is returned asynchronously in Promise mode. |
111| setLocationPrivacyConfirmStatus(type : LocationPrivacyType, isConfirmed : boolean, callback: AsyncCallback<boolean>) : void; | Set and record whether the user agrees to the privacy statement of the LCS service and use the callback callback to return the result asynchronously. |
112| setLocationPrivacyConfirmStatus(type : LocationPrivacyType, isConfirmed : boolean) : Promise<boolean>; | Set and record whether the user agrees to the privacy statement of the LCS. The result is returned asynchronously in Promise mode. |
113
114
115### Usage Guidelines<a name="section129654513264"></a>
116
117**Obtaining the device location information:**
118
1191. 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.
120
121 The system provides the following location permissions:
122
123 - ohos.permission.LOCATION
124 - ohos.permission.LOCATION\_IN\_BACKGROUND
125
126 The **ohos.permission.LOCATION** permission is a must if your application needs to access the device location information.
127
128 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.
129
130 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:
131
132 ```
133 {
134 "reqPermissions": [{
135 "name": "ohos.permission.LOCATION",
136 "reason": "$string:reason_description",
137 "usedScene": {
138 "ability": ["com.myapplication.LocationAbility"],
139 "when": "inuse"
140 }, {
141 ...
142 }
143 ]
144 }
145 ```
146
1472. Import the geolocation module. All function APIs related to basic location capabilities are provided through this module.
148
149 ```
150 import geolocation from '@ohos.geolocation';
151 ```
152
1533. Instantiates the LocationRequest object to notify the system of the type of location service to be provided to the application and the frequency of reporting location results.
154
155 **Method 1:**
156
157 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.
158
159 **Table 3** Common use cases of the location function
160
161 <a name="table1758483964015"></a>
162 <table><thead align="left"><tr id="row458433920403"><th class="cellrowborder" valign="top" width="14.92850714928507%" id="mcps1.2.4.1.1"><p id="p12584143911402"><a name="p12584143911402"></a><a name="p12584143911402"></a>Use Case</p>
163 </th>
164 <th class="cellrowborder" valign="top" width="25.16748325167483%" id="mcps1.2.4.1.2"><p id="p125842039174016"><a name="p125842039174016"></a><a name="p125842039174016"></a>Constant</p>
165 </th>
166 <th class="cellrowborder" valign="top" width="59.904009599040094%" id="mcps1.2.4.1.3"><p id="p10585139134010"><a name="p10585139134010"></a><a name="p10585139134010"></a>Description</p>
167 </th>
168 </tr>
169 </thead>
170 <tbody><tr id="row858573914011"><td class="cellrowborder" valign="top" width="14.92850714928507%" headers="mcps1.2.4.1.1 "><p id="p258518398406"><a name="p258518398406"></a><a name="p258518398406"></a>Navigation</p>
171 </td>
172 <td class="cellrowborder" valign="top" width="25.16748325167483%" headers="mcps1.2.4.1.2 "><p id="p1758513915403"><a name="p1758513915403"></a><a name="p1758513915403"></a>SCENE_NAVIGATION</p>
173 </td>
174 <td class="cellrowborder" valign="top" width="59.904009599040094%" headers="mcps1.2.4.1.3 "><p id="p4585183934017"><a name="p4585183934017"></a><a name="p4585183934017"></a>Applicable when your application needs to obtain the real-time location of a mobile device outdoors, such as navigation for driving or walking. In this scenario, the GNSS positioning technology is mainly used to ensure the location accuracy. However, due to its limitations, the technology may be unable to provide the location service when navigation is just started or when the user moves into a shielded environment such as indoors or a garage. To resolve this issue, the system uses the network positioning technology as an alternative to provide the location service for your application until the GNSS can provide stable location results. This helps achieve a smooth navigation experience for users.</p>
175 <p id="p12585039174017"><a name="p12585039174017"></a><a name="p12585039174017"></a>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the <strong id="b975004216292"><a name="b975004216292"></a><a name="b975004216292"></a>ohos.permission.LOCATION</strong> permission and obtain user authorization.</p>
176 </td>
177 </tr>
178 <tr id="row1458543934016"><td class="cellrowborder" valign="top" width="14.92850714928507%" headers="mcps1.2.4.1.1 "><p id="p258523944018"><a name="p258523944018"></a><a name="p258523944018"></a>Trajectory tracking</p>
179 </td>
180 <td class="cellrowborder" valign="top" width="25.16748325167483%" headers="mcps1.2.4.1.2 "><p id="p9585133904019"><a name="p9585133904019"></a><a name="p9585133904019"></a>SCENE_TRAJECTORY_TRACKING</p>
181 </td>
182 <td class="cellrowborder" valign="top" width="59.904009599040094%" headers="mcps1.2.4.1.3 "><p id="p1358553984019"><a name="p1358553984019"></a><a name="p1358553984019"></a>Applicable when your application needs to record user trajectories, for example, the track recording function of sports applications. In this scenario, the GNSS positioning technology is mainly used to ensure the location accuracy.</p>
183 <p id="p9585153917401"><a name="p9585153917401"></a><a name="p9585153917401"></a>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the <strong id="b18532492293"><a name="b18532492293"></a><a name="b18532492293"></a>ohos.permission.LOCATION</strong> permission and obtain user authorization.</p>
184 </td>
185 </tr>
186 <tr id="row258503916400"><td class="cellrowborder" valign="top" width="14.92850714928507%" headers="mcps1.2.4.1.1 "><p id="p1658513396408"><a name="p1658513396408"></a><a name="p1658513396408"></a>Ride hailing</p>
187 </td>
188 <td class="cellrowborder" valign="top" width="25.16748325167483%" headers="mcps1.2.4.1.2 "><p id="p6585639124019"><a name="p6585639124019"></a><a name="p6585639124019"></a>SCENE_CAR_HAILING</p>
189 </td>
190 <td class="cellrowborder" valign="top" width="59.904009599040094%" headers="mcps1.2.4.1.3 "><p id="p125857398404"><a name="p125857398404"></a><a name="p125857398404"></a>Applicable when your application needs to obtain the current location of a user who is hailing a taxi.</p>
191 <p id="p1158563974014"><a name="p1158563974014"></a><a name="p1158563974014"></a>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the <strong id="b91255452918"><a name="b91255452918"></a><a name="b91255452918"></a>ohos.permission.LOCATION</strong> permission and obtain user authorization.</p>
192 </td>
193 </tr>
194 <tr id="row19585839134012"><td class="cellrowborder" valign="top" width="14.92850714928507%" headers="mcps1.2.4.1.1 "><p id="p558583924020"><a name="p558583924020"></a><a name="p558583924020"></a>Life service</p>
195 </td>
196 <td class="cellrowborder" valign="top" width="25.16748325167483%" headers="mcps1.2.4.1.2 "><p id="p18585143914013"><a name="p18585143914013"></a><a name="p18585143914013"></a>SCENE_DAILY_LIFE_SERVICE</p>
197 </td>
198 <td class="cellrowborder" valign="top" width="59.904009599040094%" headers="mcps1.2.4.1.3 "><p id="p1585193994013"><a name="p1585193994013"></a><a name="p1585193994013"></a>Applicable when your application only needs the approximate user location for recommendations and push notifications in scenarios such as when the user is browsing news, shopping online, and ordering food.</p>
199 <p id="p9585183984012"><a name="p9585183984012"></a><a name="p9585183984012"></a>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the <strong id="b310562153012"><a name="b310562153012"></a><a name="b310562153012"></a>ohos.permission.LOCATION</strong> permission and obtain user authorization.</p>
200 </td>
201 </tr>
202 <tr id="row16585153914013"><td class="cellrowborder" valign="top" width="14.92850714928507%" headers="mcps1.2.4.1.1 "><p id="p358533911403"><a name="p358533911403"></a><a name="p358533911403"></a>Power efficiency</p>
203 </td>
204 <td class="cellrowborder" valign="top" width="25.16748325167483%" headers="mcps1.2.4.1.2 "><p id="p12585153974020"><a name="p12585153974020"></a><a name="p12585153974020"></a>SCENE_NO_POWER</p>
205 </td>
206 <td class="cellrowborder" valign="top" width="59.904009599040094%" headers="mcps1.2.4.1.3 "><p id="p75851391407"><a name="p75851391407"></a><a name="p75851391407"></a>Applicable when your application does not proactively start the location service for a higher battery efficiency. When responding to another application requesting the same location service, the system marks a copy of the location result to your application. In this way, your application will not consume extra power for obtaining the user location.</p>
207 <p id="p258533913402"><a name="p258533913402"></a><a name="p258533913402"></a>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the <strong id="b169496663012"><a name="b169496663012"></a><a name="b169496663012"></a>ohos.permission.LOCATION</strong> permission and obtain user authorization.</p>
208 </td>
209 </tr>
210 </tbody>
211 </table>
212
213 The following example instantiates the **RequestParam** object for navigation:
214
215 ```
216 RequestParam requestParam = new RequestParam(RequestParam.SCENE_NAVIGATION);
217 ```
218
219 **Method 2:**
220
221 If the predefined use cases do not meet your needs, you can also use the basic location priority policies provided by the system.
222
223 ```
224 export enum LocationRequestPriority {
225 UNSET = 0x200,
226 ACCURACY,
227 LOW_POWER,
228 FIRST_FIX,
229 }
230 ```
231
232 **Table 4** Location priority policies
233
234 <a name="table1276019614412"></a>
235 <table><thead align="left"><tr id="row07609619412"><th class="cellrowborder" valign="top" width="29.592959295929592%" id="mcps1.2.4.1.1"><p id="p176096144113"><a name="p176096144113"></a><a name="p176096144113"></a>Policy</p>
236 </th>
237 <th class="cellrowborder" valign="top" width="27.082708270827084%" id="mcps1.2.4.1.2"><p id="p8760368415"><a name="p8760368415"></a><a name="p8760368415"></a>Constant</p>
238 </th>
239 <th class="cellrowborder" valign="top" width="43.32433243324332%" id="mcps1.2.4.1.3"><p id="p127601064415"><a name="p127601064415"></a><a name="p127601064415"></a>Description</p>
240 </th>
241 </tr>
242 </thead>
243 <tbody><tr id="row67609613412"><td class="cellrowborder" valign="top" width="29.592959295929592%" headers="mcps1.2.4.1.1 "><p id="p207608664111"><a name="p207608664111"></a><a name="p207608664111"></a>Location accuracy priority</p>
244 </td>
245 <td class="cellrowborder" valign="top" width="27.082708270827084%" headers="mcps1.2.4.1.2 "><p id="p976017620419"><a name="p976017620419"></a><a name="p976017620419"></a>PRIORITY_ACCURACY</p>
246 </td>
247 <td class="cellrowborder" valign="top" width="43.32433243324332%" headers="mcps1.2.4.1.3 "><p id="p1976017624110"><a name="p1976017624110"></a><a name="p1976017624110"></a>This policy mainly uses the GNSS positioning technology. In an open area, the technology can achieve the meter-level location accuracy, depending on the hardware performance of the device. However, in a shielded environment, the location accuracy may significantly decrease.</p>
248 <p id="p1076036154113"><a name="p1076036154113"></a><a name="p1076036154113"></a>To use this policy, you must declare the <strong id="b1768101919305"><a name="b1768101919305"></a><a name="b1768101919305"></a>ohos.permission.LOCATION</strong> permission and obtain user authorization.</p>
249 </td>
250 </tr>
251 <tr id="row1676014604116"><td class="cellrowborder" valign="top" width="29.592959295929592%" headers="mcps1.2.4.1.1 "><p id="p576056104110"><a name="p576056104110"></a><a name="p576056104110"></a>Fast location priority</p>
252 </td>
253 <td class="cellrowborder" valign="top" width="27.082708270827084%" headers="mcps1.2.4.1.2 "><p id="p14760965417"><a name="p14760965417"></a><a name="p14760965417"></a>PRIORITY_FAST_FIRST_FIX</p>
254 </td>
255 <td class="cellrowborder" valign="top" width="43.32433243324332%" headers="mcps1.2.4.1.3 "><p id="p1760106164114"><a name="p1760106164114"></a><a name="p1760106164114"></a>This policy uses the GNSS positioning, base station positioning, WLAN positioning, and Bluetooth positioning technologies simultaneously to obtain the device location in both the indoor and outdoor scenarios. When all positioning technologies provide a location result, the system provides the most accurate location result for your application. This policy can lead to significant hardware resource consumption and power consumption.</p>
256 <p id="p10760965410"><a name="p10760965410"></a><a name="p10760965410"></a>To use this policy, you must declare the <strong id="b1154417237307"><a name="b1154417237307"></a><a name="b1154417237307"></a>ohos.permission.LOCATION</strong> permission and obtain user authorization.</p>
257 </td>
258 </tr>
259 <tr id="row276017654111"><td class="cellrowborder" valign="top" width="29.592959295929592%" headers="mcps1.2.4.1.1 "><p id="p1376019674118"><a name="p1376019674118"></a><a name="p1376019674118"></a>Power efficiency priority</p>
260 </td>
261 <td class="cellrowborder" valign="top" width="27.082708270827084%" headers="mcps1.2.4.1.2 "><p id="p16760156124114"><a name="p16760156124114"></a><a name="p16760156124114"></a>PRIORITY_LOW_POWER</p>
262 </td>
263 <td class="cellrowborder" valign="top" width="43.32433243324332%" headers="mcps1.2.4.1.3 "><p id="p1776096124115"><a name="p1776096124115"></a><a name="p1776096124115"></a>This policy mainly uses the base station positioning, WLAN positioning, and Bluetooth positioning technologies to obtain device location in both indoor and outdoor scenarios. The location accuracy depends on the distribution of surrounding base stations, visible WLANs, and Bluetooth devices and therefore may fluctuate greatly. This policy is recommended and can reduce power consumption when your application does not require high location accuracy or when base stations, visible WLANs, and Bluetooth devices are densely distributed.</p>
264 <p id="p6760196144113"><a name="p6760196144113"></a><a name="p6760196144113"></a>To use this policy, you must declare at least the <strong id="b644522883019"><a name="b644522883019"></a><a name="b644522883019"></a>ohos.permission.LOCATION</strong> permission and obtain user authorization.</p>
265 </td>
266 </tr>
267 </tbody>
268 </table>
269
270 The positioning accuracy priority policy is used as an example. The instantiation method is as follows:
271
272 ```
273 var requestInfo = {'priority': 0x201, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0};
274 ```
275
2764. Instantiate the Callback object, which is used to provide the system with a location report method.
277 The application needs to implement the callback interface defined by the system and instantiate the interface. The system reports the real-time location result of a device to the application through this interface. An application can complete its own business logic in the implementation of the interface.
278
279 ```
280 var locationChange = (location) => {
281 console.log('locationChanger: data: ' + JSON.stringify(location));
282 };
283 ```
284
2855. Start device location.
286
287 ```
288 geolocation.on('locationChange', requestInfo, locationChange);
289 ```
290
2916. \(Optional\) Stop device location.
292
293 ```
294 geolocation.off('locationChange', locationChange);
295 ```
296
297 If your application does not need the real-time device location, it can use the last known device location cached in the system instead.
298
299 ```
300 geolocation.getLastLocation((data) => {
301 console.log('getLastLocation: data: ' + JSON.stringify(data));
302 });
303 ```
304
305 To call this method, your application needs to request the **ohos.permission.LOCATION** permission from the user.
306
307
308**Converting the coordinates and geocoding information:**
309
3101. Import the geolocation module. All functional APIs related to the (inverse) geocoding conversion capability are provided through this module.
311
312 ```
313 import geolocation from '@ohos.geolocation';
314 ```
315
316 You can use **GeoConvert\(Locale locale\)** to create a **GeoConvert** instance based on specified parameters, such as the language and region.
317
3182. Obtain the conversion result.
319 - Convert coordinates to location information.
320
321 ```
322 var reverseGeocodeRequest = {"latitude": 31.12, "longitude": 121.11, "maxItems": 1};
323 geolocation.getAddressesFromLocation(reverseGeocodeRequest, (data) => {
324 console.log('getAddressesFromLocation: ' + JSON.stringify(data));
325 });
326 ```
327
328 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_.
329
330 - Convert location information to coordinates.
331
332 ```
333 var geocodeRequest = {"description": "上海市浦东新区xx路xx号", "maxItems": 1};
334 geolocation.getAddressesFromLocationName(geocodeRequest, (data) => {
335 console.log('getAddressesFromLocationName: ' + JSON.stringify(data));
336 });
337 ```
338
339 Your application can obtain the **GeoAddress** list that matches the specified location information and read coordinates from it. For details, see the _API Reference_.
340
341
342## Repositories Involved<a name="section1371113476307"></a>
343
344base_location
345
346
README.md
1# 位置服务组件<a name="ZH-CN_TOPIC_0000001115112235"></a>
2
3- [简介](#section11660541593)
4- [目录](#section161941989596)
5- [约束](#section119744591305)
6- [说明](#section1312121216216)
7 - [接口说明](#section1551164914237)
8 - [使用说明](#section129654513264)
9
10- [相关仓](#section1371113476307)
11
12## 简介<a name="section11660541593"></a>
13
14移动终端设备已经深入人们日常生活的方方面面，如查看所在城市的天气、新闻轶事、出行打车、旅行导航、运动记录。这些习以为常的活动，都离不开定位用户终端设备的位置。
15
16当用户处于这些丰富的使用场景中时，系统的位置能力可以提供实时准确的位置数据。对于开发者，设计基于位置体验的服务，也可以使应用的使用体验更贴近每个用户。
17
18当应用在实现基于设备位置的功能时，如：驾车导航，记录运动轨迹等，可以调用该模块的API接口，完成位置信息的获取
19
20基本概念
21
22位置能力用于确定用户设备在哪里，系统使用位置坐标标示设备的位置，并用多种定位技术提供服务，如GNSS定位、基站定位、WLAN/蓝牙定位（基站定位、WLAN/蓝牙定位后续统称“网络定位技术”）。通过这些定位技术，无论用户设备在室内或是户外，都可以准确地确定设备位置。
23
24- **坐标**
25
26 系统以1984年世界大地坐标系统为参考，使用经度、纬度数据描述地球上的一个位置。
27
28- **GNSS定位**
29
30 基于全球导航卫星系统，包含：GPS、GLONASS、北斗、Galileo等，通过导航卫星，设备芯片提供的定位算法，来确定设备准确位置。定位过程具体使用哪些定位系统，取决于用户设备的硬件能力。
31
32- **基站定位**
33
34 根据设备当前驻网基站和相邻基站的位置，估算设备当前位置。此定位方式的定位结果精度相对较低，并且需要设备可以访问蜂窝网络。
35
36- **WLAN、蓝牙定位**
37
38 根据设备可搜索到的周围WLAN、蓝牙设备位置，估算设备当前位置。此定位方式的定位结果精度依赖设备周围可见的固定WLAN、蓝牙设备的分布，密度较高时，精度也相较与基站定位方式更高，同时也需要设备可以访问网络。
39
40
41**图 1** **子系统架构图**<a name="fig4460722185514"></a>
42
43
44
45
46## 目录<a name="section161941989596"></a>
47
48```
49/base/location # 源代码目录结构：
50├── etc # 服务启动配置代码目录
51├── interfaces # 接口相关代码目录
52├── profile # 服务声明代码目录
53├── location_common # 公共代码目录
54├── location_locator # 定位服务管理代码目录
55├── location_gnss # gnss定位服务代码目录
56├── location_network # 网络定位服务代码目录
57├── location_passive # 被动定位服务代码目录
58├── location_geocode # 地理编码服务代码目录
59├── test # 测试代码目录
60├── utils # 公共工具代码目录
61```
62
63## 约束<a name="section119744591305"></a>
64
65使用设备的位置能力，需要用户进行确认并主动开启位置开关。如果位置开关没有开启，系统不会向任何应用提供位置服务。
66
67设备位置信息属于用户敏感数据，所以即使用户已经开启位置开关，应用在获取设备位置前仍需向用户申请位置访问权限。在用户确认允许后，系统才会向应用提供位置服务。
68
69## 说明<a name="section1312121216216"></a>
70
71### 接口说明<a name="section1551164914237"></a>
72
731.获取设备的位置信息，所使用的接口说明如下。
74
75**表 1** 获取位置信息API功能介绍
76| 接口名 | 功能描述 |
77| -------- | -------- |
78| on(type: 'locationChange', request: LocationRequest, callback: Callback<Location>) : void | 开启位置变化订阅，并发起定位请求。 |
79| off(type: 'locationChange', callback?: Callback<Location>) : void | 关闭位置变化订阅，并删除对应的定位请求。 |
80| on(type: 'locationServiceState', callback: Callback<boolean>) : void | 订阅位置服务状态变化。 |
81| off(type: 'locationServiceState', callback: Callback<boolean>) : void | 取消订阅位置服务状态变化。 |
82| on(type: 'cachedGnssLocationsReporting', request: CachedGnssLocationsRequest, callback: Callback<Array<Location>>) : void; | 订阅缓存GNSS位置上报。 |
83| off(type: 'cachedGnssLocationsReporting', callback?: Callback<Array<Location>>) : void; | 取消订阅缓存GNSS位置上报。 |
84| on(type: 'gnssStatusChange', callback: Callback<SatelliteStatusInfo>) : void; | 订阅卫星状态信息更新事件。 |
85| off(type: 'gnssStatusChange', callback?: Callback<SatelliteStatusInfo>) : void; | 取消订阅卫星状态信息更新事件。 |
86| on(type: 'nmeaMessageChange', callback: Callback<string>) : void; | 订阅GNSS NMEA信息上报。 |
87| off(type: 'nmeaMessageChange', callback?: Callback<string>) : void; | 取消订阅GNSS NMEA信息上报。 |
88| on(type: 'fenceStatusChange', request: GeofenceRequest, want: WantAgent) : void; | 添加围栏，并订阅该围栏事件上报。 |
89| off(type: 'fenceStatusChange', request: GeofenceRequest, want: WantAgent) : void; | 删除围栏，并取消订阅该围栏事件。 |
90| getCurrentLocation(request: CurrentLocationRequest, callback: AsyncCallback<Location>) : void | 获取当前位置，使用callback回调异步返回结果。 |
91| getCurrentLocation(request?: CurrentLocationRequest) : Promise<Location> | 获取当前位置，使用Promise方式异步返回结果。 |
92| getLastLocation(callback: AsyncCallback<Location>) : void | 获取上一次位置，使用callback回调异步返回结果。 |
93| getLastLocation() : Promise<Location> | 获取上一次位置，使用Promise方式异步返回结果。 |
94| isLocationEnabled(callback: AsyncCallback<boolean>) : void | 判断位置服务是否已经打开，使用callback回调异步返回结果。 |
95| isLocationEnabled() : Promise<boolean> | 判断位置服务是否已经开启，使用Promise方式异步返回结果。 |
96| requestEnableLocation(callback: AsyncCallback<boolean>) : void | 请求打开位置服务，使用callback回调异步返回结果。 |
97| requestEnableLocation() : Promise<boolean> | 请求打开位置服务，使用Promise方式异步返回结果。 |
98| enableLocation(callback: AsyncCallback<boolean>) : void | 打开位置服务，使用callback回调异步返回结果。 |
99| enableLocation() : Promise<boolean> | 打开位置服务，使用Promise方式异步返回结果。 |
100| disableLocation(callback: AsyncCallback<boolean>) : void | 关闭位置服务，使用callback回调异步返回结果。 |
101| disableLocation() : Promise<boolean> | 关闭位置服务，使用Promise方式异步返回结果。 |
102| getCachedGnssLocationsSize(callback: AsyncCallback<number>) : void; | 获取缓存GNSS位置的个数，使用callback回调异步返回结果。 |
103| getCachedGnssLocationsSize() : Promise<number>; | 获取缓存GNSS位置的个数，使用Promise方式异步返回结果。 |
104| flushCachedGnssLocations(callback: AsyncCallback<boolean>) : void; | 获取所有的GNSS缓存位置，并清空GNSS缓存队列，使用callback回调异步返回结果。 |
105| flushCachedGnssLocations() : Promise<boolean>; | 获取所有的GNSS缓存位置，并清空GNSS缓存队列，使用Promise方式异步返回结果。 |
106| sendCommand(command: LocationCommand, callback: AsyncCallback<boolean>) : void; | 给位置服务子系统发送扩展命令，使用callback回调异步返回结果。 |
107| sendCommand(command: LocationCommand) : Promise<boolean>; | 给位置服务子系统发送扩展命令，使用Promise方式异步返回结果。 |
108| isLocationPrivacyConfirmed(type : LocationPrivacyType, callback: AsyncCallback<boolean>) : void; | 查询用户是否同意定位服务的隐私申明，使用callback回调异步返回结果。 |
109| isLocationPrivacyConfirmed(type : LocationPrivacyType,) : Promise<boolean>; | 查询用户是否同意定位服务的隐私申明，使用Promise方式异步返回结果。 |
110| setLocationPrivacyConfirmStatus(type : LocationPrivacyType, isConfirmed : boolean, callback: AsyncCallback<boolean>) : void; | 设置并记录用户是否同意定位服务的隐私申明，使用callback回调异步返回结果。 |
111| setLocationPrivacyConfirmStatus(type : LocationPrivacyType, isConfirmed : boolean) : Promise<boolean>; | 设置并记录用户是否同意定位服务的隐私申明，使用Promise方式异步返回结果。 |
112
113
114### 使用说明<a name="section129654513264"></a>
115
116**获取设备位置信息开发步骤如下：**
117
1181. 应用在使用系统能力前，需要检查是否已经获取用户授权访问设备位置信息。如未获得授权，可以向用户申请需要的位置权限，申请方式请参考。
119 系统提供的定位权限有：
120 - ohos.permission.LOCATION
121
122 - ohos.permission.LOCATION_IN_BACKGROUND
123
124 访问设备的位置信息，必须申请ohos.permission.LOCATION权限，并且获得用户授权。
125
126 如果应用在后台运行时也需要访问设备位置，除需要将应用声明为允许后台运行外，还必须申请ohos.permission.LOCATION_IN_BACKGROUND权限，这样应用在切入后台之后，系统可以继续上报位置信息。
127
128 开发者可以在应用config.json文件中声明所需要的权限，示例代码如下：
129
130
131 ```
132 {
133 "module": {
134 "reqPermissions": [{
135 "name": "ohos.permission.LOCATION",
136 "reason": "$string:reason_description",
137 "usedScene": {
138 "ability": ["com.myapplication.LocationAbility"],
139 "when": "inuse"
140 }, {
141 ...
142 }
143 ]
144 }
145 }
146 ```
147
148 配置字段详细说明见。
149
1502. 导入geolocation模块，所有与基础定位能力相关的功能API，都是通过该模块提供的。
151
152 ```
153 import geolocation from '@ohos.geolocation';
154 ```
155
1563. 实例化LocationRequest对象，用于告知系统该向应用提供何种类型的位置服务，以及位置结果上报的频率。
157 **方式一：**
158
159 为了面向开发者提供贴近其使用场景的API使用方式，系统定义了几种常见的位置能力使用场景，并针对使用场景做了适当的优化处理，应用可以直接匹配使用，简化开发复杂度。系统当前支持场景如下表所示。
160
161
162 ```
163 export enum LocationRequestScenario {
164 UNSET = 0x300,
165 NAVIGATION,
166 TRAJECTORY_TRACKING,
167 CAR_HAILING,
168 DAILY_LIFE_SERVICE,
169 NO_POWER,
170 }
171 ```
172
173
174 **表2** 定位场景类型说明
175
176 | 场景名称 | 常量定义 | 说明 |
177 | -------- | -------- | -------- |
178 | 导航场景 | NAVIGATION | 适用于在户外定位设备实时位置的场景，如车载、步行导航。在此场景下，为保证系统提供位置结果精度最优，主要使用GNSS定位技术提供定位服务，结合场景特点，在导航启动之初，用户很可能在室内、车库等遮蔽环境，GNSS技术很难提供位置服务。为解决此问题，我们会在GNSS提供稳定位置结果之前，使用系统网络定位技术，向应用提供位置服务，以在导航初始阶段提升用户体验。<br/>此场景默认以最小1秒间隔上报定位结果，使用此场景的应用必须申请ohos.permission.LOCATION权限，同时获得用户授权。 |
179 | 轨迹跟踪场景 | TRAJECTORY_TRACKING | 适用于记录用户位置轨迹的场景，如运动类应用记录轨迹功能。主要使用GNSS定位技术提供定位服务。<br/>此场景默认以最小1秒间隔上报定位结果，并且应用必须申请ohos.permission.LOCATION权限，同时获得用户授权。 |
180 | 出行约车场景 | CAR_HAILING | 适用于用户出行打车时定位当前位置的场景，如网约车类应用。<br/>此场景默认以最小1秒间隔上报定位结果，并且应用必须申请ohos.permission.LOCATION权限，同时获得用户授权。 |
181 | 生活服务场景 | DAILY_LIFE_SERVICE | 生活服务场景，适用于不需要定位用户精确位置的使用场景，如新闻资讯、网购、点餐类应用，做推荐、推送时定位用户大致位置即可。<br/>此场景默认以最小1秒间隔上报定位结果，并且应用至少申请ohos.permission.LOCATION权限，同时获得用户授权。 |
182 | 无功耗场景 | NO_POWER | 无功耗场景，适用于不需要主动启动定位业务。系统在响应其他应用启动定位业务并上报位置结果时，会同时向请求此场景的应用程序上报定位结果，当前的应用程序不产生定位功耗。<br/>此场景默认以最小1秒间隔上报定位结果，并且应用需要申请ohos.permission.LOCATION权限，同时获得用户授权。 |
183
184 以导航场景为例，实例化方式如下：
185
186 ```
187 var requestInfo = {'scenario': 0x301, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0};
188 ```
189
190 **方式二：**
191
192 如果定义的现有场景类型不能满足所需的开发场景，系统提供了基本的定位优先级策略类型。
193
194
195 ```
196 export enum LocationRequestPriority {
197 UNSET = 0x200,
198 ACCURACY,
199 LOW_POWER,
200 FIRST_FIX,
201 }
202 ```
203
204
205 **表3** 定位优先级策略类型说明：
206
207 | 策略类型 | 常量定义 | 说明 |
208 | -------- | -------- | -------- |
209 | 定位精度优先策略 | ACCURACY | 定位精度优先策略主要以GNSS定位技术为主，在开阔场景下可以提供米级的定位精度，具体性能指标依赖用户设备的定位硬件能力，但在室内等强遮蔽定位场景下，无法提供准确的位置服务。<br/>应用必须申请ohos.permission.LOCATION权限，同时获得用户授权。 |
210 | 快速定位优先策略 | FAST_FIRST_FIX | 快速定位优先策略会同时使用GNSS定位、基站定位和WLAN、蓝牙定位技术，以便室内和户外场景下，通过此策略都可以获得位置结果，当各种定位技术都有提供位置结果时，系统会选择其中精度较好的结果返回给应用。因为对各种定位技术同时使用，对设备的硬件资源消耗较大，功耗也较大。<br/>应用必须申请ohos.permission.LOCATION权限，同时获得用户授权。 |
211 | 低功耗定位优先策略 | LOW_POWER | 低功耗定位优先策略主要使用基站定位和WLAN、蓝牙定位技术，也可以同时提供室内和户外场景下的位置服务，因为其依赖周边基站、可见WLAN、蓝牙设备的分布情况，定位结果的精度波动范围较大，如果对定位结果精度要求不高，或者使用场景多在有基站、可见WLAN、蓝牙设备高密度分布的情况下，推荐使用，可以有效节省设备功耗。<br/>应用至少申请ohos.permission.LOCATION权限，同时获得用户授权。 |
212
213 以定位精度优先策略为例，实例化方式如下：
214
215 ```
216 var requestInfo = {'priority': 0x201, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0};
217 ```
218
2194. 实例化Callback对象，用于向系统提供位置上报的途径。
220 应用需要自行实现系统定义好的回调接口，并将其实例化。系统在定位成功确定设备的实时位置结果时，会通过该接口上报给应用。应用程序可以在接口的实现中完成自己的业务逻辑。
221
222 ```
223 var locationChange = (location) => {
224 console.log('locationChanger: data: ' + JSON.stringify(location));
225 };
226 ```
227
2285. 启动定位。
229
230 ```
231 geolocation.on('locationChange', requestInfo, locationChange);
232 ```
233
2346. （可选）结束定位。
235
236 ```
237 geolocation.off('locationChange', locationChange);
238 ```
239
240 如果应用使用场景不需要实时的设备位置，可以获取系统缓存的最近一次历史定位结果。
241
242 ```
243 geolocation.getLastLocation((data) => {
244 console.log('getLastLocation: data: ' + JSON.stringify(data));
245 });
246 ```
247
248 此接口的使用需要应用向用户申请ohos.permission.LOCATION权限。
249
250
251
252**进行坐标和地理编码信息的相互转化开发步骤如下：**
253
254>  **说明：**
255> GeoConvert需要访问后端服务，请确保设备联网，以进行信息获取。
256
2571. 导入geolocation模块，所有与（逆）地理编码转化能力相关的功能API，都是通过该模块提供的。
258
259 ```
260 import geolocation from '@ohos.geolocation';
261 ```
262
2632. 获取转化结果。
264 - 调用getAddressesFromLocation，坐标转化地理位置信息。
265
266 ```
267 var reverseGeocodeRequest = {"latitude": 31.12, "longitude": 121.11, "maxItems": 1};
268 geolocation.getAddressesFromLocation(reverseGeocodeRequest, (data) => {
269 console.log('getAddressesFromLocation: ' + JSON.stringify(data));
270 });
271 ```
272
273 参考接口API说明，应用可以获得与此坐标匹配的GeoAddress列表，应用可以根据实际使用需求，读取相应的参数数据。
274 - 调用getAddressesFromLocationName位置描述转化坐标。
275
276 ```
277 var geocodeRequest = {"description": "上海市浦东新区xx路xx号", "maxItems": 1};
278 geolocation.getAddressesFromLocationName(geocodeRequest, (data) => {
279 console.log('getAddressesFromLocationName: ' + JSON.stringify(data));
280 });
281 ```
282
283 参考接口API说明，应用可以获得与位置描述相匹配的GeoAddress列表，其中包含对应的坐标数据，请参考API使用。
284
285 如果需要查询的位置描述可能出现多地重名的请求，可以设置GeoCodeRequest，通过设置一个经纬度范围，以高效地获取期望的准确结果。
286
287
288
289## 相关仓<a name="section1371113476307"></a>
290
291位置服务子系统
292
293base_location
294
