# site（地点搜索）

本模块提供地点搜索服务。

**起始版本：** 4.1.0(11)

#### 导入模块

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

#### searchByText

searchByText(searchByTextParams: SearchByTextParams): Promise<SearchByTextResult>

通过指定的关键字和可选的地理范围，查询诸如旅游景点、企业和学校之类的地点。使用Promise异步回调。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| searchByTextParams | SearchByTextParams | 是 | 关键字搜索的参数。 |

**返回值：**

| 类型 | 说明 |
| --- | --- |
| Promise<SearchByTextResult> | Promise对象，返回SearchByTextResult。 |

**错误码：**

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 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. |

**示例：**

```
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>

通过指定的关键字和可选的地理范围，查询诸如旅游景点、企业和学校之类的地点，支持传入Context上下文。使用Promise异步回调。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 5.0.0(12)

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | common.Context | 是 | Context上下文。 |
| searchByTextParams | SearchByTextParams | 是 | 关键字搜索的参数。 |

**返回值：**

| 类型 | 说明 |
| --- | --- |
| Promise<SearchByTextResult> | Promise对象，返回SearchByTextResult。 |

**错误码：**

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 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. |

**示例：**

```
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(this.getUIContext().getHostContext(), params);
console.info("Succeeded in searching by text.");
```

#### nearbySearch

nearbySearch(nearbySearchParams: NearbySearchParams): Promise<NearbySearchResult>

通过用户传入自己的位置，可以返回周边地点列表。您可以通过提供关键字或指定要搜索的地点的类型来优化搜索结果。使用Promise异步回调。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| nearbySearchParams | NearbySearchParams | 是 | 周边搜索的参数。 |

**返回值：**

| 类型 | 说明 |
| --- | --- |
| Promise<NearbySearchResult> | Promise对象，返回NearbySearchResult。 |

**错误码：**

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 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. |

**示例：**

```
let params: site.NearbySearchParams = {
  location: {
    latitude:51.50811219132287,
    longitude:-0.07594896472392065
  },
  poiTypes: [
    "Watch_Store",
    "SUBWAY",
    "PRIMARY_SCHOOL",
    "GENERAL_AUTO_REPAIR_SERVICE_CENTER"
  ]
}
// 返回周边搜索结果
const result = await site.nearbySearch(params);
console.info(`Succeeded in searching nearby. result is ${result}`);
```

#### nearbySearch

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

通过用户传入自己的位置，可以返回周边地点列表，支持传入Context上下文。您可以通过提供关键字或指定要搜索的地点的类型来优化搜索结果。使用Promise异步回调。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 5.0.0(12)

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | common.Context | 是 | Context上下文。 |
| nearbySearchParams | NearbySearchParams | 是 | 周边搜索的参数。 |

**返回值：**

| 类型 | 说明 |
| --- | --- |
| Promise<NearbySearchResult> | Promise对象，返回NearbySearchResult。 |

**错误码：**

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 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. |

**示例：**

```
let params: site.NearbySearchParams = {
  location: {
    latitude:51.50811219132287,
    longitude:-0.07594896472392065
  },
  poiTypes: [
    "Watch_Store",
    "SUBWAY",
    "PRIMARY_SCHOOL",
    "GENERAL_AUTO_REPAIR_SERVICE_CENTER"
  ]
}
// 返回周边搜索结果
const result = await site.nearbySearch(this.getUIContext().getHostContext(), params);
console.info(`Succeeded in searching nearby. result is ${result}`);
```

#### queryAutoComplete

queryAutoComplete(queryAutoCompleteParams: QueryAutoCompleteParams): Promise<QueryAutoCompleteResult>

根据输入的关键字返回预测的输入关键字和地点查询建议。使用Promise异步回调。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| queryAutoCompleteParams | QueryAutoCompleteParams | 是 | 自动补全的参数。 |

**返回值：**

| 类型 | 说明 |
| --- | --- |
| Promise<QueryAutoCompleteResult> | Promise对象，返回QueryAutoCompleteResult。 |

**错误码：**

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 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. |

**示例：**

```
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>

