使用 Region Lookup API

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

  • 地区查找,即按地点名称、FIPS 代码(仅限美国各州县)或 ISO-3166-1 国家/地区代码来查找地区。
  • 地区搜索,即搜索特定位置(以地址、LatLng 或地点 ID 的形式指定)所在的地区。

支持的地区地点类型

支持以下地区地点类型:countryadministrative_area_level_1administrative_area_level_2postal_codelocality

安装库

若要使用 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

  • placeunit_code(必需):地点的地区名称 (place) 或 unit_codeunit_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 });

必须指定 placeunit_code 参数。如果未指定,则系统会返回错误。

除非 place_typeCOUNTRY,否则必须指定 region_code 参数。

placeunit_code 指定与地点 ID 匹配的位置。例如,如果 place 为“California”(加利福尼亚州),并且 place_typeADMINISTRATIVE_AREA_LEVEL_1,API 会返回加利福尼亚州的地点 ID 作为 matched_place_id

  • place_typeADMINISTRATIVE_AREA_LEVEL_1

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

如果 unit_code 为“6”(加利福尼亚州的 FIPS 代码),place_typeADMINISTRATIVE_AREA_LEVEL_1,并且 region_code 为“US”,API 会返回加利福尼亚州的地点 ID:

  • place_typeADMINISTRATIVE_AREA_LEVEL_1
  • region_codeUS

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

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

  • place_typeCOUNTRY

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

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

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

“地区查找”响应

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

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

“地区搜索”请求

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

  • addresslatlngplace_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_typeCOUNTRY,则有效的 unit_code 可以是“US”(美国的 ISO-3166-1 二位字母代码)或“BR”(巴西的 ISO-3166-1 二位字母代码)。如果 place_typeADMINISTRATIVE_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 标识符

必需addresslatlngplace_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 不在地点类型和国家/地区的许可名单中。