使用 Region Lookup API

借助 Region Lookup API，您可以查找地区的地点 ID，并将其用于为边界多边形设置数据驱动型样式。Region Lookup API 支持以下两种请求：

地区查找按地点名称、FIPS 代码（仅限美国各州县）或 ISO-3166-1 国家/地区代码来查找地区。
地区搜索搜索包含特定位置的地区，以地址、LatLng 或地点 ID 的形式指定。

支持的地区地点类型

支持以下地区地点类型：country、administrative_area_level_1、administrative_area_level_2、postal_code、locality。

安装库

若要使用 Region Lookup API，请按以下步骤操作：

在控制台中启用 Region Lookup API。
安装开源库：npm install @googlemaps/region-lookup

从库导入依赖项

Region Lookup 开源库提供了一系列函数和 TypeScript typings，您需要将其导入您的代码中。

对于“地区查找”请求，请导入以下内容：

import {
  lookupRegion,
  LookupRegionRequestData,
  LookupRegionResponseData,
  LookupRegionResponse,
  RegionIdentifier
} from "@googlemaps/region-lookup";

对于“地区搜索”请求，请导入以下内容：

import {
  searchRegion,
  RegionSearchValue,
  SearchRegionRequestData,
  SearchRegionResponse
} from "@googlemaps/region-lookup";

“地区查找”请求

“地区查找”请求接受地点名称或标识符代码，并返回地点 ID。若要查找地区，请调用 lookupRegion()，并指定包含以下参数的 LookupRegionRequestData：

place 或 unit_code（必需）：地点的地区名称 (place) 或 unit_code。unit_code 可以是 FIPS 代码（仅限美国各州县），也可以是 ISO-3166-1 国家/地区代码。
place_type（必需）：要查找的地点类型的地点类型值。
region_code：要匹配的位置的 ISO-3166 国家/地区代码（由两个字母组成）。如果 place_type 为 COUNTRY，则 region_code 是可选的。
language：BCP-47 语言代码，例如“en-US”或“sr-Latn”。如果未指定，则默认为 en-US。

以下示例展示了针对新泽西州纽瓦克的查找请求。

// Headers
const headers = {
  "X-Goog-Api-Key": "YOUR API KEY",
};
const data: LookupRegionRequestData = {
  identifiers: [
    {
      "place": "newark",
      "place_type": "locality",
      "region_code": "us",
      "language": "en",
    },
  ],
};
const response: LookupRegionResponse = await RegionLookup.lookupRegion({ headers, data });

必须指定 place 或 unit_code 参数。如果未指定，则系统会返回错误。

除非 place_type 为 COUNTRY，否则必须指定 region_code 参数。

place 和 unit_code 指定与地点 ID 匹配的位置。例如，如果 place 为“California”（加利福尼亚州），并且 place_type 为 ADMINISTRATIVE_AREA_LEVEL_1，API 会返回加利福尼亚州的地点 ID 作为 matched_place_id：

place_type：ADMINISTRATIVE_AREA_LEVEL_1

matched_place_id 结果：加利福尼亚州的地点 ID。所有其他支持的类型均不会返回任何匹配项。

如果 unit_code 为“6”（加利福尼亚州的 FIPS 代码），place_type 为 ADMINISTRATIVE_AREA_LEVEL_1，并且 region_code 为“US”，API 会返回加利福尼亚州的地点 ID：

place_type：ADMINISTRATIVE_AREA_LEVEL_1
region_code：US

matched_place_id 结果：加利福尼亚州的地点 ID。所有其他支持的类型均不会返回任何匹配项。

如果 unit_code 为“US”，那么指定以下 place_type 时，API 会返回以下结果：

place_type：COUNTRY

matched_place_id 结果：美国的地点 ID。所有其他支持的类型均不会返回任何匹配项。

如果未找到任何匹配项，则表示 matched_place_id 未设置。

在不明确的情况下，系统会返回候选地点 ID。例如，如果 place 为“Santa Clara County”（圣克拉拉县），并且 place_type 为 LOCALITY，圣克拉拉县的地点 ID 会作为候选 ID 返回。

“地区查找”响应

如果找到了结果，LookupRegionResponse 对象会包含 matched_place_id。如果未找到任何结果，系统会将置信度较低的地点 ID 作为候选 ID 返回，同时返回包含调试信息的错误代码。

{
  "matches": [
    {
      "matchedPlaceId": "ChIJPV4oX_65j4ARVW8IJ6IJUYs"
    }
  ]
}

“地区搜索”请求

若要查找包含特定位置的地区，请调用 searchRegion，并指定包含以下参数的 SearchRegionRequestData：

address、latlng 或 place_id（必需）：包含非结构化地址字符串、latlng 或地区所包含的地点 ID（例如地图注点、建筑物等）。如果未指定，则系统会返回错误。
place_type（必需）：要搜索的地区类型的地点类型值。
region_code：要匹配的位置的 ISO-3166 国家/地区代码（由两个字母组成）。如果指定了 address，则 region_code 是必需的。
language：BCP-47 语言代码，例如“en-US”或“sr-Latn”。如果未指定，则默认为 en-US。

以下示例展示了针对加利福尼亚州伯班克的查找请求。

// Headers
const headers = {
  "X-Goog-Api-Key": "YOUR API KEY",
};

const data: SearchRegionRequestData = {
  search_values: [
    {
      "address": "2627 N Hollywood Way, Burbank, CA" ,
      "place_type": "locality" as const,
      "region_code": "us"
    },
  ],
};
const response = await regionLookupClient.searchRegion({ headers, data });

