@ohos.geoLocationManager (Geolocation Manager) (System API)

The geoLocationManager module provides location services such as Global Navigation Satellite System (GNSS)-based positioning, network positioning, geofencing, as well as geocoding and reverse geocoding.

NOTE

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. This topic describes only system APIs provided by the module. For details about its public APIs, see @ohos.geoLocationManager (Geolocation Manager). This module supports only the WGS-84 coordinate system.

Applying for Permissions

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 as described below.

The system provides the following location permissions:

  • ohos.permission.LOCATION

  • ohos.permission.APPROXIMATELY_LOCATION

  • ohos.permission.LOCATION_IN_BACKGROUND

If your application needs to access the device location information, it must first apply for required permissions. Specifically speaking:

API versions earlier than 9: Apply for ohos.permission.LOCATION.

API 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.

API Version Location Permission Permission Application Result Location Accuracy
Earlier than 9 ohos.permission.LOCATION Success Location accurate to meters
9 and later ohos.permission.LOCATION Failure No location obtained
9 and later ohos.permission.APPROXIMATELY_LOCATION Success Location accurate to 5 kilometers
9 and later ohos.permission.APPROXIMATELY_LOCATION and ohos.permission.LOCATION Success Location accurate to meters

To access the device location information when running in the background, an application needs to request for the ohos.permission.LOCATION_IN_BACKGROUND permission or a continuous task of the background mode. In this way, the system continues to report device location information after your application moves to the background.

A 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.

For details about how to request for a continuous task, see Continuous Task.

You can declare the required permission in your application's configuration file. For details, see Requesting User Authorization.

Modules to Import

import geoLocationManager from '@ohos.geoLocationManager';

GeoAddress

Geocoding address information.

System capability: SystemCapability.Location.Location.Geocoder

Name Type Readable Writable Description
isFromMock Boolean Yes No Whether the geographical name is from the mock reverse geocoding function.
System API: This is a system API.

Location

Location information.

System capability: SystemCapability.Location.Location.Core

Name Type Readable Writable Description
isFromMock Boolean Yes No Whether the location information is from the mock location function.
System API: This is a system API.

ReverseGeocodingMockInfo

Defines the configuration of the mock reverse geocoding function.

System capability: SystemCapability.Location.Location.Core

System API: This is a system API.

Name Type Readable Writable Description
location ReverseGeoCodeRequest Yes Yes Latitude and longitude information.
geoAddress GeoAddress Yes Yes Geographical name.

LocationMockConfig

Defines the configuration of the mock location function.

System capability: SystemCapability.Location.Location.Core

System API: This is a system API.

Name Type Readable Writable Description
timeInterval number Yes Yes Time interval at which mock locations are reported, in seconds.
locations Array<Location> Yes Yes Array of mocked locations.

LocatingRequiredDataConfig10+

Defines the configuration for obtaining the required data of the location service.

System capability: SystemCapability.Location.Location.Core

System API: This is a system API.

Name Type Readable Writable Description
type LocatingRequiredDataType Yes Yes Type of the required data.
needStartScan boolean Yes Yes Whether to initiate scanning.
scanInterval number Yes Yes Scanning interval, in milliseconds. The specified value must be greater than 0. The default value is 10000.
scanTimeout number Yes Yes Scanning timeout interval, in milliseconds. The value ranges from 0 to 600000. The default value is 10000.

LocatingRequiredData10+

Defines 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.

System capability: SystemCapability.Location.Location.Core

System API: This is a system API.

Name Type Readable Writable Description
wifiData WifiScanInfo Yes No Wi-Fi scanning result.
bluetoothData BluetoothScanInfo Yes No Bluetooth scanning result.

WifiScanInfo10+

Defines the Wi-Fi scanning information, including the SSID, BSSID, and RSSI of the scanned Wi-Fi hotspot.

System capability: SystemCapability.Location.Location.Core

System API: This is a system API.

Name Type Readable Writable Description
ssid string Yes No Service set identifier (SSID) of a Wi-Fi hotspot, in UTF-8 format.
bssid string Yes No Base station subsystem identifier (BSSID) of a Wi-Fi hotspot.
rssi number Yes No Received signal strength indicator (RSSI) of a Wi-Fi hotspot, in dBm.
frequency number Yes No Frequency of a Wi-Fi hotspot.
timestamp number Yes No Scanning timestamp.

