目录

site (Place Search)

This module provides the place search service.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

Start version: 4.1.0(11)

Module Import

import { site } from '@kit.MapKit';

This module provides the methods described in the following table to implement the function of place search.

Name

Description

searchByText(searchByTextParams: SearchByTextParams)

Performs keyword search.

searchByText(context: common.Context, searchByTextParams: SearchByTextParams)

Performs keyword search. The context can be passed.

nearbySearch(nearbySearchParams: NearbySearchParams)

Performs nearby place search.

nearbySearch(context: common.Context, nearbySearchParams: NearbySearchParams)

Performs nearby place search. The context can be passed.

queryAutoComplete(queryAutoCompleteParams: QueryAutoCompleteParams)

Performs autocomplete.

queryAutoComplete(context: common.Context, queryAutoCompleteParams: QueryAutoCompleteParams)

Performs autocomplete. The context can be passed.

searchById(searchByIdParams: SearchByIdParams)

Searches for place details.

searchById(context: common.Context, searchByIdParams: SearchByIdParams)

Searches for place details. The context can be passed.

geocode(geocodeParams: GeocodeParams)

Performs forward geocoding.

geocode(context: common.Context, geocodeParams: GeocodeParams)

Performs forward geocoding. The context can be passed.

reverseGeocode(reverseGeocodeParams: ReverseGeocodeParams)

Performs reverse geocoding.

reverseGeocode(context: common.Context, reverseGeocodeParams: ReverseGeocodeParams)

Performs reverse geocoding. The context can be passed.

This module provides the APIs described in the following table to implement the function of place search.

Name

Type

Description

SearchByTextParams

SearchByTextParams

Defines parameters for keyword search.

NearbySearchParams

NearbySearchParams

Defines parameters for nearby place search.

QueryAutoCompleteParams

QueryAutoCompleteParams

Defines parameters for autocomplete.

SearchByIdParams

SearchByIdParams

Defines parameters for place details search.

ReverseGeocodeParams

ReverseGeocodeParams

Defines parameters for reverse geocoding.

GeocodeParams

GeocodeParams

Defines parameters for forward geocoding.

SearchByTextResult

SearchByTextResult

Defines the keyword search result.

NearbySearchResult

NearbySearchResult

Defines the nearby place search result.

QueryAutoCompleteResult

QueryAutoCompleteResult

Defines the autocomplete result.

SearchByIdResult

SearchByIdResult

Defines the place details search result.

ReverseGeocodeResult

ReverseGeocodeResult

Defines the reverse geocoding result.

GeocodeResult

GeocodeResult

Defines the forward geocoding result.

Site

Site

Defines location information.

AddressComponent

AddressComponent

Defines address details.

City

City

Defines city information.

StreetNumber

StreetNumber

Defines a street number.

Poi

Poi

Defines POI information.

OpeningHours

OpeningHours

Defines the business hours.

Period

Period

Defines the business cycle.

TimeOfWeek

TimeOfWeek

Defines the business hour model.

ChildNode

ChildNode

Defines information about child nodes of a POI.

Comment

Comment

Defines comments on a POI.

Aoi

Aoi

Defines AOI information.

ReverseGeocodePoi

ReverseGeocodePoi

Defines the POI information of the reverse geocoding result.

Road

Road

Defines road information.

Intersection

Intersection

Defines crosspoint information.

searchByText

searchByText(searchByTextParams: SearchByTextParams): Promise<SearchByTextResult>

Searches for a place, such as a scenic spot, enterprise, or school, based on a user's input keyword and coordinate bounds. Coordinate bounds are optional. This API returns the result asynchronously through a promise.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Mandatory

Description

searchByTextParams

SearchByTextParams

Yes

Parameters for keyword search.

Returns:

Type

Description

Promise<SearchByTextResult>

SearchByTextResult object returned through a promise.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Invalid input parameter.

1002600001

System internal error.

1002600002

Failed to connect to the Map Kit server.

1002600003

App authentication failed.

1002600004

