1# @ohos.geoLocationManager (Geolocation Manager) (System API) 2 3The **geoLocationManager** module provides location services such as Global Navigation Satellite System (GNSS)-based positioning, network positioning, geofencing, as well as geocoding and reverse geocoding. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.geoLocationManager (Geolocation Manager)](js-apis-geoLocationManager.md). 9> This module supports only the WGS-84 coordinate system. 10 11## Applying for Permissions 12 13Before 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 as described below. 14 15The system provides the following location permissions: 16- ohos.permission.LOCATION 17 18- ohos.permission.APPROXIMATELY_LOCATION 19 20- ohos.permission.LOCATION_IN_BACKGROUND 21 22If your application needs to access the device location information, it must first apply for required permissions. Specifically speaking: 23 24API versions earlier than 9: Apply for **ohos.permission.LOCATION**. 25 26API version 9 and later: Apply for **ohos.permission.APPROXIMATELY\_LOCATION**, or apply for **ohos.permission.APPROXIMATELY\_LOCATION** and **ohos.permission.LOCATION**. Note that **ohos.permission.LOCATION** cannot be applied for separately. 27 28| API Version| Location Permission| Permission Application Result| Location Accuracy| 29| -------- | -------- | -------- | -------- | 30| Earlier than 9| ohos.permission.LOCATION | Success| Location accurate to meters| 31| 9 and later| ohos.permission.LOCATION | Failure| No location obtained| 32| 9 and later| ohos.permission.APPROXIMATELY_LOCATION | Success| Location accurate to 5 kilometers| 33| 9 and later| ohos.permission.APPROXIMATELY_LOCATION and ohos.permission.LOCATION| Success| Location accurate to meters| 34 35To access the device location information when running in the background, an application needs to request for a continuous task of the LOCATION type. In this way, the system continues to report device location information after your application moves to the background. For details about how to request for a continuous task, see [Continuous Task](../../task-management/continuous-task.md). 36 37A user can grant the **ohos.permission.LOCATION_IN_BACKGROUND** permission for an application on the setting page. For details, see [ohos.permission.LOCATION_IN_BACKGROUND](../../security/AccessToken/permissions-for-all-user.md#ohospermissionlocation_in_background). 38 39You can declare the required permission in your application's configuration file. For details, see [Requesting User Authorization](../../security/AccessToken/request-user-authorization.md). 40 41 42## Modules to Import 43 44```ts 45import { geoLocationManager } from '@kit.LocationKit'; 46``` 47 48## GeoAddress 49 50Geocoding address information. 51 52**System capability**: SystemCapability.Location.Location.Geocoder 53 54| Name| Type| Read Only| Optional| Description| 55| -------- | -------- | -------- | -------- | -------- | 56| isFromMock | Boolean | No| Yes| **true**: The geographic address is obtained from the mock reverse geocoding function.<br>**false**: The geographic address is not obtained from the mock reverse geocoding function.<br>**System API**: This is a system API.| 57 58 59## Location 60 61Location information. 62 63**System capability**: SystemCapability.Location.Location.Core 64 65| Name| Type| Read Only| Optional| Description| 66| -------- | -------- | -------- | -------- | -------- | 67| isFromMock | Boolean | No| Yes| **true**: The location information is obtained from the mock location switch.<br>**false**: The location information is not obtained from the location simulation function.<br>**System API**: This is a system API.| 68 69 70## ReverseGeocodingMockInfo 71 72Defines the configuration of the mock reverse geocoding function. 73 74**System capability**: SystemCapability.Location.Location.Core 75 76**System API**: This is a system API. 77 78| Name| Type| Read Only| Optional| Description| 79| -------- | -------- | -------- | -------- | -------- | 80| location | [ReverseGeoCodeRequest](js-apis-geoLocationManager.md#reversegeocoderequest) | No| No| Latitude and longitude information.| 81| geoAddress | [GeoAddress](#geoaddress) | No| No|Geographical name.| 82 83 84## LocationMockConfig 85 86Defines the configuration of the mock location switch. 87 88**System capability**: SystemCapability.Location.Location.Core 89 90**System API**: This is a system API. 91 92| Name| Type| Read Only| Optional| Description| 93| -------- | -------- | -------- | -------- | -------- | 94| timeInterval | number | No| No| Time interval at which mock locations are reported, in seconds.| 95| locations | Array<[Location](#location)> | No| No| Array of mocked locations.| 96 97## LocatingRequiredDataConfig<sup>10+</sup> 98 99Defines the configuration for obtaining the required data of the location service. 100 101**System capability**: SystemCapability.Location.Location.Core 102 103**System API**: This is a system API. 104 105| Name| Type| Read Only| Optional| Description| 106| -------- | -------- | -------- | -------- | -------- | 107| type | [LocatingRequiredDataType](#locatingrequireddatatype10) | No| No| Type of the required data.| 108| needStartScan | boolean | No| No| **true**: Scanning needs to be initiated.<br>**false**: Scanning does not need to be initiated.| 109| scanInterval | number | No| Yes| Scanning interval, in milliseconds. The specified value must be greater than **0**. The default value is **10000**.| 110| scanTimeout | number | No| Yes| Scanning timeout interval, in milliseconds. The value ranges from **0** to **600000**. The default value is **10000**.| 111 112 113## LocatingRequiredData<sup>10+</sup> 114 115Defines the required data of the location service, including the Wi-Fi or Bluetooth scanning result. After obtaining the data, an application can use the data for services such as network positioning. 116 117**System capability**: SystemCapability.Location.Location.Core 118 119**System API**: This is a system API. 120 121| Name| Type| Read Only| Optional| Description| 122| -------- | -------- | -------- | -------- | -------- | 123| wifiData | [WifiScanInfo](#wifiscaninfo10) | No| Yes| Wi-Fi scanning result.| 124| bluetoothData | [BluetoothScanInfo](#bluetoothscaninfo10) | No| Yes| Bluetooth scanning result.| 125 126 127## WifiScanInfo<sup>10+</sup> 128 129Defines the Wi-Fi scanning information, including the SSID, BSSID, and RSSI of the scanned Wi-Fi hotspot. 130 131**System capability**: SystemCapability.Location.Location.Core 132 133**System API**: This is a system API. 134 135| Name| Type| Read Only| Optional| Description| 136| -------- | -------- | -------- | -------- | -------- | 137| ssid | string | No| No| Service set identifier (SSID) of a Wi-Fi hotspot, in UTF-8 format.| 138| bssid | string | No| No| Base station subsystem identifier (BSSID) of a Wi-Fi hotspot.| 139| rssi | number | No| No| Received signal strength indicator (RSSI) of a Wi-Fi hotspot, in dBm.| 140| frequency | number | No| No| Frequency of a Wi-Fi hotspot.| 141| timestamp | number | No| No| Scanning timestamp.| 142 143 144## BluetoothScanInfo<sup>10+</sup> 145 146Defines the Bluetooth scanning information. 147 148**System capability**: SystemCapability.Location.Location.Core 149 150**System API**: This is a system API. 151 152| Name| Type| Read Only| Optional| Description| 153| -------- | -------- | -------- | -------- | -------- | 154| deviceName | string | No| No| Name of a Bluetooth device.| 155| macAddress | string | No| No| MAC address of a Bluetooth device.| 156| rssi | number | No| No| Signal strength of a Bluetooth device, in dBm.| 157| timestamp | number | No| No| Scanning timestamp.| 158 159## LocationPrivacyType 160 161Defines the privacy statement type. 162 163**System capability**: SystemCapability.Location.Location.Core 164 165**System API**: This is a system API. 166 167| Name| Value| Description| 168| -------- | -------- | -------- | 169| OTHERS | 0 | Other scenarios. Reserved field.| 170| STARTUP | 1 | Privacy statement displayed in the startup wizard. The user needs to choose whether to agree with the statement.| 171| CORE_LOCATION | 2 | Privacy statement displayed when enabling the location service.| 172 173## LocatingRequiredDataType<sup>10+</sup> 174 175Defines the type of the required data of the location service. 176 177**System capability**: SystemCapability.Location.Location.Core 178 179**System API**: This is a system API. 180 181| Name| Value| Description| 182| -------- | -------- | -------- | 183| WIFI | 1 | Wi-Fi scanning information.| 184| BLUETOOTH | 2 | Bluetooth scanning information.| 185 186 187## LocationIconStatus<sup>12+</sup> 188 189Defines the location icon status. 190 191**System capability**: SystemCapability.Location.Location.Core 192 193**System API**: This is a system API. 194 195| Name| Value| Description| 196| -------- | -------- | -------- | 197| LOCATING_NOT_STARTED | 0 | No location services are available and the location icon does not need to be displayed.| 198| LOCATING_STARTED | 1 | Common location is in progress, and the common location icon needs to be displayed.| 199| HD_LOCATING_STARTED | 2 | High-precision location is in progress, and the high-precision location icon needs to be displayed.| 200 201 202## geoLocationManager.on('locatingRequiredDataChange')<sup>10+</sup> 203 204on(type: 'locatingRequiredDataChange', config: LocatingRequiredDataConfig, callback: Callback<Array<LocatingRequiredData>>): void 205 206Subscribes to changes in the required data of the location service, including Wi-Fi and Bluetooth scanning information. An application can then determine whether to enable Wi-Fi and Bluetooth scanning based on the return result. This API uses an asynchronous callback to return the result. 207 208**Required permissions**: ohos.permission.LOCATION and ohos.permission.APPROXIMATELY_LOCATION 209 210**System capability**: SystemCapability.Location.Location.Core 211 212**System API**: This is a system API. 213 214**Parameters** 215 216 | Name| Type| Mandatory| Description| 217 | -------- | -------- | -------- | -------- | 218 | type | string | Yes| Event type. The value **locatingRequiredDataChange** indicates a change in the required data of the location service.| 219 | config | [LocatingRequiredDataConfig](#locatingrequireddataconfig10) | Yes| Configuration for obtaining the required data of the location service.| 220 | callback | Callback<Array<[LocatingRequiredData](#locatingrequireddata10)>> | Yes| Callback used to return the data required by the location service.| 221 222**Error codes** 223 224For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 225 226| ID| Error Message| 227| -------- | ---------------------------------------- | 228|201 | Permission verification failed. The application does not have the permission required to call the API. | 229|202 | Permission verification failed. A non-system application calls a system API. | 230|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 231|801 | Capability not supported. Failed to call ${geoLocationManager.on('locatingRequiredDataChange')} due to limited device capabilities. | 232|3301800 | Failed to start WiFi or Bluetooth scanning. | 233 234**Example** 235 236 ```ts 237 import { geoLocationManager } from '@kit.LocationKit'; 238 let callback = (code:Array<geoLocationManager.LocatingRequiredData>):void => { 239 console.info('locatingRequiredDataChange: ' + JSON.stringify(code)); 240 } 241 let config:geoLocationManager.LocatingRequiredDataConfig = {'type': 1, 'needStartScan': true, 'scanInterval': 10000}; 242 try { 243 geoLocationManager.on('locatingRequiredDataChange', config, callback); 244 } catch (err) { 245 console.error("errCode:" + err.code + ", message:" + err.message); 246 } 247 ``` 248 249 250## geoLocationManager.off('locatingRequiredDataChange')<sup>10+</sup> 251 252off(type: 'locatingRequiredDataChange', callback?: Callback<Array<LocatingRequiredData>>): void 253 254Unsubscribes from changes in the required data of the location service and stops Wi-Fi and Bluetooth scanning. 255 256**Required permissions**: ohos.permission.LOCATION and ohos.permission.APPROXIMATELY_LOCATION 257 258**System capability**: SystemCapability.Location.Location.Core 259 260**System API**: This is a system API. 261 262**Parameters** 263 264 | Name| Type| Mandatory| Description| 265 | -------- | -------- | -------- | -------- | 266 | type | string | Yes| Event type. The value **locatingRequiredDataChange** indicates a change in the required data of the location service.| 267 | callback | Callback<Array<[LocatingRequiredData](#locatingrequireddata10)>> | No| Callback to unregister. The callback must be the same as that passed by the **on** API. If this parameter is not specified, all callbacks of the specified event type are unregistered.| 268 269**Error codes** 270 271For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 272 273| ID| Error Message| 274| -------- | ---------------------------------------- | 275|201 | Permission verification failed. The application does not have the permission required to call the API. | 276|202 | Permission verification failed. A non-system application calls a system API. | 277|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 278|801 | Capability not supported. Failed to call ${geoLocationManager.off('locatingRequiredDataChange')} due to limited device capabilities. | 279 280**Example** 281 282 ```ts 283 import { geoLocationManager } from '@kit.LocationKit'; 284 let callback = (code:Array<geoLocationManager.LocatingRequiredData>):void => { 285 console.info('locatingRequiredDataChange: ' + JSON.stringify(code)); 286 } 287 let config:geoLocationManager.LocatingRequiredDataConfig = {'type': 1, 'needStartScan': true, 'scanInterval': 10000}; 288 try { 289 geoLocationManager.on('locatingRequiredDataChange', config, callback); 290 geoLocationManager.off('locatingRequiredDataChange', callback); 291 } catch (err) { 292 console.error("errCode:" + err.code + ", message:" + err.message); 293 } 294 ``` 295 296## geoLocationManager.enableLocation 297 298enableLocation(callback: AsyncCallback<void>): void 299 300Enables the location service. This API uses an asynchronous callback to return the result. 301 302**System API**: This is a system API. 303 304**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS and ohos.permission.CONTROL_LOCATION_SWITCH 305 306**System capability**: SystemCapability.Location.Location.Core 307 308**Parameters** 309 310 | Name| Type| Mandatory| Description| 311 | -------- | -------- | -------- | -------- | 312 | callback | AsyncCallback<void> | Yes| Callback used to return the result. If the location service is successfully enabled, **err** is **undefined**. Otherwise, **err** is an error object.| 313 314**Error codes** 315 316For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 317 318| ID| Error Message| 319| -------- | ---------------------------------------- | 320|201 | Permission verification failed. The application does not have the permission required to call the API. | 321|202 | Permission verification failed. A non-system application calls a system API. | 322|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 323|801 | Capability not supported. Failed to call ${geoLocationManager.enableLocation} due to limited device capabilities. | 324|3301000 | The location service is unavailable. | 325 326**Example** 327 328 ```ts 329 import { geoLocationManager } from '@kit.LocationKit'; 330 try { 331 geoLocationManager.enableLocation((err) => { 332 if (err) { 333 console.error('enableLocation: err=' + JSON.stringify(err)); 334 } 335 }); 336 } catch (err) { 337 console.error("errCode:" + err.code + ", message:" + err.message); 338 } 339 ``` 340 341 342## geoLocationManager.enableLocation 343 344enableLocation(): Promise<void> 345 346Enables the location service. This API uses a promise to return the result. 347 348**System API**: This is a system API. 349 350**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS and ohos.permission.CONTROL_LOCATION_SWITCH 351 352**System capability**: SystemCapability.Location.Location.Core 353 354**Return value** 355 356 | Type| Description| 357 | -------- | -------- | 358 | Promise<void> | Promise that returns no value.| 359 360**Error codes** 361 362For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 363 364| ID| Error Message| 365| -------- | ---------------------------------------- | 366|201 | Permission verification failed. The application does not have the permission required to call the API. | 367|202 | Permission verification failed. A non-system application calls a system API. | 368|801 | Capability not supported. Failed to call ${geoLocationManager.enableLocation} due to limited device capabilities. | 369|3301000 | The location service is unavailable. | 370 371**Example** 372 373 ```ts 374 import { geoLocationManager } from '@kit.LocationKit'; 375 import { BusinessError } from '@kit.BasicServicesKit'; 376 try { 377 geoLocationManager.enableLocation().then(() => { 378 console.info('promise, enableLocation succeed'); 379 }) 380 .catch((error:BusinessError) => { 381 console.error('promise, enableLocation: error=' + JSON.stringify(error)); 382 }); 383 } catch (err) { 384 console.error("errCode:" + err.code + ", message:" + err.message); 385 } 386 ``` 387 388## geoLocationManager.disableLocation 389 390disableLocation(): void 391 392Disables the location service. 393 394**System API**: This is a system API. 395 396**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS and ohos.permission.CONTROL_LOCATION_SWITCH 397 398**System capability**: SystemCapability.Location.Location.Core 399 400**Error codes** 401 402For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 403 404| ID| Error Message| 405| -------- | ---------------------------------------- | 406|201 | Permission verification failed. The application does not have the permission required to call the API. | 407|202 | Permission verification failed. A non-system application calls a system API. | 408|801 | Capability not supported. Failed to call ${geoLocationManager.disableLocation} due to limited device capabilities. | 409|3301000 | The location service is unavailable. | 410 411**Example** 412 413 ```ts 414 import { geoLocationManager } from '@kit.LocationKit'; 415 try { 416 geoLocationManager.disableLocation(); 417 } catch (err) { 418 console.error("errCode:" + err.code + ", message:" + err.message); 419 } 420 ``` 421 422## geoLocationManager.enableLocationMock 423 424enableLocationMock(): void 425 426Enables the mock location switch. 427 428**System capability**: SystemCapability.Location.Location.Core 429 430**System API**: This is a system API. 431 432**Required permissions**: ohos.permission.MOCK_LOCATION 433 434**Error codes** 435 436For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 437 438| ID| Error Message| 439| -------- | ---------------------------------------- | 440|201 | Permission verification failed. The application does not have the permission required to call the API. | 441|202 | Permission verification failed. A non-system application calls a system API. | 442|801 | Capability not supported. Failed to call ${geoLocationManager.enableLocationMock} due to limited device capabilities. | 443|3301000 | The location service is unavailable. | 444|3301100 | The location switch is off.| 445 446**Example** 447 448 ```ts 449 import { geoLocationManager } from '@kit.LocationKit'; 450 try { 451 geoLocationManager.enableLocationMock(); 452 } catch (err) { 453 console.error("errCode:" + err.code + ", message:" + err.message); 454 } 455 ``` 456 457 458## geoLocationManager.disableLocationMock 459 460disableLocationMock(): void 461 462Disables the mock location switch. 463 464**System capability**: SystemCapability.Location.Location.Core 465 466**System API**: This is a system API. 467 468**Required permissions**: ohos.permission.MOCK_LOCATION 469 470**Error codes** 471 472For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 473 474| ID| Error Message| 475| -------- | ---------------------------------------- | 476|201 | Permission verification failed. The application does not have the permission required to call the API. | 477|202 | Permission verification failed. A non-system application calls a system API. | 478|801 | Capability not supported. Failed to call ${geoLocationManager.disableLocationMock} due to limited device capabilities. | 479|3301000 | The location service is unavailable. | 480|3301100 | The location switch is off.| 481 482**Example** 483 484 ```ts 485 import { geoLocationManager } from '@kit.LocationKit'; 486 try { 487 geoLocationManager.disableLocationMock(); 488 } catch (err) { 489 console.error("errCode:" + err.code + ", message:" + err.message); 490 } 491 ``` 492 493 494## geoLocationManager.setMockedLocations 495 496setMockedLocations(config: LocationMockConfig): void 497 498Sets the mock location information. The mock locations will be reported at the interval specified in this API. 499 500This API can be invoked only after [geoLocationManager.enableLocationMock](#geolocationmanagerenablelocationmock) is called. 501 502**System capability**: SystemCapability.Location.Location.Core 503 504**System API**: This is a system API. 505 506**Required permissions**: ohos.permission.MOCK_LOCATION 507 508**Parameters** 509 510 | Name| Type| Mandatory| Description| 511 | -------- | -------- | -------- | -------- | 512 | config | [LocationMockConfig](#locationmockconfig) | Yes| Mock location information, including the interval for reporting the mock locations and the array of the mock locations.| 513 514**Error codes** 515 516For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 517 518| ID| Error Message| 519| -------- | ---------------------------------------- | 520|201 | Permission verification failed. The application does not have the permission required to call the API. | 521|202 | Permission verification failed. A non-system application calls a system API. | 522|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 523|801 | Capability not supported. Failed to call ${geoLocationManager.setMockedLocations} due to limited device capabilities. | 524|3301000 | The location service is unavailable. | 525|3301100 | The location switch is off.| 526 527**Example** 528 529 ```ts 530 import { geoLocationManager } from '@kit.LocationKit'; 531 let locations:Array<geoLocationManager.Location> = [ 532 {"latitude": 30.12, "longitude": 120.11, "altitude": 123, "accuracy": 1, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 1000000000, "additionSize": 0, "isFromMock": true}, 533 {"latitude": 31.13, "longitude": 121.11, "altitude": 123, "accuracy": 2, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 2000000000, "additionSize": 0, "isFromMock": true}, 534 {"latitude": 32.14, "longitude": 122.11, "altitude": 123, "accuracy": 3, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 3000000000, "additionSize": 0, "isFromMock": true}, 535 {"latitude": 33.15, "longitude": 123.11, "altitude": 123, "accuracy": 4, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 4000000000, "additionSize": 0, "isFromMock": true}, 536 {"latitude": 34.16, "longitude": 124.11, "altitude": 123, "accuracy": 5, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 5000000000, "additionSize": 0, "isFromMock": true} 537 ]; 538 let config:geoLocationManager.LocationMockConfig = {"timeInterval": 5, "locations": locations}; 539 try { 540 geoLocationManager.enableLocationMock(); 541 geoLocationManager.setMockedLocations(config); 542 } catch (err) { 543 console.error("errCode:" + err.code + ", message:" + err.message); 544 } 545 ``` 546 547 548## geoLocationManager.enableReverseGeocodingMock 549 550enableReverseGeocodingMock(): void 551 552Enables the mock reverse geocoding function. 553 554**System capability**: SystemCapability.Location.Location.Core 555 556**System API**: This is a system API. 557 558**Required permissions**: ohos.permission.MOCK_LOCATION 559 560**Error codes** 561 562For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 563 564| ID| Error Message| 565| -------- | ---------------------------------------- | 566|201 | Permission verification failed. The application does not have the permission required to call the API. | 567|202 | Permission verification failed. A non-system application calls a system API. | 568|801 | Capability not supported. Failed to call ${geoLocationManager.enableReverseGeocodingMock} due to limited device capabilities. | 569|3301000 | The location service is unavailable. | 570 571**Example** 572 573 ```ts 574 import { geoLocationManager } from '@kit.LocationKit'; 575 try { 576 geoLocationManager.enableReverseGeocodingMock(); 577 } catch (err) { 578 console.error("errCode:" + err.code + ", message:" + err.message); 579 } 580 ``` 581 582 583## geoLocationManager.disableReverseGeocodingMock 584 585disableReverseGeocodingMock(): void 586 587Disables the mock geocoding function. 588 589**System capability**: SystemCapability.Location.Location.Core 590 591**System API**: This is a system API. 592 593**Required permissions**: ohos.permission.MOCK_LOCATION 594 595**Error codes** 596 597For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 598 599| ID| Error Message| 600| -------- | ---------------------------------------- | 601|201 | Permission verification failed. The application does not have the permission required to call the API. | 602|202 | Permission verification failed. A non-system application calls a system API. | 603|801 | Capability not supported. Failed to call ${geoLocationManager.disableReverseGeocodingMock} due to limited device capabilities. | 604|3301000 | The location service is unavailable. | 605 606**Example** 607 608 ```ts 609 import { geoLocationManager } from '@kit.LocationKit'; 610 try { 611 geoLocationManager.disableReverseGeocodingMock(); 612 } catch (err) { 613 console.error("errCode:" + err.code + ", message:" + err.message); 614 } 615 ``` 616 617 618## geoLocationManager.setReverseGeocodingMockInfo 619 620setReverseGeocodingMockInfo(mockInfos: Array<ReverseGeocodingMockInfo>): void 621 622Sets information of the mock reverse geocoding function, including the mapping between a location and geographical name. If the location is contained in the configurations during reverse geocoding query, the corresponding geographical name will be returned. 623 624This API can be invoked only after [geoLocationManager.enableReverseGeocodingMock](#geolocationmanagerenablereversegeocodingmock) is called. 625 626**System capability**: SystemCapability.Location.Location.Core 627 628**System API**: This is a system API. 629 630**Required permissions**: ohos.permission.MOCK_LOCATION 631 632**Parameters** 633 634 | Name| Type| Mandatory| Description| 635 | -------- | -------- | -------- | -------- | 636 | mockInfos | Array<[ReverseGeocodingMockInfo](#reversegeocodingmockinfo)> | Yes| Array of information of the mock reverse geocoding function, including a location and a geographical name.| 637 638**Error codes** 639 640For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 641 642| ID| Error Message| 643| -------- | ---------------------------------------- | 644|201 | Permission verification failed. The application does not have the permission required to call the API. | 645|202 | Permission verification failed. A non-system application calls a system API. | 646|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 647|801 | Capability not supported. Failed to call ${geoLocationManager.setReverseGeocodingMockInfo} due to limited device capabilities. | 648|3301000 | The location service is unavailable. | 649 650**Example** 651 652 ```ts 653 import { geoLocationManager } from '@kit.LocationKit'; 654 let mockInfos:Array<geoLocationManager.ReverseGeocodingMockInfo> = [ 655 {"location": {"locale": "zh", "latitude": 30.12, "longitude": 120.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 30.12, "longitude": 120.11, "isFromMock": true}}, 656 {"location": {"locale": "zh", "latitude": 31.12, "longitude": 121.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 31.12, "longitude": 121.11, "isFromMock": true}}, 657 {"location": {"locale": "zh", "latitude": 32.12, "longitude": 122.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 32.12, "longitude": 122.11, "isFromMock": true}}, 658 {"location": {"locale": "zh", "latitude": 33.12, "longitude": 123.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 33.12, "longitude": 123.11, "isFromMock": true}}, 659 {"location": {"locale": "zh", "latitude": 34.12, "longitude": 124.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 34.12, "longitude": 124.11, "isFromMock": true}}, 660 ]; 661 try { 662 geoLocationManager.enableReverseGeocodingMock(); 663 geoLocationManager.setReverseGeocodingMockInfo(mockInfos); 664 } catch (err) { 665 console.error("errCode:" + err.code + ", message:" + err.message); 666 } 667 ``` 668 669 670## geoLocationManager.isLocationPrivacyConfirmed 671 672isLocationPrivacyConfirmed(type: LocationPrivacyType): boolean 673 674Checks whether a user agrees with the privacy statement of the location service. This API can only be called by system applications. 675 676**System API**: This is a system API. 677 678**System capability**: SystemCapability.Location.Location.Core 679 680**Parameters** 681 682 | Name| Type| Mandatory| Description| 683 | -------- | -------- | -------- | -------- | 684 | type | [LocationPrivacyType](#locationprivacytype)| Yes| Privacy statement type, for example, privacy statement displayed in the startup wizard or privacy statement displayed when the location service is enabled.| 685 686**Return value** 687 688 | Type| Description| 689 | -------- | -------- | 690 | boolean | **true**: The user agrees to the privacy statement of the location service.<br>**false**: The user does not agree to the privacy statement of the location service.| 691 692**Error codes** 693 694For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 695 696| ID| Error Message| 697| -------- | ---------------------------------------- | 698|202 | Permission verification failed. A non-system application calls a system API. | 699|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 700|801 | Capability not supported. Failed to call ${geoLocationManager.isLocationPrivacyConfirmed} due to limited device capabilities. | 701|3301000 | The location service is unavailable. | 702 703**Example** 704 705 ```ts 706 import { geoLocationManager } from '@kit.LocationKit'; 707 try { 708 let isConfirmed = geoLocationManager.isLocationPrivacyConfirmed(1); 709 } catch (err) { 710 console.error("errCode:" + err.code + ", message:" + err.message); 711 } 712 ``` 713 714 715## geoLocationManager.setLocationPrivacyConfirmStatus 716 717setLocationPrivacyConfirmStatus(type: LocationPrivacyType, isConfirmed: boolean): void 718 719Sets the user confirmation status for the privacy statement of the location service. This API can only be called by system applications. 720 721**System API**: This is a system API. 722 723**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS 724 725**System capability**: SystemCapability.Location.Location.Core 726 727**Parameters** 728 729 | Name| Type| Mandatory| Description| 730 | -------- | -------- | -------- | -------- | 731 | type | [LocationPrivacyType](#locationprivacytype) | Yes| Privacy statement type, for example, privacy statement displayed in the startup wizard or privacy statement displayed when the location service is enabled.| 732 | isConfirmed | boolean | Yes| **true**: The user agrees to the privacy statement of the location service.<br>**false**: The user does not agree to the privacy statement of the location service.| 733 734**Error codes** 735 736For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 737 738| ID| Error Message| 739| -------- | ---------------------------------------- | 740|201 | Permission verification failed. The application does not have the permission required to call the API. | 741|202 | Permission verification failed. A non-system application calls a system API. | 742|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 743|801 | Capability not supported. Failed to call ${geoLocationManager.setLocationPrivacyConfirmStatus} due to limited device capabilities. | 744|3301000 | The location service is unavailable. | 745 746**Example** 747 748 ```ts 749 import { geoLocationManager } from '@kit.LocationKit'; 750 try { 751 geoLocationManager.setLocationPrivacyConfirmStatus(1, true); 752 } catch (err) { 753 console.error("errCode:" + err.code + ", message:" + err.message); 754 } 755 ``` 756 757 758## geoLocationManager.getLocatingRequiredData<sup>10+</sup> 759 760getLocatingRequiredData(config: LocatingRequiredDataConfig): Promise<Array<LocatingRequiredData>> 761 762Obtains the required data of the location service. This API uses a promise to return the result. 763 764**Required permissions**: ohos.permission.LOCATION and ohos.permission.APPROXIMATELY_LOCATION 765 766**System capability**: SystemCapability.Location.Location.Core 767 768**System API**: This is a system API. 769 770**Parameters** 771 772 | Name| Type| Mandatory| Description| 773 | -------- | -------- | -------- | -------- | 774 | config | [LocatingRequiredDataConfig](#locatingrequireddataconfig10) | Yes| Configuration for obtaining the required data of the location service.| 775 776**Return value** 777 778 | Type| Description| 779 | -------- | -------- | 780 | Promise<Array<[LocatingRequiredData](#locatingrequireddata10)>> | Promise used to return the required data for the location service, such as the Wi-Fi and Bluetooth scanning information.| 781 782**Error codes** 783 784For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 785 786| ID| Error Message| 787| -------- | ---------------------------------------- | 788|201 | Permission verification failed. The application does not have the permission required to call the API. | 789|202 | Permission verification failed. A non-system application calls a system API. | 790|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 791|801 | Capability not supported. Failed to call ${geoLocationManager.getLocatingRequiredData} due to limited device capabilities. | 792|3301800 | Failed to start WiFi or Bluetooth scanning. | 793 794**Example** 795 796 ```ts 797 import { geoLocationManager } from '@kit.LocationKit'; 798 import { BusinessError } from '@kit.BasicServicesKit'; 799 let config:geoLocationManager.LocatingRequiredDataConfig = {'type': 1, 'needStartScan': true, 'scanInterval': 10000}; 800 try { 801 geoLocationManager.getLocatingRequiredData(config).then((result) => { 802 console.info('getLocatingRequiredData return: ' + JSON.stringify(result)); 803 }) 804 .catch((error:BusinessError) => { 805 console.error('promise, getLocatingRequiredData: error=' + JSON.stringify(error)); 806 }); 807 } catch (err) { 808 console.error("errCode:" + err.code + ", message:" + err.message); 809 } 810 ``` 811 812 813## geoLocationManager.on('locationIconStatusChange')<sup>12+</sup> 814 815on(type: 'locationIconStatusChange', callback: Callback<LocationIconStatus>): void 816 817Subscribes to status changes of the location icon. This API uses an asynchronous callback to return the result. 818 819**System capability**: SystemCapability.Location.Location.Core 820 821**System API**: This is a system API. 822 823**Parameters** 824 825 | Name| Type| Mandatory| Description| 826 | -------- | -------- | -------- | -------- | 827 | type | string | Yes| Event type. Event type. The value **locationIconStatusChange** indicates status changes of the location icon.| 828 | callback | Callback<[LocationIconStatus](#locationiconstatus12)> | Yes| Callback used to return the location icon status.| 829 830**Error codes** 831 832For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 833 834| ID| Error Message| 835| -------- | ---------------------------------------- | 836|202 | Permission verification failed. A non-system application calls a system API. | 837|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 838|801 | Capability not supported. Failed to call ${geoLocationManager.on('locationIconStatusChange')} due to limited device capabilities. | 839|3301000 | The location service is unavailable. | 840 841**Example** 842 843 ```ts 844 import { geoLocationManager } from '@kit.LocationKit'; 845 let callback = (code: geoLocationManager.LocationIconStatus):void => { 846 console.info('LocationIconStatus: ' + JSON.stringify(code)); 847 } 848 try { 849 geoLocationManager.on('locationIconStatusChange', callback); 850 } catch (err) { 851 console.error("errCode:" + err.code + ", message:" + err.message); 852 } 853 ``` 854 855 856## geoLocationManager.off('locationIconStatusChange')<sup>12+</sup> 857 858off(type: 'locationIconStatusChange', callback?: Callback<LocationIconStatus>): void 859 860Unsubscribes from status changes of the location icon. 861 862**System capability**: SystemCapability.Location.Location.Core 863 864**System API**: This is a system API. 865 866**Parameters** 867 868 | Name| Type| Mandatory| Description| 869 | -------- | -------- | -------- | -------- | 870 | type | string | Yes| Event type. Event type. The value **locationIconStatusChange** indicates status changes of the location icon.| 871 | callback | Callback<[LocationIconStatus](#locationiconstatus12)> | No| Callback to unregister. The callback must be the same as that passed by the **on** API. If this parameter is not specified, all callbacks of the specified event type are unregistered.| 872 873**Error codes** 874 875For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 876 877| ID| Error Message| 878| -------- | ---------------------------------------- | 879|202 | Permission verification failed. A non-system application calls a system API. | 880|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 881|801 | Capability not supported. Failed to call ${geoLocationManager.off('locationIconStatusChange')} due to limited device capabilities. | 882|3301000 | The location service is unavailable. | 883 884**Example** 885 886 ```ts 887 import { geoLocationManager } from '@kit.LocationKit'; 888 let callback = (code: geoLocationManager.LocationIconStatus):void => { 889 console.info('LocationIconStatus: ' + JSON.stringify(code)); 890 } 891 try { 892 geoLocationManager.on('locationIconStatusChange', callback); 893 geoLocationManager.off('locationIconStatusChange', callback); 894 } catch (err) { 895 console.error("errCode:" + err.code + ", message:" + err.message); 896 } 897 ``` 898 899 900## geoLocationManager.getLocationIconStatus<sup>12+</sup> 901 902getLocationIconStatus(): LocationIconStatus 903 904Obtains the current location icon status. 905 906**System capability**: SystemCapability.Location.Location.Core 907 908**System API**: This is a system API. 909 910**Return value** 911 912 | Type| Description| 913 | -------- | -------- | 914 | [LocationIconStatus](#locationiconstatus12) | Location icon status.| 915 916**Error codes** 917 918For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 919 920| ID| Error Message| 921| -------- | ---------------------------------------- | 922|202 | Permission verification failed. A non-system application calls a system API. | 923|801 | Capability not supported. Failed to call ${geoLocationManager.getLocationIconStatus} due to limited device capabilities. | 924|3301000 | The location service is unavailable. | 925 926**Example** 927 928 ```ts 929 import { geoLocationManager } from '@kit.LocationKit'; 930 try { 931 let iconStatus = geoLocationManager.getLocationIconStatus(); 932 } catch (err) { 933 console.error("errCode:" + err.code + ", message:" + err.message); 934 } 935 ``` 936 937 938## geoLocationManager.enableLocationByUserId<sup>18+</sup> 939 940enableLocationByUserId(userId: number): Promise<void> 941 942Enables the location switch for the specified system account. This API uses a promise to return the result. 943 944**System API**: This is a system API. 945 946**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS and ohos.permission.CONTROL_LOCATION_SWITCH 947 948**System capability**: SystemCapability.Location.Location.Core 949 950**Parameters** 951 952 | Name| Type| Mandatory| Description| 953 | -------- | -------- | -------- | -------- | 954 | userId | number | Yes| System account ID. For details about how to obtain the system account ID, see [Obtaining All System Accounts](../../basic-services/account/manage-os-account.md#obtaining-all-system-accounts).| 955 956**Return value** 957 958 | Type| Description| 959 | -------- | -------- | 960 | Promise<void> | Promise that returns no value.| 961 962**Error codes** 963 964For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 965 966| ID| Error Message| 967| -------- | ---------------------------------------- | 968|201 | Permission verification failed. The application does not have the permission required to call the API. | 969|202 | Permission verification failed. A non-system application calls a system API. | 970|801 | Capability not supported. Failed to call ${geoLocationManager.enableLocationByUserId} due to limited device capabilities. | 971|3301000 | The location service is unavailable. | 972 973**Example** 974 975 ```ts 976 import { geoLocationManager } from '@kit.LocationKit'; 977 import { BusinessError } from '@kit.BasicServicesKit'; 978 try { 979 // Enable the location switch for the specified system account. For example, if the account ID is below 101, you can enable the location switch for the account whose ID is 100. 980 let userId:number = 100; 981 geoLocationManager.enableLocationByUserId(userId).then(() => { 982 console.info('promise, enableLocationByUserId succeed'); 983 }) 984 .catch((error:BusinessError) => { 985 console.error('promise, enableLocationByUserId: error=' + JSON.stringify(error)); 986 }); 987 } catch (err) { 988 console.error("errCode:" + err.code + ", message:" + err.message); 989 } 990 ``` 991 992 993## geoLocationManager.disableLocationByUserId<sup>18+</sup> 994 995disableLocationByUserId(userId: number): void 996 997Disables the location switch for the specified system account. 998 999**System API**: This is a system API. 1000 1001**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS and ohos.permission.CONTROL_LOCATION_SWITCH 1002 1003**System capability**: SystemCapability.Location.Location.Core 1004 1005**Parameters** 1006 1007 | Name| Type| Mandatory| Description| 1008 | -------- | -------- | -------- | -------- | 1009 | userId | number | Yes| System account ID. For details about how to obtain the system account ID, see [Obtaining All System Accounts](../../basic-services/account/manage-os-account.md#obtaining-all-system-accounts).| 1010 1011**Error codes** 1012 1013For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 1014 1015| ID| Error Message| 1016| -------- | ---------------------------------------- | 1017|201 | Permission verification failed. The application does not have the permission required to call the API. | 1018|202 | Permission verification failed. A non-system application calls a system API. | 1019|801 | Capability not supported. Failed to call ${geoLocationManager.disableLocationByUserId} due to limited device capabilities. | 1020|3301000 | The location service is unavailable. | 1021 1022**Example** 1023 1024 ```ts 1025 import { geoLocationManager } from '@kit.LocationKit'; 1026 try { 1027 // Disable the location switch for the specified system account. For example, if the account ID is below 101, you can disable the location switch for the account whose ID is 100. 1028 let userId:number = 100; 1029 geoLocationManager.disableLocationByUserId(userId); 1030 } catch (err) { 1031 console.error("errCode:" + err.code + ", message:" + err.message); 1032 } 1033 ``` 1034 1035 1036## geoLocationManager.isLocationEnabledByUserId<sup>18+</sup> 1037 1038isLocationEnabledByUserId(userId: number): boolean 1039 1040Checks whether the location switch is enabled for the specified system account. 1041 1042**System API**: This is a system API. 1043 1044**System capability**: SystemCapability.Location.Location.Core 1045 1046**Parameters** 1047 1048 | Name| Type| Mandatory| Description| 1049 | -------- | -------- | -------- | -------- | 1050 | userId | number | Yes| System account ID. For details about how to obtain the system account ID, see [Obtaining All System Accounts](../../basic-services/account/manage-os-account.md#obtaining-all-system-accounts).| 1051 1052**Return value** 1053 1054 | Type| Description| 1055 | -------- | -------- | 1056 | boolean | **true**: The location switch is enabled.<br>**false**: The location switch is disabled.| 1057 1058**Error codes** 1059 1060For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 1061 1062| ID| Error Message| 1063| -------- | ---------------------------------------- | 1064|202 | Permission verification failed. A non-system application calls a system API. | 1065|801 | Capability not supported. Failed to call ${geoLocationManager.isLocationEnabled} due to limited device capabilities. | 1066|3301000 | The location service is unavailable. | 1067 1068**Example** 1069 1070 ```ts 1071 import { geoLocationManager } from '@kit.LocationKit'; 1072 try { 1073 // Check whether the location switch is enabled for the specified system account. For example, if the account ID is below 101, you can check whether the location switch is enabled for the account whose ID is 100. 1074 let userId:number = 100; 1075 let locationEnabled = geoLocationManager.isLocationEnabledByUserId(userId); 1076 } catch (err) { 1077 console.error("errCode:" + err.code + ", message:" + err.message); 1078 } 1079 ``` 1080 1081 1082## geoLocationManager.setLocationSwitchIgnored<sup>18+</sup> 1083 1084setLocationSwitchIgnored(isIgnored: boolean): void 1085 1086Sets whether the location switch is ignored. 1087 1088If this parameter is set to **true**, the application can obtain the location information when the location switch is disabled. The setting takes effect 2 minutes after the API is successfully called. 1089 1090**System API**: This is a system API. 1091 1092**Required permissions**: ohos.permission.LOCATION_SWITCH_IGNORED 1093 1094**System capability**: SystemCapability.Location.Location.Core 1095 1096**Parameters** 1097 1098 | Name| Type| Mandatory| Description| 1099 | -------- | -------- | -------- | -------- | 1100 | isIgnored | boolean | Yes| **true**: The application can obtain location information when the location switch is disabled. The setting takes effect 2 minutes after the API is successfully called.<br>**false**: The application cannot obtain location information when the location switch is disabled.| 1101 1102**Error codes** 1103 1104For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md). 1105 1106| ID| Error Message| 1107| -------- | ---------------------------------------- | 1108|201 | Permission verification failed. The application does not have the permission required to call the API. | 1109|202 | Permission verification failed. A non-system application calls a system API. | 1110|801 | Capability not supported. Failed to call ${geoLocationManager.disableLocationByUserId} due to limited device capabilities. | 1111|3301000 | The location service is unavailable. | 1112 1113**Example** 1114 1115 ```ts 1116 import { geoLocationManager } from '@kit.LocationKit'; 1117 try { 1118 let isIgnored:boolean = true; 1119 geoLocationManager.setLocationSwitchIgnored(isIgnored); 1120 } catch (err) { 1121 console.error("errCode:" + err.code + ", message:" + err.message); 1122 } 1123 ``` 1124