BluetoothScanInfo10+

Defines the Bluetooth scanning information.

System capability: SystemCapability.Location.Location.Core

System API: This is a system API.

Name Type Readable Writable Description
deviceName string Yes No Name of a Bluetooth device.
macAddress string Yes No MAC address of a Bluetooth device.
rssi number Yes No Signal strength of a Bluetooth device, in dBm.
timestamp number Yes No Scanning timestamp.

LocationPrivacyType

Defines the privacy statement type.

System capability: SystemCapability.Location.Location.Core

System API: This is a system API.

Name Value Description
OTHERS 0 Other scenarios. Reserved field.
STARTUP 1 Privacy statement displayed in the startup wizard. The user needs to choose whether to agree with the statement.
CORE_LOCATION 2 Privacy statement displayed when enabling the location service.

LocatingRequiredDataType10+

Defines the type of the required data of the location service.

System capability: SystemCapability.Location.Location.Core

System API: This is a system API.

Name Value Description
WIFI 1 Wi-Fi scanning information.
BLUETOOTH 2 Bluetooth scanning information.

geoLocationManager.on('locatingRequiredDataChange')10+

on(type: 'locatingRequiredDataChange', config: LocatingRequiredDataConfig, callback: Callback<Array<LocatingRequiredData>>): void;

Subscribes 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.

Required permissions: ohos.permission.LOCATION and ohos.permission.APPROXIMATELY_LOCATION

System capability: SystemCapability.Location.Location.Core

System API: This is a system API.

Parameters

Name Type Mandatory Description
type string Yes Event type. The value locatingRequiredDataChange indicates a change in the required data of the location service.
config LocatingRequiredDataConfig Yes Configuration for obtaining the required data of the location service.
callback Callback<Array<LocatingRequiredData>> Yes Callback used to receive the required data of the location service.

Error codes

For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md).

ID Error Message
3301800 Failed to start WiFi or Bluetooth scanning.

Example

import geoLocationManager from '@ohos.geoLocationManager';
import BusinessError from "@ohos.base";
let callback = (code:Array<geoLocationManager.LocatingRequiredData>):void => {
    console.log('locatingRequiredDataChange: ' + JSON.stringify(code));
}
let config:geoLocationManager.LocatingRequiredDataConfig = {'type': 1, 'needStartScan': true, 'scanInterval': 10000};
try {
    geoLocationManager.on('locatingRequiredDataChange', config, callback);
} catch (err) {
    console.error("errCode:" + (err as BusinessError.BusinessError).code + ",errMessage:" + (err as BusinessError.BusinessError).message);
}

geoLocationManager.off('locatingRequiredDataChange')10+

off(type: 'locatingRequiredDataChange', callback?: Callback<Array<LocatingRequiredData>>): void;

Unsubscribes from changes in the required data of the location service and stops Wi-Fi and Bluetooth scanning.

Required permissions: ohos.permission.LOCATION and ohos.permission.APPROXIMATELY_LOCATION

System capability: SystemCapability.Location.Location.Core

System API: This is a system API.

Parameters

Name Type Mandatory Description
type string Yes Event type. The value locatingRequiredDataChange indicates a change in the required data of the location service.
callback Callback<Array<LocatingRequiredData>> No Callback to unregister. If this parameter is not specified, all callbacks of the specified event type are unregistered.

Error codes

For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md).

Example

import geoLocationManager from '@ohos.geoLocationManager';
import BusinessError from "@ohos.base";
let callback = (code:Array<geoLocationManager.LocatingRequiredData>):void => {
    console.log('locatingRequiredDataChange: ' + JSON.stringify(code));
}
let config:geoLocationManager.LocatingRequiredDataConfig = {'type': 1, 'needStartScan': true, 'scanInterval': 10000};
try {
    geoLocationManager.on('locatingRequiredDataChange', config, callback);
    geoLocationManager.off('locatingRequiredDataChange', callback);
} catch (err) {
    console.error("errCode:" + (err as BusinessError.BusinessError).code + ",errMessage:" + (err as BusinessError.BusinessError).message);
}