The Map permission is not enabled.

1002603001

Zero result.

Example:

let params: site.SearchByTextParams = {
  query: "Piazzale Dante, 41, 55049 Viareggio, Tuscany, Italy",
  location: {
    latitude: 31.984410259206815,
    longitude: 118.76625379397866
  },
  radius: 10000,
  language: "en"
};
const result = await site.searchByText(params);
console.info("Succeeded in searching by text.");

searchByText

searchByText(context: common.Context, searchByTextParams: SearchByTextParams): Promise<SearchByTextResult>

Searches for a place, such as a scenic spot, enterprise, or school, based on a user's input keyword and coordinate bounds. Coordinate bounds are optional. The context can be passed. This API returns the result asynchronously through a promise.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

System capability: SystemCapability.Map.Core

Start version: 5.0.0(12)

Parameters:

Name

Type

Mandatory

Description

context

common.Context

Yes

Context.

searchByTextParams

SearchByTextParams

Yes

Parameters for keyword search.

Returns:

Type

Description

Promise<SearchByTextResult>

SearchByTextResult object returned through a promise.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Invalid input parameter.

1002600001

System internal error.

1002600002

Failed to connect to the Map Kit server.

1002600003

App authentication failed.

1002600004

The Map permission is not enabled.

1002603001

Zero result.

Example:

let params: site.SearchByTextParams = {
  query: "Piazzale Dante, 41, 55049 Viareggio, Tuscany, Italy",
  location: {
    latitude: 31.984410259206815,
    longitude: 118.76625379397866
  },
  radius: 10000,
  language: "en"
};
const result = await site.searchByText(getContext(), params);
console.info("Succeeded in searching by text.");

nearbySearch

nearbySearch(nearbySearchParams: NearbySearchParams): Promise<NearbySearchResult>

Searches for nearby places based on the user device location. You can optimize the search result by providing keywords or specifying the type of the places to search. This API returns the result asynchronously through a promise.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Mandatory

Description

nearbySearchParams

NearbySearchParams

Yes

Parameters for nearby place search.

Returns:

Type

Description

Promise<NearbySearchResult>

NearbySearchResult object returned through a promise.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Invalid input parameter.

1002600001

System internal error.

1002600002

Failed to connect to the Map Kit server.

1002600003

App authentication failed.

1002600004

The Map permission is not enabled.

1002603001

Zero result.

Example:

let params: site.NearbySearchParams = {
  query: "stazione di pomezia",
  location: {
    latitude: 31.984410259206815,
    longitude: 118.76625379397866
  },
  radius: 5000,
  poiTypes: ["NATIONAL_RAILWAY_STATION"],
  language: "en",
  pageIndex: 1,
  pageSize: 1
};
const result = await site.nearbySearch(params);
console.info("Succeeded in searching nearby.");

nearbySearch

nearbySearch(context: common.Context,nearbySearchParams: NearbySearchParams): Promise<NearbySearchResult>

Searches for nearby places based on the user device location. The context can be passed. You can optimize the search result by providing keywords or specifying the type of the places to search. This API returns the result asynchronously through a promise.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

System capability: SystemCapability.Map.Core

Start version: 5.0.0(12)

Parameters:

Name

Type

Mandatory

Description

context

common.Context

Yes

Context.

nearbySearchParams

NearbySearchParams

Yes

Parameters for nearby place search.

Returns:

Type

Description

Promise<NearbySearchResult>

NearbySearchResult object returned through a promise.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Invalid input parameter.

1002600001

System internal error.

1002600002

Failed to connect to the Map Kit server.

1002600003

App authentication failed.

1002600004

The Map permission is not enabled.

1002603001

Zero result.

Example:

let params: site.NearbySearchParams = {
  query: "stazione di pomezia",
  location: {
    latitude: 31.984410259206815,
    longitude: 118.76625379397866
  },
  radius: 5000,
  poiTypes: ["NATIONAL_RAILWAY_STATION"],
  language: "en",
  pageIndex: 1,
  pageSize: 1
};
const result = await site.nearbySearch(getContext(), params);
console.info("Succeeded in searching nearby.");