根据输入的关键字返回预测的输入关键字和地点查询建议，支持传入Context上下文。使用Promise异步回调。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 5.0.0(12)

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | common.Context | 是 | Context上下文。 |
| queryAutoCompleteParams | QueryAutoCompleteParams | 是 | 自动补全的参数。 |

**返回值：**

| 类型 | 说明 |
| --- | --- |
| Promise<QueryAutoCompleteResult> | Promise对象，返回QueryAutoCompleteResult。 |

**错误码：**

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 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. |

**示例：**

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

#### searchById

searchById(searchByIdParams: SearchByIdParams): Promise<SearchByIdResult>

根据地点ID获取地点详情。地点详情包括：地点名称、地址详细信息、经纬度等。使用Promise异步回调。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| searchByIdParams | SearchByIdParams | 是 | 地点详情的参数。 |

**返回值：**

| 类型 | 说明 |
| --- | --- |
| Promise<SearchByIdResult> | Promise对象，返回SearchByIdResult。 |

**错误码：**

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 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. |

**示例：**

```
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>

根据地点ID获取地点详情，支持传入Context上下文。地点详情包括：地点名称、地址详细信息、经纬度等。使用Promise异步回调。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 5.0.0(12)

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | common.Context | 是 | Context上下文。 |
| searchByIdParams | SearchByIdParams | 是 | 地点详情的参数。 |

**返回值：**

| 类型 | 说明 |
| --- | --- |
| Promise<SearchByIdResult> | Promise对象，返回SearchByIdResult。 |

**错误码：**

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 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. |

**示例：**

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

#### geocode

geocode(geocodeParams: GeocodeParams): Promise<GeocodeResult>

根据结构化地址获取地点的经纬度。使用Promise异步回调。

根据地址获取地点的空间坐标，如经纬度，最多返回10条记录。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| geocodeParams | GeocodeParams | 是 | 正地理编码的参数。 |

**返回值：**

| 类型 | 说明 |
| --- | --- |
| Promise<GeocodeResult> | Promise对象，返回GeocodeResult。 |

**错误码：**

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 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. |

**示例：**

```
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>

根据结构化地址获取地点的经纬度，支持传入Context上下文。使用Promise异步回调。

根据地址获取地点的空间坐标，如经纬度，最多返回10条记录。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 5.0.0(12)

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | common.Context | 是 | Context上下文。 |
| geocodeParams | GeocodeParams | 是 | 正地理编码的参数。 |

**返回值：**

| 类型 | 说明 |
| --- | --- |
| Promise<GeocodeResult> | Promise对象，返回GeocodeResult。 |

**错误码：**

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 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. |

**示例：**

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

#### reverseGeocode

reverseGeocode(reverseGeocodeParams: ReverseGeocodeParams): Promise<ReverseGeocodeResult>

逆地理编码接口能够根据经纬度返回对应的地址信息，包括位置描述信息、结构化区划信息、周边POI地点等详细信息。使用Promise异步回调。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| reverseGeocodeParams | ReverseGeocodeParams | 是 | 逆地理编码的参数。 |

**返回值：**

| 类型 | 说明 |
| --- | --- |
| Promise<ReverseGeocodeResult> | Promise对象，返回ReverseGeocodeResult。 |

**错误码：**

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 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. |

**示例：**