geoLocationManager.enableLocation

enableLocation(callback: AsyncCallback<void>): void;

Enables the location service. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.MANAGE_SECURE_SETTINGS

System capability: SystemCapability.Location.Location.Core

Parameters

Name Type Mandatory Description
callback AsyncCallback<void> Yes Callback used to receive the error message.

Error codes

For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md).

ID Error Message
3301000 Location service is unavailable.

Example

import geoLocationManager from '@ohos.geoLocationManager';
import BusinessError from "@ohos.base";
try {
    geoLocationManager.enableLocation((err) => {
        if (err) {
            console.error('enableLocation: err=' + JSON.stringify(err));
        }
    });
} catch (err) {
    console.error("errCode:" + (err as BusinessError.BusinessError).code + ",errMessage:" + (err as BusinessError.BusinessError).message);
}

geoLocationManager.enableLocation

enableLocation(): Promise<void>

Enables the location service. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.MANAGE_SECURE_SETTINGS

System capability: SystemCapability.Location.Location.Core

Return value

Type Description
Promise<void> Promise used to return the result.

Error codes

For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md).

ID Error Message
3301000 Location service is unavailable.

Example

import geoLocationManager from '@ohos.geoLocationManager';
import BusinessError from "@ohos.base";
try {
    geoLocationManager.enableLocation().then(() => {
        console.log('promise, enableLocation succeed');
    })
    .catch((error:number) => {
        console.error('promise, enableLocation: error=' + JSON.stringify(error));
    });
} catch (err) {
    console.error("errCode:" + (err as BusinessError.BusinessError).code + ",errMessage:" + (err as BusinessError.BusinessError).message);
}

geoLocationManager.disableLocation

disableLocation(): void;

Disables the location service.

System API: This is a system API.

Required permissions: ohos.permission.MANAGE_SECURE_SETTINGS

System capability: SystemCapability.Location.Location.Core

Error codes

For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md).

ID Error Message
3301000 Location service is unavailable.

Example

import geoLocationManager from '@ohos.geoLocationManager';
import BusinessError from "@ohos.base";
try {
    geoLocationManager.disableLocation();
} catch (err) {
    console.error("errCode:" + (err as BusinessError.BusinessError).code + ",errMessage:" + (err as BusinessError.BusinessError).message);
}

geoLocationManager.enableLocationMock

enableLocationMock(): void;

Enables the mock location function.

System capability: SystemCapability.Location.Location.Core

System API: This is a system API.

Error codes

For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md).

ID Error Message
3301000 Location service is unavailable.
3301100 The location switch is off.

Example

import geoLocationManager from '@ohos.geoLocationManager';
import BusinessError from "@ohos.base";
try {
    geoLocationManager.enableLocationMock();
} catch (err) {
    console.error("errCode:" + (err as BusinessError.BusinessError).code + ",errMessage:" + (err as BusinessError.BusinessError).message);
}

geoLocationManager.disableLocationMock

disableLocationMock(): void;

Disables the mock location function.

System capability: SystemCapability.Location.Location.Core

System API: This is a system API.

Error codes

For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md).

ID Error Message
3301000 Location service is unavailable.
3301100 The location switch is off.

Example

import geoLocationManager from '@ohos.geoLocationManager';
import BusinessError from "@ohos.base";
try {
    geoLocationManager.disableLocationMock();
} catch (err) {
    console.error("errCode:" + (err as BusinessError.BusinessError).code + ",errMessage:" + (err as BusinessError.BusinessError).message);
}

geoLocationManager.setMockedLocations

setMockedLocations(config: LocationMockConfig): void;

Sets the mock location information. The mock locations will be reported at the interval specified in this API.

This API can be invoked only after geoLocationManager.enableLocationMock is called.

System capability: SystemCapability.Location.Location.Core

System API: This is a system API.

Parameters

Name Type Mandatory Description
config LocationMockConfig Yes Mock location information, including the interval for reporting the mock locations and the array of the mock locations.