queryAutoComplete

queryAutoComplete(queryAutoCompleteParams: QueryAutoCompleteParams): Promise<QueryAutoCompleteResult>

Returns an autocomplete place and a list of suggested places based on the input keyword. This API returns the result asynchronously through a promise.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Mandatory

Description

queryAutoCompleteParams

QueryAutoCompleteParams

Yes

Parameters for autocomplete.

Returns:

Type

Description

Promise<QueryAutoCompleteResult>

QueryAutoCompleteResult object returned through a promise.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Invalid input parameter.

1002600001

System internal error.

1002600002

Failed to connect to the Map Kit server.

1002600003

App authentication failed.

1002600004

The Map permission is not enabled.

1002603001

Zero result.

Example:

let params: site.QueryAutoCompleteParams = {
  query: "hotel",
  location: {
    latitude: 31.984410259206815,
    longitude: 118.76625379397866
  },
  language: "en",
  isChildren: true
};
const result = await site.queryAutoComplete(params);
console.info("Succeeded in querying.");

queryAutoComplete

queryAutoComplete(context: common.Context, queryAutoCompleteParams: QueryAutoCompleteParams): Promise<QueryAutoCompleteResult>

Returns an autocomplete place and a list of suggested places based on the input keyword. The context can be passed. If an invalid value is passed, this API will not respond. This API returns the result asynchronously through a promise.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

System capability: SystemCapability.Map.Core

Start version: 5.0.0(12)

Parameters:

Name

Type

Mandatory

Description

context

common.Context

Yes

Context.

queryAutoCompleteParams

QueryAutoCompleteParams

Yes

Parameters for autocomplete.

Returns:

Type

Description

Promise<QueryAutoCompleteResult>

QueryAutoCompleteResult object returned through a promise.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Invalid input parameter.

1002600001

System internal error.

1002600002

Failed to connect to the Map Kit server.

1002600003

App authentication failed.

1002600004

The Map permission is not enabled.

1002603001

Zero result.

Example:

let params: site.QueryAutoCompleteParams = {
  query: "hotel",
  location: {
    latitude: 31.984410259206815,
    longitude: 118.76625379397866
  },
  language: "en",
  isChildren: true
};
const result = await site.queryAutoComplete(getContext(), params);
console.info("Succeeded in querying.");

searchById

searchById(searchByIdParams: SearchByIdParams): Promise<SearchByIdResult>

Obtains details about a place based on its unique ID which serves as the primary key. The details include the name, address, and longitude and latitude of the place. This API returns the result asynchronously through a promise.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Mandatory

Description

searchByIdParams

SearchByIdParams

Yes

Parameters for place details search.

Returns:

Type

Description

Promise<SearchByIdResult>

SearchByIdResult object returned through a promise.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Invalid input parameter.

1002600001

System internal error.

1002600002

Failed to connect to the Map Kit server.

1002600003

App authentication failed.

1002600004

The Map permission is not enabled.

1002603001

Zero result.

Example:

let params: site.SearchByIdParams = {
  siteId: "144129739873977856",
  language: "en",
  isChildren: true
};
const result = await site.searchById(params);
console.info("Succeeded in searching by id.");

searchById

searchById(context: common.Context, searchByIdParams: SearchByIdParams): Promise<SearchByIdResult>

Obtains details about a place based on its unique ID which serves as the primary key. The details include the name, address, and longitude and latitude of the place. This API returns the result asynchronously through a promise.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

System capability: SystemCapability.Map.Core

Start version: 5.0.0(12)

Parameters:

Name

Type

Mandatory

Description

context

common.Context

Yes

Context.

searchByIdParams

SearchByIdParams

Yes

Parameters for place details search.

Returns:

Type

Description

Promise<SearchByIdResult>

SearchByIdResult object returned through a promise.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Invalid input parameter.

1002600001

System internal error.

1002600002

Failed to connect to the Map Kit server.