```
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>

逆地理编码接口能够根据经纬度返回对应的地址信息，包括位置描述信息、结构化区划信息、周边POI地点等详细信息，支持传入Context上下文。使用Promise异步回调。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 5.0.0(12)

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| context | common.Context | 是 | Context上下文。 |
| reverseGeocodeParams | ReverseGeocodeParams | 是 | 逆地理编码的参数。 |

**返回值：**

| 类型 | 说明 |
| --- | --- |
| Promise<ReverseGeocodeResult> | Promise对象，返回ReverseGeocodeResult。 |

**错误码：**

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 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. |

**示例：**

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

#### SortRule

结果排序规则。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 5.0.0(12)

| 名称 | 值 | 说明 |
| --- | --- | --- |
| COMPOSITE | 0 | 综合排序。 |
| DISTANCE | 1 | 按距离排序。 |

#### SearchByTextParams

SearchByTextParams定义了搜索关键字的参数。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| query | string | 否 | 否 | 搜索关键字，例如“故宫”。参数的长度范围：[1, 512]。 |
| location | mapCommon.LatLng | 否 | 是 | 搜索结果的经纬度。 |
| radius | number | 否 | 是 | Location的搜索半径，单位：m。取值范围：[1, 50000]，默认50000米。小数点后数字忽略。异常值返回错误码401。 |
| poiTypes | Array<string> | 否 | 是 | 返回指定的华为分类体系的地点，取值范围参见HwLocationType。 |
| countryCodes | Array<string> | 否 | 是 | 在指定的国家内搜索，采用ISO 3166-1 alpha-2。 最多传5个国家或地区码。 |
| cityId | string | 否 | 是 | 在指定的城市内搜索，参数的长度范围：[1, 32]。 说明： - 支持中国大陆和港澳的中文城市名。 - 对中国大陆城市及港澳地区，支持传入3-4位数字cityCode或6位数字adminCode，参见城市码及区划代码表。 - 支持传入16-18位数字cityId。 |
| isCityLimit | boolean | 否 | 是 | 搜索结果是否强限制在指定城市内，默认值：false，需配合cityId参数使用，若未传cityId按默认值false处理。 - true：强限制在指定城市内 - false：不强限制在指定城市内 |
| language | string | 否 | 是 | 返回结果的语言类型，参数的长度范围：[1, 16]。语种取值请参见位置搜索支持语言列表。 如果不传，默认返回地点的当地语言。异常值按默认值处理。 |
| pageSize | number | 否 | 是 | 每页返回的记录数。取值范围：[1, 20]，默认值为20。 |
| pageIndex | number | 否 | 是 | 当前页数。取值范围：[1, 500]，默认值为1。 说明： pageIndex * pageSize <= 500 |
| isChildren | boolean | 否 | 是 | 是否返回子节点，默认为false。 - true：如果有子节点信息，则返回子节点的全量信息 - false：不返回 |

#### NearbySearchParams

周边搜索的参数。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| location | mapCommon.LatLng | 否 | 否 | 当前用户的定位。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| radius | number | 否 | 是 | 搜索结果限定的半径范围，单位：m。取值范围：[1, 50000]，默认值为1000米。小数点后数字忽略。异常值返回错误码401。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| query | string | 否 | 是 | 搜索关键字，参数的长度范围：[1, 512]。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| poiTypes | Array<string> | 否 | 是 | 返回指定的华为分类体系的地点，取值范围参见HwLocationType。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| language | string | 否 | 是 | 输入语言，参数的长度范围：[1, 16]。语种取值请参见位置搜索支持语言列表。 如果不传，默认返回地点的当地语言。异常值按默认值处理。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| pageSize | number | 否 | 是 | 每页返回的记录数。取值范围：[1, 20]，默认值为20。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| pageIndex | number | 否 | 是 | 当前页数。取值范围：[1, 500]，默认值为1。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 说明： pageIndex * pageSize <= 500 |
| sortRule | SortRule | 否 | 是 | 排序规则，默认值为SortRule.COMPOSITE。 起始版本： 5.0.0(12) 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。 |

#### QueryAutoCompleteParams

自动补全的参数。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| query | string | 否 | 否 | 搜索关键字，参数的长度范围：[1, 512]。 |
| location | mapCommon.LatLng | 否 | 是 | 搜索结果的经纬度。 |
| radius | number | 否 | 是 | Location的搜索半径，单位：m。取值范围：[1, 50000]，默认值为50000米。小数点后数字忽略。异常值返回错误码401。 |
| poiTypes | Array<string> | 否 | 是 | 返回指定的华为分类体系的地点，取值范围参见HwLocationType。 |
| cityId | string | 否 | 是 | 在指定的城市内搜索，参数的长度范围：[1, 32]。 说明： - 支持中国大陆和港澳的中文城市名。 - 对中国大陆城市及港澳地区，支持传入3-4位数字cityCode或6位数字adminCode，参见城市码及区划代码表。 - 支持传入16-18位数字cityId。 |
| isCityLimit | boolean | 否 | 是 | 搜索结果是否强限制在指定城市内，默认值：false，需配合cityId参数使用，若未传cityId按默认值false处理。 - true：强限制在指定城市内 - false：不强限制在指定城市内 |
| language | string | 否 | 是 | 输入语言，参数的长度范围：[1, 16]。语种取值请参见位置搜索支持语言列表。 如果不传，默认返回地点的当地语言。异常值按默认值处理。 |
| isChildren | boolean | 否 | 是 | 是否返回子节点，默认为false。 - true：如果有子节点信息，则返回子节点的全量信息 - false：不返回 |

#### SearchByIdParams

地点详情的参数。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| siteId | string | 否 | 否 | 地址ID，参数的长度范围：[1, 256]。 |
| language | string | 否 | 是 | 输入语言，参数的长度范围：[1, 16]。语种取值请参见位置搜索支持语言列表。 如果不传，默认返回地点的当地语言。异常值按默认值处理。 |
| isChildren | boolean | 否 | 是 | 是否返回子节点，默认为false。 - true：如果有子节点信息，则返回子节点的全量信息 - false：不返回 |

#### ReverseGeocodeParams

逆地理编码的参数。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| location | mapCommon.LatLng | 否 | 否 | 经纬度。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| language | string | 否 | 是 | 输入语言，参数的长度范围：[1, 16]。语种取值请参见位置搜索支持语言列表。 如果不传，默认返回地点的当地语言。异常值按默认值处理。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| radius | number | 否 | 是 | 搜索半径，单位：m。取值范围：[0, 1000]，默认值为1000。小数点后数字忽略。异常值返回错误码401。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| isExtension | boolean | 否 | 是 | 是否扩展返回POI、Aoi、Road、交叉口等信息，推荐设置为true，默认为false。 - true：扩展信息 - false：不扩展，仅返回区划信息 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 说明： 拓展返回信息时，POI信息最多展示30个，Aoi信息最多展示10个，Road信息最多展示3个，交叉口信息最多展示1个。 |
| poiTypes | Array<string> | 否 | 是 | 返回指定的华为分类体系的地点，取值范围参见HwLocationType。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| isNearbyAoi | boolean | 否 | 是 | 是否返回附近的Aoi。 仅当isExtension=true时生效。 推荐设置为true，默认值为false。 - true：返回附近的Aoi - false：仅返回传入经纬度所在的Aoi 起始版本： 5.0.0(12) 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。 |
| sortRule | SortRule | 否 | 是 | POI的排序规则。 默认值为SortRule.DISTANCE，即按距离排序。 起始版本： 5.0.0(12) 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。 |

#### GeocodeParams

正地理编码的参数。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| query | string | 否 | 否 | 地址信息，参数的长度范围：[1, 512]。 |
| language | string | 否 | 是 | 输入语言，参数的长度范围：[1, 16]。语种取值请参见位置搜索支持语言列表。 如果不传，默认返回地点的当地语言。异常值按默认值处理。 |
| bounds | mapCommon.LatLngBounds | 否 | 是 | 查询结果的搜索范围。 |

#### SearchByTextResult

关键字搜索的结果。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| totalCount | number | 否 | 否 | 如果查询成功，返回满足搜索条件的记录总数。 |
| sites | Array<Site> | 否 | 是 | 如果查询成功，返回搜索结果。 |

#### NearbySearchResult

周边搜索的结果。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| totalCount | number | 否 | 否 | 如果查询成功，返回满足搜索条件的记录总数。 |
| sites | Array<Site> | 否 | 是 | 如果查询成功，返回搜索结果。 |

#### QueryAutoCompleteResult

自动补全的结果。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| sites | Array<Site> | 否 | 是 | 如果查询成功，返回搜索结果。 |

#### SearchByIdResult

地点详情的结果。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| site | Site | 否 | 是 | 如果查询成功，返回地点详情。 |

#### ReverseGeocodeResult

逆地理编码的结果。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| addressComponent | AddressComponent | 否 | 否 | 地址详细信息。 |
| addressDescription | string | 否 | 否 | 非结构化的地址文本。 |
| aois | Array<Aoi> | 否 | 是 | Aoi面信息。 |
| pois | Array<ReverseGeocodePoi> | 否 | 是 | POI信息。 |
| roads | Array<Road> | 否 | 是 | 道路信息。 |
| intersections | Array<Intersection> | 否 | 是 | 交叉点信息。 |

#### GeocodeResult

正地理编码的结果。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| sites | Array<Site> | 否 | 是 | 如果查询成功，返回搜索结果。 |

#### Site

地点详情。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| siteId | string | 否 | 否 | 地点的唯一主键。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| name | string | 否 | 是 | 地点名称。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| formatAddress | string | 否 | 是 | 格式化的地点详细地址。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| addressComponent | AddressComponent | 否 | 否 | 地址详细信息。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| location | mapCommon.LatLng | 否 | 是 | 地点的经纬度。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| viewport | mapCommon.LatLngBounds | 否 | 是 | 地点的视口范围。 说明： queryAutoComplete不支持返回此字段。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| distance | number | 否 | 是 | 预测地点和传参location之间的直线距离，单位：m。 说明： 目前仅关键字搜索和周边搜索支持返回此字段。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| poi | Poi | 否 | 是 | 如果地点是POI类型，返回POI信息。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| utcOffset | number | 否 | 是 | 位置所在时区和UTC时区的差值，单位：分钟。 说明： 自动补全不支持返回此字段。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| reliability | number | 否 | 是 | 相关性，可用于判断搜索结果是否准确。取值范围：[0, 1]，数值越大相关性越高，1表示完全相关。 起始版本： 6.1.1(24) 元服务API： 从版本6.1.1(24)开始，该接口支持在元服务中使用。 |

#### AddressComponent

地址详细信息。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| countryCode | string | 否 | 是 | 国家/地区码。 |
| countryName | string | 否 | 是 | 国家名。 |
| adminLevel1 | string | 否 | 是 | 一级行政区。 |
| adminLevel2 | string | 否 | 是 | 二级行政区。 |
| adminLevel3 | string | 否 | 是 | 三级行政区。 |
| adminLevel4 | string | 否 | 是 | 四级行政区。 |
| adminLevel5 | string | 否 | 是 | 五级行政区。 |
| locality | string | 否 | 是 | 地区、区域。 |
| subLocality1 | string | 否 | 是 | 一级子区域。 |
| subLocality2 | string | 否 | 是 | 二级子区域。 |
| neighborhoods | Array<string> | 否 | 是 | 街区、城区。 |
| adminCode | string | 否 | 是 | 行政区划码。 说明： 接口返回的行政区划码覆盖中国大陆及港澳地区，包括省份、城市、区/县、乡镇/街道等层级，文档附录中仅提供部分城市行政区划码示例。 |
| postalCode | string | 否 | 是 | 邮政编码。 |
| city | City | 否 | 是 | 城市信息。 |
| streetNumber | StreetNumber | 否 | 是 | 街道号。 |

#### City

城市信息。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| cityCode | string | 否 | 是 | 城市码。 |
| cityId | string | 否 | 是 | 城市ID。 |
| cityName | string | 否 | 是 | 城市名称。 |

#### StreetNumber

街道号。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| direction | string | 否 | 是 | 该输入点在街道的方向。 |
| distance | number | 否 | 是 | 地点和传参location之间的直线距离，单位：m。 |
| location | mapCommon.LatLng | 否 | 是 | 街道经纬度。 |
| streetNumber | string | 否 | 是 | 街道号。 |
| streetName | string | 否 | 是 | 街道名称。 |
| formatAddress | string | 否 | 是 | 格式化的街道地址。 |

#### Poi

POI信息。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| poiTypes | Array<string> | 否 | 是 | 华为POI分类体系，取值范围请参见HwLocationType。 |
| poiTypeIds | Array<string> | 否 | 是 | 华为POI分类体系Id，预留字段，当前无使用场景。 |
| phone | string | 否 | 是 | 电话号码。 |
| internationalPhone | string | 否 | 是 | 国际电话号码。 |
| rating | number | 否 | 是 | 评分。 |
| websiteUrl | string | 否 | 是 | 网址。 |
| openingHours | OpeningHours | 否 | 是 | 营业时间。 |
| businessStatus | string | 否 | 是 | 营业状态，其中包括： - OPEN_NOW：正在营业。 - CLOSE_NOW：已休息。 - CLOSED_TEMPORARILY：临时关闭。 - CLOSED_PERMANENTLY：永久关闭。 - STATUS_UNKNOWN：未知。 说明： 仅地点详情接口返回。 |
| brand | string | 否 | 是 | 品牌名称。 |
| email | string | 否 | 是 | 邮箱地址。 |
| starRating | number | 否 | 是 | 星级评定。 |
| childNodes | Array<ChildNode> | 否 | 是 | POI的子节点信息。 |
| icon | string | 否 | 是 | POI图标地址。 |
| description | string | 否 | 是 | 描述信息。 |
| abstractText | string | 否 | 是 | 摘要信息。 |
| comment | Comment | 否 | 是 | POI的评论信息。 |

#### OpeningHours

营业时间。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| texts | Array<string> | 否 | 是 | 每个星期的开放时间段的描述。 |
| periods | Array<Period> | 否 | 是 | 开放时间段的详细说明。 |

#### Period

开放时间段的详细说明。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| open | TimeOfWeek | 否 | 是 | 开放时间。 |
| close | TimeOfWeek | 否 | 是 | 关闭时间。 |

#### TimeOfWeek

时间模型。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| week | number | 否 | 是 | 0：星期日 1：星期一 2：星期二 3：星期三 4：星期四 5：星期五 6：星期六 |
| time | string | 否 | 是 | 24小时制时间，hhmm格式。 |

#### ChildNode

POI的子节点信息。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| siteId | string | 否 | 是 | 位置ID。 |
| name | string | 否 | 是 | 地点名称。 |
| formatAddress | string | 否 | 是 | 格式化的地点详细地址。 |
| location | mapCommon.LatLng | 否 | 是 | 地点的经纬度。 |
| poiTypes | Array<string> | 否 | 是 | 华为分类体系，取值范围参见HwLocationType。 |

#### Comment

POI的评论信息。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| averageRating | number | 否 | 是 | 平均分。 |
| total | number | 否 | 是 | 总数。 |

#### Aoi

Aoi面信息。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| area | number | 否 | 是 | Aoi面积，单位：m2。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| distance | number | 否 | 是 | 地点和传参location之间的直线距离，单位：m。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| siteId | string | 否 | 是 | Aoi ID。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| location | mapCommon.LatLng | 否 | 是 | 地点的经纬度。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| name | string | 否 | 是 | 地点名称。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| poiType | string | 否 | 是 | 华为POI分类体系，取值范围请参见HwLocationType。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| direction | string | 否 | 是 | 该Aoi在输入点的方向。 起始版本： 5.0.0(12) 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。 |

#### ReverseGeocodePoi

逆地理结果POI信息。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| address | string | 否 | 是 | 地址。 |
| direction | string | 否 | 是 | 该输入点在POI的方向。 |
| distance | number | 否 | 是 | 地点和传参location之间的直线距离，单位：m。 |
| siteId | string | 否 | 是 | 地点ID。 |
| location | mapCommon.LatLng | 否 | 是 | 地点的经纬度。 |
| name | string | 否 | 是 | 地点名称。 |
| poiType | string | 否 | 是 | 华为POI分类体系，取值范围请参见HwLocationType。 |

#### Road

道路信息。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| direction | string | 否 | 是 | 该输入点在道路的方向。 |
| distance | number | 否 | 是 | 道路和传参location之间的直线距离，单位：m。 |
| siteId | string | 否 | 是 | 道路ID。 |
| location | mapCommon.LatLng | 否 | 是 | 道路的经纬度。 |
| name | string | 否 | 是 | 道路名称。 |

#### Intersection

交叉点信息。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**起始版本：** 4.1.0(11)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| direction | string | 否 | 是 | 该输入点与交叉口的方位关系。 |
| distance | number | 否 | 是 | 交叉点和传参location之间的直线距离，单位：m。 |
| siteId | string | 否 | 是 | 交叉点ID。 |
| location | mapCommon.LatLng | 否 | 是 | 交叉点的经纬度。 |
| name | string | 否 | 是 | 交叉点名称。 |