Error codes

For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md).

ID Error Message
3301000 Location service is unavailable.
3301100 The location switch is off.

Example

import geoLocationManager from '@ohos.geoLocationManager';
import BusinessError from "@ohos.base";
let locations:Array<geoLocationManager.Location> = [
    {"latitude": 30.12, "longitude": 120.11, "altitude": 123, "accuracy": 1, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 1000000000, "additionSize": 0, "isFromMock": true},
    {"latitude": 31.13, "longitude": 121.11, "altitude": 123, "accuracy": 2, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 2000000000, "additionSize": 0, "isFromMock": true},
    {"latitude": 32.14, "longitude": 122.11, "altitude": 123, "accuracy": 3, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 3000000000, "additionSize": 0, "isFromMock": true},
    {"latitude": 33.15, "longitude": 123.11, "altitude": 123, "accuracy": 4, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 4000000000, "additionSize": 0, "isFromMock": true},
    {"latitude": 34.16, "longitude": 124.11, "altitude": 123, "accuracy": 5, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 5000000000, "additionSize": 0, "isFromMock": true}
];
let config:geoLocationManager.LocationMockConfig = {"timeInterval": 5, "locations": locations};
try {
    geoLocationManager.enableLocationMock();
    geoLocationManager.setMockedLocations(config);
} catch (err) {
    console.error("errCode:" + (err as BusinessError.BusinessError).code + ",errMessage:" + (err as BusinessError.BusinessError).message);
}

geoLocationManager.enableReverseGeocodingMock

enableReverseGeocodingMock(): void;

Enables the mock reverse geocoding function.

System capability: SystemCapability.Location.Location.Core

System API: This is a system API.

Error codes

For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md).

ID Error Message
3301000 Location service is unavailable.

Example

import geoLocationManager from '@ohos.geoLocationManager';
import BusinessError from "@ohos.base";
try {
    geoLocationManager.enableReverseGeocodingMock();
} catch (err) {
    console.error("errCode:" + (err as BusinessError.BusinessError).code + ",errMessage:" + (err as BusinessError.BusinessError).message);
}

geoLocationManager.disableReverseGeocodingMock

disableReverseGeocodingMock(): void;

Disables the mock geocoding function.

System capability: SystemCapability.Location.Location.Core

System API: This is a system API.

Error codes

For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md).

ID Error Message
3301000 Location service is unavailable.

Example

import geoLocationManager from '@ohos.geoLocationManager';
import BusinessError from "@ohos.base";
try {
    geoLocationManager.disableReverseGeocodingMock();
} catch (err) {
    console.error("errCode:" + (err as BusinessError.BusinessError).code + ",errMessage:" + (err as BusinessError.BusinessError).message);
}

geoLocationManager.setReverseGeocodingMockInfo

setReverseGeocodingMockInfo(mockInfos: Array<ReverseGeocodingMockInfo>): void;

Sets 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.

This API can be invoked only after geoLocationManager.enableReverseGeocodingMock is called.

System capability: SystemCapability.Location.Location.Core

System API: This is a system API.

Parameters

Name Type Mandatory Description
mockInfos Array<ReverseGeocodingMockInfo> Yes Array of information of the mock reverse geocoding function, including a location and a geographical name.

Error codes

For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md).

ID Error Message
3301000 Location service is unavailable.

Example

import geoLocationManager from '@ohos.geoLocationManager';
import BusinessError from "@ohos.base";
let mockInfos:Array<geoLocationManager.ReverseGeocodingMockInfo> = [
    {"location": {"locale": "zh", "latitude": 30.12, "longitude": 120.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 30.12, "longitude": 120.11, "isFromMock": true}},
    {"location": {"locale": "zh", "latitude": 31.12, "longitude": 121.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 31.12, "longitude": 121.11, "isFromMock": true}},
    {"location": {"locale": "zh", "latitude": 32.12, "longitude": 122.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 32.12, "longitude": 122.11, "isFromMock": true}},
    {"location": {"locale": "zh", "latitude": 33.12, "longitude": 123.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 33.12, "longitude": 123.11, "isFromMock": true}},
    {"location": {"locale": "zh", "latitude": 34.12, "longitude": 124.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 34.12, "longitude": 124.11, "isFromMock": true}},
];
try {
    geoLocationManager.enableReverseGeocodingMock();
    geoLocationManager.setReverseGeocodingMockInfo(mockInfos);
} catch (err) {
    console.error("errCode:" + (err as BusinessError.BusinessError).code + ",errMessage:" + (err as BusinessError.BusinessError).message);
}