1002600003

App authentication failed.

1002600004

The Map permission is not enabled.

1002603001

Zero result.

Example:

let params: site.SearchByIdParams = {
  siteId: "144129739873977856",
  language: "en",
  isChildren: true
};
const result = await site.searchById(getContext(), params);
console.info("Succeeded in searching by id.");

geocode

geocode(geocodeParams: GeocodeParams): Promise<GeocodeResult>

Obtains the longitude and latitude of a place based on its structured address. This API returns the result asynchronously through a promise.

This API obtains spatial coordinates (such as the longitude and latitude) of a place based on its address. A maximum of 10 records can be returned.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Mandatory

Description

geocodeParams

GeocodeParams

Yes

Parameters for forward geocoding.

Returns:

Type

Description

Promise<GeocodeResult>

GeocodeResult object returned through a promise.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Invalid input parameter.

1002600001

System internal error.

1002600002

Failed to connect to the Map Kit server.

1002600003

App authentication failed.

1002600004

The Map permission is not enabled.

1002603001

Zero result.

Example:

let params: site.GeocodeParams = {
  "query": "Piazzale Dante, 41, 55049 Viareggio",
  "language": "en"
};
const result = await site.geocode(params);
console.info("Succeeded in geocoding.");

geocode

geocode(context: common.Context, geocodeParams: GeocodeParams): Promise<GeocodeResult>

Obtains the longitude and latitude of a place based on its structured address. The context can be passed. This API returns the result asynchronously through a promise.

This API obtains spatial coordinates (such as the longitude and latitude) of a place based on its address. A maximum of 10 records can be returned.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

System capability: SystemCapability.Map.Core

Start version: 5.0.0(12)

Parameters:

Name

Type

Mandatory

Description

context

common.Context

Yes

Context.

geocodeParams

GeocodeParams

Yes

Parameters for forward geocoding.

Returns:

Type

Description

Promise<GeocodeResult>

GeocodeResult object returned through a promise.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Invalid input parameter.

1002600001

System internal error.

1002600002

Failed to connect to the Map Kit server.

1002600003

App authentication failed.

1002600004

The Map permission is not enabled.

1002603001

Zero result.

Example:

let params: site.GeocodeParams = {
  "query": "Piazzale Dante, 41, 55049 Viareggio",
  "language": "en"
};
const result = await site.geocode(getContext(), params);
console.info("Succeeded in geocoding.");

reverseGeocode

reverseGeocode(reverseGeocodeParams: ReverseGeocodeParams): Promise<ReverseGeocodeResult>

Obtains location information about a place based on its longitude and latitude. This API returns the result asynchronously through a promise.

This API obtains the detailed addresses of places within 200 meters around the device location based on the place's longitude and latitude. A maximum of 11 records can be returned.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Mandatory

Description

reverseGeocodeParams

ReverseGeocodeParams

Yes

Parameters for reverse geocoding.

Returns:

Type

Description

Promise<ReverseGeocodeResult>

ReverseGeocodeResult object returned through a promise.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Invalid input parameter.

1002600001

System internal error.

1002600002

Failed to connect to the Map Kit server.

1002600003

App authentication failed.

1002600004

The Map permission is not enabled.

1002603001

Zero result.

Example:

let params: site.ReverseGeocodeParams = {
  location: {
    latitude: 31.984410259206815,
    longitude: 118.76625379397866
  },
  language: "en",
  radius: 200
};
const result = await site.reverseGeocode(params);
console.info("Succeeded in reversing geocode.");

reverseGeocode

reverseGeocode(context: common.Context, reverseGeocodeParams: ReverseGeocodeParams): Promise<ReverseGeocodeResult>

Obtains location information about a place based on its longitude and latitude. The context can be passed. This API returns the result asynchronously through a promise.

This API obtains the detailed addresses of places within 200 meters around the device location based on the place's longitude and latitude. A maximum of 11 records can be returned.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

System capability: SystemCapability.Map.Core

Start version: 5.0.0(12)

Parameters:

Name

