diff --git a/en/application-dev/device/device-location-geocoding.md b/en/application-dev/device/device-location-geocoding.md index 8a6a9a6751f8446ef1a1d20502444ab2a3bcb984..c29b1a0ed206cde027d3002d8b110722a473bfda 100644 --- a/en/application-dev/device/device-location-geocoding.md +++ b/en/application-dev/device/device-location-geocoding.md @@ -10,17 +10,18 @@ The geographic description helps users understand a location easily by providing ## Available APIs -The following table describes APIs available for mutual conversion between coordinates and geographic description. For details, see [Geolocation Manager](../reference/apis/js-apis-geoLocationManager.md). +The following table describes APIs available for mutual conversion between coordinates and geographic description. For details, see [Geolocation Manager](../reference/apis/js-apis-geolocation.md). **Table1** APIs for geocoding and reverse geocoding | API | Description | | -------- | -------- | -| isGeocoderAvailable(): boolean; | Obtains the (reverse) geocoding service status.| -| getAddressesFromLocation(request: ReverseGeoCodeRequest, callback: AsyncCallback<Array<GeoAddress>>): void | Converts coordinates into geographic description through reverse geocoding. This API uses an asynchronous callback to return the result. | -| getAddressesFromLocation(request: ReverseGeoCodeRequest): Promise<Array<GeoAddress>> | Converts coordinates into geographic description through reverse geocoding. This API uses a promise to return the result. | -| getAddressesFromLocationName(request: GeoCodeRequest, callback: AsyncCallback<Array<GeoAddress>>): void | Converts geographic description into coordinates through geocoding. This API uses an asynchronous callback to return the result. | -| getAddressesFromLocationName(request: GeoCodeRequest): Promise<Array<GeoAddress>> | Converts geographic description into coordinates through geocoding. This API uses a promise to return the result. | +| isGeoServiceAvailable(callback: AsyncCallback<boolean>) : void | Checks whether the (reverse) geocoding service is available. This API uses an asynchronous callback to return the result.| +| isGeoServiceAvailable() : Promise<boolean> | Checks whether the (reverse) geocoding service is available. This API uses a promise to return the result.| +| getAddressesFromLocation(request: ReverseGeoCodeRequest, callback: AsyncCallback<Array<GeoAddress>>) : void | Converts coordinates into geographic description through reverse geocoding. This API uses an asynchronous callback to return the result. | +| getAddressesFromLocation(request: ReverseGeoCodeRequest) : Promise<Array<GeoAddress>> | Converts coordinates into geographic description through reverse geocoding. This API uses a promise to return the result. | +| getAddressesFromLocationName(request: GeoCodeRequest, callback: AsyncCallback<Array<GeoAddress>>) : void | Converts geographic description into coordinates through geocoding. This API uses an asynchronous callback to return the result. | +| getAddressesFromLocationName(request: GeoCodeRequest) : Promise<Array<GeoAddress>> | Converts geographic description into coordinates through geocoding. This API uses a promise to return the result. | ## How to Develop @@ -29,21 +30,22 @@ The following table describes APIs available for mutual conversion between coord > > The **GeoConvert** instance needs to access backend services to obtain information. Therefore, before performing the following steps, ensure that your device is connected to the network. -1. Import the **geoLocationManager** module by which you can implement all APIs related to the geocoding and reverse geocoding conversion capabilities. +1. Import the **geolocation** module by which you can implement all APIs related to the geocoding and reverse geocoding conversion capabilities. ```ts - import geoLocationManager from '@ohos.geoLocationManager'; + import geolocation from '@ohos.geolocation'; ``` 2. Query whether geocoder service is available. - Call **isGeoServiceAvailable** to query whether the geocoder service is available. If the service is available, continue with step 3. ```ts - import geoLocationManager from '@ohos.geoLocationManager'; - try { - var isAvailable = geoLocationManager.isGeocoderAvailable(); - } catch (err) { - console.error("errCode:" + err.code + ",errMessage:" + err.message); - } + geolocation.isGeoServiceAvailable((err, data) => { + if (err) { + console.log('isGeoServiceAvailable err: ' + JSON.stringify(err)); + } else { + console.log('isGeoServiceAvailable data: ' + JSON.stringify(data)); + } + }); ``` 3. Obtain the conversion result. @@ -51,7 +53,7 @@ The following table describes APIs available for mutual conversion between coord ```ts var reverseGeocodeRequest = {"latitude": 31.12, "longitude": 121.11, "maxItems": 1}; - geoLocationManager.getAddressesFromLocation(reverseGeocodeRequest, (err, data) => { + geolocation.getAddressesFromLocation(reverseGeocodeRequest, (err, data) => { if (err) { console.log('getAddressesFromLocation err: ' + JSON.stringify(err)); } else { @@ -60,12 +62,12 @@ The following table describes APIs available for mutual conversion between coord }); ``` - Your application can obtain the **GeoAddress** list that matches the specified coordinates and then read location information from it. For details, see [Geolocation](../reference/apis/js-apis-geoLocationManager.md). + Your application can obtain the **GeoAddress** list that matches the specified coordinates and then read location information from it. For details, see [Geolocation](../reference/apis/js-apis-geolocation.md). - Call **getAddressesFromLocationName** to convert geographic description into coordinates. ```ts var geocodeRequest = {"description": "No. xx, xx Road, Pudong District, Shanghai", "maxItems": 1}; - geoLocationManager.getAddressesFromLocationName(geocodeRequest, (err, data) => { + geolocation.getAddressesFromLocationName(geocodeRequest, (err, data) => { if (err) { console.log('getAddressesFromLocationName err: ' + JSON.stringify(err)); } else { @@ -74,6 +76,6 @@ The following table describes APIs available for mutual conversion between coord }); ``` - Your application can obtain the **GeoAddress** list that matches the specified location information and read coordinates from it. For details, see [Geolocation](../reference/apis/js-apis-geoLocationManager.md). + Your application can obtain the **GeoAddress** list that matches the specified location information and read coordinates from it. For details, see [Geolocation](../reference/apis/js-apis-geolocation.md). To improve the accuracy of location results, you can set the longitude and latitude ranges in **GeoCodeRequest**. diff --git a/en/application-dev/device/device-location-info.md b/en/application-dev/device/device-location-info.md index edd1bb6093f40d6033adbb2e11cbe88ff984551d..235ef590861ceb1a8b2f9b878954ea3d3cecccc9 100644 --- a/en/application-dev/device/device-location-info.md +++ b/en/application-dev/device/device-location-info.md @@ -10,11 +10,11 @@ Real-time location of the device is recommended for location-sensitive services. ## Available APIs -For details about the APIs used to obtain the device location information, see [Geolocation Manager](../reference/apis/js-apis-geoLocationManager.md). +For details about the APIs used to obtain the device location information, see [Geolocation Manager](../reference/apis/js-apis-geolocation.md). ## How to Develop -To learn more about the APIs for obtaining device location information, see [Geolocation](../reference/apis/js-apis-geoLocationManager.md). +To learn more about the APIs for obtaining device location information, see [Geolocation](../reference/apis/js-apis-geolocation.md). 1. Before using basic location capabilities, check whether your application has been granted the permission to access the device location information. If not, your application needs to obtain the permission from the user as described below. The system provides the following location permissions: @@ -41,10 +41,10 @@ To learn more about the APIs for obtaining device location information, see [Geo You can declare the required permission in your application's configuration file. For details, see [Access Control (Permission) Development](../security/accesstoken-guidelines.md). -2. Import the **geoLocationManager** module by which you can implement all APIs related to the basic location capabilities. +2. Import the **geolocation** module by which you can implement all APIs related to the basic location capabilities. - ```ts - import geoLocationManager from '@ohos.geoLocationManager'; + ``` + import geolocation from '@ohos.geolocation'; ``` 3. Instantiate the **LocationRequest** object. This object provides APIs to notify the system of the location service type and the interval of reporting location information.
@@ -53,7 +53,7 @@ To learn more about the APIs for obtaining device location information, see [Geo 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. - ```ts + ``` export enum LocationRequestScenario { UNSET = 0x300, NAVIGATION, @@ -78,7 +78,7 @@ To learn more about the APIs for obtaining device location information, see [Geo Sample code for initializing **requestInfo** for navigation: ```ts - var requestInfo = {'scenario': geoLocationManager.LocationRequestScenario.NAVIGATION, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0}; + var requestInfo = {'scenario': geolocation.LocationRequestScenario.NAVIGATION, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0}; ``` **Method 2:** @@ -107,7 +107,7 @@ To learn more about the APIs for obtaining device location information, see [Geo Sample code for initializing **requestInfo** for the location accuracy priority policy: ```ts - var requestInfo = {'priority': geoLocationManager.LocationRequestPriority.ACCURACY, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0}; + var requestInfo = {'priority': geolocation.LocationRequestPriority.ACCURACY, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0}; ``` 4. Instantiate the **Callback** object for the system to report location results. @@ -122,24 +122,25 @@ To learn more about the APIs for obtaining device location information, see [Geo 5. Start device location. ```ts - geoLocationManager.on('locationChange', requestInfo, locationChange); + geolocation.on('locationChange', requestInfo, locationChange); ``` 6. (Optional) Stop device location. ```ts - geoLocationManager.off('locationChange', locationChange); + geolocation.off('locationChange', locationChange); ``` If your application does not need the real-time device location, it can use the last known device location cached in the system instead. ```ts - import geoLocationManager from '@ohos.geoLocationManager'; - try { - var location = geoLocationManager.getLastLocation(); - } catch (err) { - console.error("errCode:" + err.code + ",errMessage:" + err.message); - } + geolocation.getLastLocation((err, data) => { + if (err) { + console.log('getLastLocation: err: ' + JSON.stringify(err)); + } else { + console.log('getLastLocation: data: ' + JSON.stringify(data)); + } + }); ``` To call this method, your application needs to request the **ohos.permission.LOCATION** permission from the user. diff --git a/en/application-dev/reference/apis/js-apis-geoLocationManager.md b/en/application-dev/reference/apis/js-apis-geoLocationManager.md index 9c09d174723ca769e8b712a2e874c9b3c6f4f3a8..5d22ce86255fa5bb680d4cf66c530a98fe4f215a 100644 --- a/en/application-dev/reference/apis/js-apis-geoLocationManager.md +++ b/en/application-dev/reference/apis/js-apis-geoLocationManager.md @@ -30,7 +30,7 @@ If your application needs to access the device location information, it must fir | 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| -If your application needs to access the device location information when running in the background, it must be configured to be able to run in the background and be granted the **ohos.permission.LOCATION_IN_BACKGROUND** permission. In this way, the system continues to report device location information after your application moves to the background. +If your application needs to access the device location information when running in the background, it must be configured to be able to run in the background and be granted the **ohos.permission.LOCATION\_IN\_BACKGROUND** permission. In this way, the system continues to report device location information after your application moves to the background. You can declare the required permission in your application's configuration file. For details, see [Access Control (Permission) Development](../../security/accesstoken-guidelines.md). @@ -1615,7 +1615,7 @@ Obtains the current country code. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | Promise<[CountryCode](#countrycode)> | [CountryCode](#countrycode) | NA | Promise used to return the country code.| + | Promise<[CountryCode](#countrycode)> | [CountryCode](#countrycode) | NA | Callback used to return the country code.| **Error codes** @@ -1815,7 +1815,7 @@ For details about the following error codes, see [Location Error Codes](../error 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. +Sets information of the mock reverse geocoding function, including the mapping between a location and geographic name. If the location is contained in the configurations during reverse geocoding query, the corresponding geographic name will be returned. **System capability**: SystemCapability.Location.Location.Core @@ -1825,7 +1825,7 @@ Sets information of the mock reverse geocoding function, including the mapping b | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | mockInfos | Array<[ReverseGeocodingMockInfo](#reversegeocodingmockinfo)> | Yes| Array of information of the mock reverse geocoding function, including a location and a geographical name.| + | mockInfos | Array<[ReverseGeocodingMockInfo](#reversegeocodingmockinfo)> | Yes| Array of information of the mock reverse geocoding function, including a location and a geographic name.| **Error codes** @@ -1874,7 +1874,7 @@ Checks whether a user agrees with the privacy statement of the location service. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | boolean | boolean | NA | Callback used to return the result, which indicates whether the user agrees with the privacy statement.| + | boolean | boolean | NA | Result indicating whether the user agrees with the privacy statement.| **Error codes** @@ -1913,7 +1913,7 @@ Sets the user confirmation status for the privacy statement of the location serv | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | 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.| - | isConfirmed | boolean | Yes| Callback used to return the result, which indicates whether the user agrees with the privacy statement.| + | isConfirmed | boolean | Yes| Whether the user agrees with the privacy statement.| **Error codes** @@ -1975,7 +1975,7 @@ Defines a reverse geocoding request. | -------- | -------- | -------- | -------- | -------- | | locale | string | Yes| Yes| Language used for the location description. **zh** indicates Chinese, and **en** indicates English.| | latitude | number | Yes| Yes| Latitude information. A positive value indicates north latitude, and a negative value indicates south latitude.| -| longitude | number | Yes| Yes| Longitude information. A positive value indicates east longitude , and a negative value indicates west longitude .| +| longitude | number | Yes| Yes| Longitude information. A positive value indicates east longitude, and a negative value indicates west longitude.| | maxItems | number | Yes| Yes| Maximum number of location records to be returned.| @@ -2005,7 +2005,7 @@ Defines a geographic location. | Name| Type| Readable|Writable| Description| | -------- | -------- | -------- | -------- | -------- | | latitude | number | Yes| No | Latitude information. A positive value indicates north latitude, and a negative value indicates south latitude.| -| longitude | number | Yes| No | Longitude information. A positive value indicates east longitude , and a negative value indicates west longitude .| +| longitude | number | Yes| No | Longitude information. A positive value indicates east longitude, and a negative value indicates west longitude.| | locale | string | Yes| No | Language used for the location description. **zh** indicates Chinese, and **en** indicates English.| | placeName | string | Yes| No | Landmark of the location.| | countryCode | string | Yes| No | Country code.| @@ -2022,7 +2022,7 @@ Defines a geographic location. | addressUrl | string | Yes| No| Website URL.| | descriptions | Array<string> | Yes| No| Additional descriptions.| | descriptionsSize | number | Yes| No| Total number of additional descriptions.| -| isFromMock | Boolean | Yes| No| Whether the geographical name is from the mock reverse geocoding function.| +| isFromMock | Boolean | Yes| No| Whether the geographic name is from the mock reverse geocoding function.| ## LocationRequest @@ -2142,7 +2142,7 @@ Defines a location. | Name| Type| Readable|Writable| Description| | -------- | -------- | -------- | -------- | -------- | | latitude | number| Yes| No| Latitude information. A positive value indicates north latitude, and a negative value indicates south latitude.| -| longitude | number| Yes| No| Longitude information. A positive value indicates east longitude , and a negative value indicates west longitude .| +| longitude | number| Yes| No| Longitude information. A positive value indicates east longitude, and a negative value indicates west longitude.| | altitude | number | Yes| No| Location altitude, in meters.| | accuracy | number | Yes| No| Location accuracy, in meters.| | speed | number | Yes| No|Speed, in m/s.| @@ -2165,7 +2165,7 @@ Represents information of the mock reverse geocoding function. | Name| Type| Readable|Writable| Description| | -------- | -------- | -------- | -------- | -------- | | location | [ReverseGeoCodeRequest](#reversegeocoderequest) | Yes| Yes| Latitude and longitude information.| -| geoAddress | [GeoAddress](#geoaddress) | Yes| Yes|Geographical name.| +| geoAddress | [GeoAddress](#geoaddress) | Yes| Yes|Geographic name.| ## LocationMockConfig diff --git a/en/application-dev/reference/apis/js-apis-geolocation.md b/en/application-dev/reference/apis/js-apis-geolocation.md index 8bc027058b6d9bbda89636757219f83827029317..a5c7034c0333cb640dbe1a51b7f5f6e6f63743ca 100644 --- a/en/application-dev/reference/apis/js-apis-geolocation.md +++ b/en/application-dev/reference/apis/js-apis-geolocation.md @@ -19,9 +19,9 @@ The system provides the following location permissions: 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 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 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| | -------- | -------- | -------- | -------- | @@ -30,7 +30,7 @@ API version 9 and later: Apply for **ohos.permission.APPROXIMATELY\_LOCATION**, | 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| -If your application needs to access the device location information when running in the background, it must be configured to be able to run in the background and be granted the **ohos.permission.LOCATION_IN_BACKGROUND** permission. In this way, the system continues to report device location information after your application moves to the background. +If your application needs to access the device location information when running in the background, it must be configured to be able to run in the background and be granted the **ohos.permission.LOCATION\_IN\_BACKGROUND** permission. In this way, the system continues to report device location information after your application moves to the background. You can declare the required permission in your application's configuration file. For details, see [Access Control (Permission) Development](../../security/accesstoken-guidelines.md). @@ -971,7 +971,7 @@ Converts geographic description into coordinates through geocoding. This API use | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | Promise<Array<[GeoAddress](#geoaddress)>> | Array<[GeoAddress](#geoaddress)>|NA|Callback used to return the geocoding result.| + | Promise<Array<[GeoAddress](#geoaddress)>> | Array<[GeoAddress](#geoaddress)>|NA|Promise used to return the geocoding result.| **Example** @@ -1265,7 +1265,7 @@ Defines a reverse geocoding request. | -------- | -------- | -------- | -------- | -------- | | locale | string | Yes| Yes| Language used for the location description. **zh** indicates Chinese, and **en** indicates English.| | latitude | number | Yes| Yes| Latitude information. A positive value indicates north latitude, and a negative value indicates south latitude.| -| longitude | number | Yes| Yes| Longitude information. A positive value indicates east longitude , and a negative value indicates west longitude .| +| longitude | number | Yes| Yes| Longitude information. A positive value indicates east longitude, and a negative value indicates west longitude.| | maxItems | number | Yes| Yes| Maximum number of location records to be returned.| @@ -1305,7 +1305,7 @@ Defines a geographic location. | Name| Type| Readable|Writable| Description| | -------- | -------- | -------- | -------- | -------- | | latitude7+ | number | Yes| No| Latitude information. A positive value indicates north latitude, and a negative value indicates south latitude.| -| longitude7+ | number | Yes| No| Longitude information. A positive value indicates east longitude , and a negative value indicates west longitude .| +| longitude7+ | number | Yes| No| Longitude information. A positive value indicates east longitude, and a negative value indicates west longitude.| | locale7+ | string | Yes| No| Language used for the location description. **zh** indicates Chinese, and **en** indicates English.| | placeName7+ | string | Yes| No| Landmark of the location.| | countryCode7+ | string | Yes| No| Country code.| @@ -1493,7 +1493,7 @@ Defines a location. | Name| Type| Readable|Writable| Description| | -------- | -------- | -------- | -------- | -------- | | latitude7+ | number | Yes| No| Latitude information. A positive value indicates north latitude, and a negative value indicates south latitude.| -| longitude7+ | number | Yes| No| Longitude information. A positive value indicates east longitude , and a negative value indicates west longitude .| +| longitude7+ | number | Yes| No| Longitude information. A positive value indicates east longitude, and a negative value indicates west longitude.| | altitude7+ | number | Yes| No| Location altitude, in meters.| | accuracy7+ | number | Yes| No| Location accuracy, in meters.| | speed7+ | number | Yes| No| Speed, in m/s.| diff --git a/en/application-dev/reference/apis/js-apis-system-location.md b/en/application-dev/reference/apis/js-apis-system-location.md index 80101da6c810604815880a98aab09588af833918..fd4fba8512b1cdecae82339ef31a4b293f022aef 100644 --- a/en/application-dev/reference/apis/js-apis-system-location.md +++ b/en/application-dev/reference/apis/js-apis-system-location.md @@ -1,8 +1,8 @@ # Geographic Location > **NOTE** +> - The APIs of this module are no longer maintained since API version 7. You are advised to use [`@ohos.geolocation`](js-apis-geolocation.md). > - The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version. -> - The APIs provided by this module are no longer maintained since API version 9. You are advised to use [geoLocationManager](js-apis-geoLocationManager.md) instead. ## Modules to Import @@ -18,15 +18,12 @@ import geolocation from '@system.geolocation'; ohos.permission.LOCATION -## geolocation.getLocation(deprecated) +## geolocation.getLocation getLocation(Object): void Obtains the geographic location. -> **NOTE** -> This API is deprecated since API version 9. You are advised to use [geoLocationManager.getCurrentLocation](js-apis-geoLocationManager.md#geolocationmanagergetcurrentlocation). - **System capability**: SystemCapability.Location.Location.Lite **Parameters** @@ -77,15 +74,12 @@ export default { ``` -## geolocation.getLocationType(deprecated) +## geolocation.getLocationType getLocationType(Object): void Obtains the supported location types. -> **NOTE** -> This API is deprecated since API version 9. - **System capability**: SystemCapability.Location.Location.Lite **Parameters** @@ -120,15 +114,12 @@ export default { ``` -## geolocation.subscribe(deprecated) +## geolocation.subscribe subscribe(Object): void Listens to the geographical location. If this method is called multiple times, the last call takes effect. -> **NOTE** -> This API is deprecated since API version 9. You are advised to use [geoLocationManager.on('locationChange')](js-apis-geoLocationManager.md#geolocationmanageronlocationchange). - **System capability**: SystemCapability.Location.Location.Lite **Parameters** @@ -175,15 +166,12 @@ export default { ``` -## geolocation.unsubscribe(deprecated) +## geolocation.unsubscribe unsubscribe(): void Cancels listening to the geographical location. -> **NOTE** -> This API is deprecated since API version 9. You are advised to use [geoLocationManager.off('locationChange')](js-apis-geoLocationManager.md#geolocationmanagerofflocationchange). - **System capability**: SystemCapability.Location.Location.Lite **Example** @@ -197,15 +185,12 @@ export default { ``` -## geolocation.getSupportedCoordTypes(deprecated) +## geolocation.getSupportedCoordTypes getSupportedCoordTypes(): Array<string> Obtains coordinate system types supported by the device. -> **NOTE** -> This API is deprecated since API version 9. - **System capability**: SystemCapability.Location.Location.Lite **Return Value**