geoLocationManager.isLocationPrivacyConfirmed

isLocationPrivacyConfirmed(type: LocationPrivacyType): boolean;

Checks whether a user agrees with the privacy statement of the location service. This API can only be called by system applications.

System API: This is a system API.

System capability: SystemCapability.Location.Location.Core

Parameters

Name Type Mandatory Description
type LocationPrivacyType Yes Privacy statement type, for example, privacy statement displayed in the startup wizard or privacy statement displayed when the location service is enabled.

Return value

Type Description
boolean Whether the user agrees with the privacy statement.

Error codes

For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md).

ID Error Message
3301000 Location service is unavailable.

Example

import geoLocationManager from '@ohos.geoLocationManager';
import BusinessError from "@ohos.base";
try {
    let isConfirmed = geoLocationManager.isLocationPrivacyConfirmed(1);
} catch (err) {
    console.error("errCode:" + (err as BusinessError.BusinessError).code + ",errMessage:" + (err as BusinessError.BusinessError).message);
}

geoLocationManager.setLocationPrivacyConfirmStatus

setLocationPrivacyConfirmStatus(type: LocationPrivacyType, isConfirmed: boolean): void;

Sets the user confirmation status for the privacy statement of the location service. This API can only be called by system applications.

System API: This is a system API.

Required permissions: ohos.permission.MANAGE_SECURE_SETTINGS

System capability: SystemCapability.Location.Location.Core

Parameters

Name Type Mandatory Description
type LocationPrivacyType Yes Privacy statement type, for example, privacy statement displayed in the startup wizard or privacy statement displayed when the location service is enabled.
isConfirmed boolean Yes Whether the user agrees with the privacy statement.

Error codes

For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md).

ID Error Message
3301000 Location service is unavailable.

Example

import geoLocationManager from '@ohos.geoLocationManager';
import BusinessError from "@ohos.base";
try {
    geoLocationManager.setLocationPrivacyConfirmStatus(1, true);
} catch (err) {
    console.error("errCode:" + (err as BusinessError.BusinessError).code + ",errMessage:" + (err as BusinessError.BusinessError).message);
}

geoLocationManager.getLocatingRequiredData10+

getLocatingRequiredData(config: LocatingRequiredDataConfig): Promise<Array<LocatingRequiredData>>;

Obtains the required data of the location service. This API uses a promise to return the result.

Required permissions: ohos.permission.LOCATION and ohos.permission.APPROXIMATELY_LOCATION

System capability: SystemCapability.Location.Location.Core

System API: This is a system API.

Parameters

Name Type Mandatory Description
config LocatingRequiredDataConfig Yes Configuration for obtaining the required data of the location service.

Return value

Type Description
Promise<Array<LocatingRequiredData>> Promise used to return the required data for the location service, such as the Wi-Fi and Bluetooth scanning information.

Error codes

For details about the error codes, see [Location Error Codes]](errorcode-geoLocationManager.md).

ID Error Message
3301800 Failed to start WiFi or Bluetooth scanning.

Example

import geoLocationManager from '@ohos.geoLocationManager';
import BusinessError from "@ohos.base";
let config:geoLocationManager.LocatingRequiredDataConfig = {'type': 1, 'needStartScan': true, 'scanInterval': 10000};
try {
    geoLocationManager.getLocatingRequiredData(config).then((result) => {
        console.log('getLocatingRequiredData return: ' + JSON.stringify(result));
    })  
    .catch((error:number) => {
        console.error('promise, getLocatingRequiredData: error=' + JSON.stringify(error));
    });
} catch (err) {
    console.error("errCode:" + (err as BusinessError.BusinessError).code + ",errMessage:" + (err as BusinessError.BusinessError).message);
}