Type

Mandatory

Description

context

common.Context

Yes

Context.

reverseGeocodeParams

ReverseGeocodeParams

Yes

Parameters for reverse geocoding.

Returns:

Type

Description

Promise<ReverseGeocodeResult>

ReverseGeocodeResult object returned through a promise.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Invalid input parameter.

1002600001

System internal error.

1002600002

Failed to connect to the Map Kit server.

1002600003

App authentication failed.

1002600004

The Map permission is not enabled.

1002603001

Zero result.

Example:

let params: site.ReverseGeocodeParams = {
  location: {
    latitude: 31.984410259206815,
    longitude: 118.76625379397866
  },
  language: "en",
  radius: 200
};
const result = await site.reverseGeocode(getContext(), params);
console.info("Succeeded in reversing geocode.");

SortRule

Defines the result sorting rule.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

System capability: SystemCapability.Map.Core

Start version: 5.0.0(12)

Name

Value

Description

COMPOSITE

0

Comprehensive sorting, which is the default sorting rule.

DISTANCE

1

Sorting by distance.

SearchByTextParams

Defines parameters for keyword search.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

query

string

No

No

Search keyword. The length of the parameter value ranges from 1 to 512.

location

mapCommon.LatLng

No

Yes

Longitude and latitude to which search suggestions need to be biased.

radius

number

No

Yes

Search radius, in meters. The value ranges from 1 to 50000. The default value is 50000.

poiTypes

Array<string>

No

Yes

Huawei POI type of a place to search. The value range is the same as that of HwLocationType.

A maximum of five types can be passed. The default value is null.

countryCodes

Array<string>

No

Yes

Country/Region code, which complies with ISO 3166-1 alpha-2. This parameter is used to specify the country/region where places are searched.

A maximum of five country/region codes can be passed.

cityId

string

No

Yes

City ID. This parameter is used to specify the city where places are searched. The length of the parameter value ranges from 1 to 32.

NOTE:
  • Chinese names of Hong Kong (China), and Macao (China), and cities in the Chinese mainland are supported.
  • For Hong Kong, Macao, and cities in the Chinese mainland, the value can be the city code with 3-4 digits or the administrative division code with 6 digits. For details, please refer to City Codes and Administrative Division Codes.
  • The value can also be a city ID with 16-18 digits.

isCityLimit

boolean

No

Yes

Indicates whether the search result must be in the specified city. This parameter needs to be used with cityId. The default value is false.

  • true: yes
  • false: no

language

string

No

Yes

Input language. The length of the parameter value ranges from 1 to 16. For details about the language values, please refer to Supported Languages.

If this parameter is not set, the local language will be used.

pageSize

number

No

Yes

Number of records on each page. The value ranges from 1 to 20. The default value is 20.

pageIndex

number

No

Yes

Number of the current page. The value ranges from 1 to 500. The default value is 1.

NOTE:

pageIndex * pageSize <= 500

isChildren

boolean

No

Yes

Indicates whether to return information about child nodes. The default value is false.

  • true: yes (Full information about child nodes will be returned.)
  • false: no

NearbySearchParams

Defines parameters for nearby place search.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

location

mapCommon.LatLng

No

No

Current location of a user.

radius

number

No

Yes

Radius of a circle area where places are searched, in meters. The value ranges from 1 to 50000. The default value is 1000.

query

string

No

Yes

Search keyword. The length of the parameter value ranges from 1 to 512.

poiTypes

Array<string>

No

Yes

Huawei POI type of a place to search. The value range is the same as that of HwLocationType.

A maximum of five types can be passed.

language

string

No

Yes

Input language. The length of the parameter value ranges from 1 to 16. For details about the language values, please refer to Supported Languages.

If this parameter is not set, the local language will be used.

pageSize

number

No

Yes

Number of records on each page. The value ranges from 1 to 20. The default value is 20.

pageIndex

number

No

Yes

Number of the current page. The value ranges from 1 to 500. The default value is 1.

NOTE:

pageIndex * pageSize <= 500

