使用 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，请按以下步骤操作：

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

从库导入依赖项

Region Lookup 开源库提供了一系列函数和 TypeScript 类型定义，您必须将其导入到您的代码中。

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

    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 可以是“Palo Alto, CA”（加利福尼亚州帕洛阿尔托）。如果 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 不在地点类型和国家/地区的许可名单中。