“地区搜索”响应

如果找到了结果，SearchRegionResponse 对象会包含 matched_place_id。如果匹配失败，响应会包含一个或多个候选地点 ID 以及错误代码。

{
  "matches": [
    {
      "matchedPlaceId": "ChIJPV4oX_65j4ARVW8IJ6IJUYs"
    }
  ]
}

参考

`LookupRegionRequestData` 标识符

字段	类型	说明
`place`	字符串	要与地点 ID 匹配的地区的名称。将 `place` 字段与 `place_type` 结合使用可查找地区地点 ID。例如，如果 `place_type` 为“locality”，则有效的 `place` 可以是“加利福尼亚州帕洛阿尔托”。如果 `place_type` 为“POSTAL_CODE”，则有效的 place_name 可以是“94109”。如果 `place_type` 为“COUNTRY”，则有效的 `place` 可以是“United States”（美国）等。如果指定了 `place`，除非 `place_type` 为“COUNTRY”，否则 `region_code` 是必需的。
`unit_code`	字符串	要匹配的 FIP 州县代码（仅限美国）或 ISO-3166-1 国家/地区代码。将 `unit_code` 字段与 `place_type` 结合使用可查找地区地点 ID。例如：如果 `place_type` 为 `COUNTRY`，则有效的 unit_code 可以是“US”（美国的 ISO-3166-1 二位字母代码）或“BR”（巴西的 ISO-3166-1 二位字母代码）。如果 `place_type` 为 `ADMINISTRATIVE_AREA_LEVEL_1`（州）且 region_code 为“US”，则有效的 unit_code 可以是“6”（加利福尼亚州的 FIP 代码）或“12”（佛罗里达州的 FIP 代码）。如果 place_type 为 `ADMINISTRATIVE_AREA_LEVEL_2`（县）且 region_code 为“US”，则有效的 unit_code 可以是“6001”（加利福尼亚州阿拉梅达县的 FIP 代码）或“12086”（佛罗里达州迈阿密-戴德县的 FIP 代码）。指定 FIP 代码时 `region_code` 是必需的。对于 ISO-3166-1 国家/地区代码，系统会忽略 `region_code`。
`place_type`	PlaceType	必需。要匹配的地区的类型。
`region_code`	字符串	您尝试匹配的位置的 ISO-3166 国家/地区代码（由两个字母组成）。如果 `place_type` 为“COUNTRY”，则 region_code 是可选的。
`language_code`	字符串	BCP-47 语言代码（例如“en-US”或“sr-Latn”），对应于请求地点名称和地址时所用的语言。如果未发出任何请求，则默认为英语。

`SearchRegionRequestData` 标识符

必需：address、latlng 或 place_id 中的一个。

字段	类型	说明
`address`	字符串	要匹配的地区内包含的非结构化街道地址。如果指定了 `address`，则 `region_code` 是必需的。
`latlng`	LatLng	要匹配的地区内包含的纬度和经度。
`place_id`	字符串	要匹配的地区内包含的地点 ID。
`place_type`	地点类型	必需。要匹配的地区的类型。
`language_code`	字符串	BCP-47 语言代码（例如“en-US”或“sr-Latn”），对应于请求地点名称和地址时所用的语言。如果未发出任何请求，则默认为英语。
`region_code`	字符串	要匹配的位置的 ISO-3166 国家/地区代码（由两个字母组成）。如果指定了地址，则 `region_code` 是必需的。

地点类型

值	说明
`POSTAL_CODE`	表示国家/地区内邮寄地址所用的邮政编码。
`ADMINISTRATIVE_AREA_LEVEL_1`	表示国家/地区级别以下的一级行政实体。在美国，这类行政级别是指州。
`ADMINISTRATIVE_AREA_LEVEL_2`	表示国家/地区级别以下的二级行政实体。在美国，这类行政级别是指县。
`LOCALITY`	表示有建制的城市或城镇政治实体。
`COUNTRY`	表示国家政治实体，通常是具有最高级别的类型。

LatLng

表示纬度/经度对的对象。该对象以一对双精度数表示，分别代表纬度度数和经度度数。除非另有说明，否则该对象必须符合 WGS84 标准。值必须介于标准化范围内。

字段	类型	说明
`latitude`	双精度	纬度（以度为单位）。它必须在 `[-90.0, +90.0]` 范围内。例如 `47.47583476464538`。
`longitude`	双精度	经度（以度为单位）。它必须在 `[-180.0, +180.0]` 范围内。例如 `-121.73858779269906`。

错误代码

值	说明
`UnknownError`	发生了未知错误。
`NoMatchFound`	没有与请求匹配的项，请检查 `candidate_place_ids`（如果有）。
`AddressNotUnderstood`	对所提供地址进行的地理编码失败。
`PlaceTypeMismatch`	响应中的地点类型与请求的地点类型不匹配。例如，请求的是 `locality`，但返回的是 `administrative_area_level_2`。
`MultipleCandidatesFound`	有多个候选 ID 与输入内容匹配。请检查 `candidate_place_ids`（如果有）。
`PlaceNameNotUnderstood`	提供的地点名称未能解析为地区。
`UnitCodeNotFound`	找不到单位代码。请验证单位代码是否有效，以及是否以正确的格式提供。
`PlaceTypeNotAllowed`	匹配的地点 ID 不在地点类型和国家/地区的许可名单中。