sortRule

SortRule

No

Yes

Sorting rule. The default value is SortRule.COMPOSITE.

Start version: 5.0.0(12)

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

QueryAutoCompleteParams

Defines parameters for autocomplete.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

query

string

No

No

Search keyword. The length of the parameter value ranges from 1 to 512.

location

mapCommon.LatLng

No

Yes

Longitude and latitude to which search suggestions need to be biased.

radius

number

No

Yes

Search radius, in meters. The value ranges from 1 to 50000. The default value is 50000.

poiTypes

Array<string>

No

Yes

Huawei POI type of a place to search. The value range is the same as that of HwLocationType.

A maximum of five types can be passed.

cityId

string

No

Yes

City ID. This parameter is used to specify the city where places are searched. The length of the parameter value ranges from 1 to 32.

NOTE:
  • Chinese names of Hong Kong (China), and Macao (China), and cities in the Chinese mainland are supported.
  • For Hong Kong, Macao, and cities in the Chinese mainland, the value can be the city code with 3-4 digits or the administrative division code with 6 digits. For details, please refer to City Codes and Administrative Division Codes.
  • The value can also be a city ID with 16-18 digits.

isCityLimit

boolean

No

Yes

Indicates whether the search result must be in the specified city. This parameter needs to be used with cityId. The default value is false.

  • true: yes
  • false: no

language

string

No

Yes

Input language. The length of the parameter value ranges from 1 to 16. For details about the language values, please refer to Supported Languages.

If this parameter is not set, the local language will be used.

isChildren

boolean

No

Yes

Indicates whether to return information about child nodes. The default value is false.

  • true: yes (Full information about child nodes will be returned.)
  • false: no

SearchByIdParams

Defines parameters for place details search.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

siteId

string

No

No

Address ID. The length of the parameter value ranges from 1 to 256.

language

string

No

Yes

Input language. The length of the parameter value ranges from 1 to 16. For details about the language values, please refer to Supported Languages.

If this parameter is not set, the local language will be used.

isChildren

boolean

No

Yes

Indicates whether to return information about child nodes. The default value is false.

  • true: yes (Full information about child nodes will be returned.)
  • false: no

ReverseGeocodeParams

Defines parameters for reverse geocoding.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

location

mapCommon.LatLng

No

No

Longitude and latitude for reverse geocoding.

language

string

No

Yes

Input language. The length of the parameter value ranges from 1 to 16. For details about the language values, please refer to Supported Languages.

If this parameter is not set, the local language will be used.

radius

number

No

Yes

Search radius, in meters. The value ranges from 0 to 1000. The default value is 1000.

isExtension

boolean

No

Yes

Indicates whether to return information such as POIs, AOIs, roads, and crosspoints. The default value is false.

  • true: yes
  • false: no

poiTypes

Array<string>

No

Yes

Huawei POI type of a place to search. The value range is the same as that of HwLocationType.

A maximum of five types can be passed.

isNearbyAoi

boolean

No

Yes

Indicates whether to return nearby AOIs.

This parameter is valid only when isExtension is set to true.

The default value is false.

  • true: returns nearby AOIs.
  • false: returns only AOIs specified by the passed longitude and latitude.

Start version: 5.0.0(12)

NOTE:

This parameter can be used in atomic services since version 5.0.0(12).

sortRule

SortRule

No

Yes

POI sorting rule.

The default value is SortRule.DISTANCE, which indicates sorting by distance.

Start version: 5.0.0(12)

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

GeocodeParams

Defines parameters for forward geocoding.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

query

string

No

No

Address information. The length of the parameter value ranges from 1 to 512.

language

string

No

Yes

Input language. The length of the parameter value ranges from 1 to 16. For details about the language values, please refer to Supported Languages.

If this parameter is not set, the local language will be used.

bounds

mapCommon.LatLngBounds

No

Yes

Coordinate bounds to which search results need to be biased.

SearchByTextResult

Defines the keyword search result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

totalCount

number

No

No

Total number of records that meet the search criteria when the search is successful.

sites

Array<Site>

No

Yes

Search result returned upon a successful search.

NearbySearchResult

Defines the nearby place search result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

totalCount

number

No

No

Total number of records that meet the search criteria when the search is successful.

sites

Array<Site>

No

Yes

Search result returned upon a successful search.

QueryAutoCompleteResult

Defines the autocomplete result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

sites

Array<Site>

No

Yes

Suggested places returned upon a successful autocomplete.

SearchByIdResult

Defines the place details search result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

site

Site

No

Yes

Place details returned upon a successful search.

ReverseGeocodeResult

Defines the reverse geocoding result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

addressComponent

AddressComponent

No

No

Address details.

addressDescription

string

No

No

Unstructured address text.

aois

Array<Aoi>

No

Yes

AOI information.

pois

Array<ReverseGeocodePoi>

No

Yes

POI information.

roads

Array<Road>

No

Yes

Road information.

intersections

Array<Intersection>

No

Yes

Crosspoint information.

GeocodeResult

Defines the forward geocoding result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

sites

Array<Site>

No

Yes

Search result returned upon a successful search.

Site

Defines place details.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

siteId

string

No

No

Unique ID of a place.

name

string

No

Yes

Name of a place.

formatAddress

string

No

Yes

Formatted detailed address of a place.

addressComponent

AddressComponent

No

No

Address details.

location

mapCommon.LatLng

No

Yes

Longitude and latitude of a place.

viewport

mapCommon.LatLngBounds

No

Yes

Viewport of a place.

NOTE:

This parameter is not supported for the autocomplete function.

distance

number

No

Yes

Linear distance between a place and the location specified by the input parameter location, in meters.

NOTE:

Currently, this parameter is supported only for keyword search and nearby place search.

poi

Poi

No

Yes

POI information about a place if the place is a POI.

utcOffset

number

No

Yes

Difference between the time zone of a place and the UTC time zone, in minutes.

NOTE:

This parameter is not supported for the autocomplete function.

AddressComponent

Defines address details.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

countryCode

string

No

Yes

Country/Region code.

countryName

string

No

Yes

Country name.

adminLevel1

string

No

Yes

Level-1 administrative division.

adminLevel2

string

No

Yes

Level-2 administrative division.

adminLevel3

string

No

Yes

Level-3 administrative division.

adminLevel4

string

No

Yes

Level-4 administrative division.

adminLevel5

string

No

Yes

Level-5 administrative division.

locality

string

No

Yes

locality.

subLocality1

string

No

Yes

Level-1 locality.

subLocality2

string

No

Yes

Level-2 locality.

neighborhoods

Array<string>

No

Yes

Neighborhood.

adminCode

string

No

Yes

Administrative division code.

NOTE:

The administrative division codes returned by the API cover all provinces, cities, districts/counties, and towns/streets in the Chinese mainland, Hong Kong (China), and Macao (China). The appendix provides only a sample of city administrative division codes.

postalCode

string

No

Yes

Postal code.

city

City

No

Yes

City information.

streetNumber

StreetNumber

No

Yes

Street number.

City

Defines city information.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

cityCode

string

No

Yes

City code.

cityId

string

No

Yes

City ID.

cityName

string

No

Yes

City name.

StreetNumber

Defines a street number.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

direction

string

No

Yes

Direction of an input point along a street.

distance

number

No

Yes

Linear distance between a place and the location specified by the input parameter location, in meters.

location

mapCommon.LatLng

No

Yes

Longitude and latitude of a street.

streetNumber

string

No

Yes

Street number.

streetName

string

No

Yes

Street name.

formatAddress

string

No

Yes

Formatted street address.

Poi

Defines POI information.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

poiTypes

Array<string>

No

Yes

Huawei POI type. The value range is the same as that of HwLocationType.

poiTypeIds

Array<string>

No

Yes

Huawei POI type ID.

phone

string

No

Yes

Phone number.

internationalPhone

string

No

Yes

International phone number.

rating

number

No

Yes

Rating.

websiteUrl

string

No

Yes

Website URL.

openingHours

OpeningHours

No

Yes

Business hours.

businessStatus

string

No

Yes

Business status.

  • OPEN_NOW: open
  • CLOSE_NOW: closed
  • CLOSED_TEMPORARILY: temporarily closed
  • CLOSED_PERMANENTLY: permanently closed
  • STATUS_UNKNOWN: unknown
NOTE:

This parameter is returned only by the place details search API.

brand

string

No

Yes

Brand name.

email

string

No

Yes

Email address.

starRating

number

No

Yes

Star rating.

childNodes

Array<ChildNode>

No

Yes

Child nodes of a POI.

icon

string

No

Yes

POI icon URL.

description

string

No

Yes

Description.

abstractText

string

No

Yes

Abstract information.

comment

Comment

No

Yes

Comment information about a POI.

OpeningHours

Defines the business hours.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

texts

Array<string>

No

Yes

Description of weekly opening hours of a place.

periods

Array<Period>

No

Yes

Opening hours of a place.

Period

Defines the opening hours of a place.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

open

TimeOfWeek

No

Yes

Open time.

close

TimeOfWeek

No

Yes

Close time.

TimeOfWeek

Defines the time model.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

week

number

No

Yes

0: Sunday

1: Monday

2: Tuesday

3: Wednesday

4: Thursday

5: Friday

6: Saturday

time

string

No

Yes

24-hour time in hhmm format.

ChildNode

Defines information about child nodes of a POI.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

siteId

string

No

Yes

Location ID.

name

string

No

Yes

Name of a place.

formatAddress

string

No

Yes

Formatted detailed address of a place.

location

mapCommon.LatLng

No

Yes

Longitude and latitude of a place.

poiTypes

Array<string>

No

Yes

Huawei POI type. The value range is the same as that of HwLocationType.

Comment

Defines comment information about a POI.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

averageRating

number

No

Yes

Average rating.

total

number

No

Yes

Total number of comments.

Aoi

Defines AOI information.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

area

number

No

Yes

AOI area.

distance

number

No

Yes

Linear distance between a place and the location specified by the input parameter location, in meters.

siteId

string

No

Yes

AOI ID.

location

mapCommon.LatLng

No

Yes

Longitude and latitude of a place.

name

string

No

Yes

Name of a place.

poiType

string

No

Yes

Huawei POI type. The value range is the same as that of HwLocationType.

direction

string

No

Yes

Direction of the AOI at the input point.

Start version: 5.0.0(12)

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

ReverseGeocodePoi

Defines the POI information of the reverse geocoding result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

address

string

No

Yes

Address.

direction

string

No

Yes

Direction of an input point towards the POI.

distance

number

No

Yes

Linear distance between a place and the location specified by the input parameter location, in meters.

siteId

string

No

Yes

ID of a place.

location

mapCommon.LatLng

No

Yes

Longitude and latitude of a place.

name

string

No

Yes

Name of a place.

poiType

string

No

Yes

Huawei POI type. The value range is the same as that of HwLocationType.

Road

Defines road information.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

direction

string

No

Yes

Direction of an input point along a road.

distance

number

No

Yes

Linear distance between a road and the location specified by the input parameter location, in meters.

siteId

string

No

Yes

Road ID.

location

mapCommon.LatLng

No

Yes

Longitude and latitude of a road.

name

string

No

Yes

Road name.

Intersection

Defines crosspoint information.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 4.1.0(11).

System capability: SystemCapability.Map.Core

Start version: 4.1.0(11)

Parameters:

Name

Type

Read-only

Optional

Description

direction

string

No

Yes

Direction of an input point towards a crosspoint.

distance

number

No

Yes

Linear distance between a crosspoint and the location specified by the input parameter location, in meters.

siteId

string

No

Yes

Crosspoint ID.

location

mapCommon.LatLng

No

Yes

Longitude and latitude of a crosspoint.

name

string

No

Yes

Crosspoint name.