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

從程式庫匯入依附元件

區域查詢開放原始碼程式庫提供一組函式和 TypeScript 類型，您必須將這些內容匯入程式碼。

針對區域查詢要求，請匯入以下內容：

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

針對區域搜尋要求，請匯入以下內容：

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

區域查詢要求

區域查詢要求會採用地點名稱或 ID 代碼，並傳回地點 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 為「加州」，而 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 為「聖塔克拉拉郡」，place_type 為 LOCALITY，則會傳回聖塔克拉拉郡的地點 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` ID

欄位	類型	說明
`place`	字串	要與地點 ID 比對的區域名稱。搭配使用 `place` 欄位與 `place_type`，即可查詢區域地點 ID。舉例來說，如果 `place_type` 為「locality」，有效的 `place` 可以是「加州帕羅奧圖」。如果 `place_type` 為「POSTAL_CODE」，有效的 place_name 可以是「94109」。如果 `place_type` 為「COUNTRY」，有效的 `place` 可以是「美國」等。另外，如果指定 `place`，就必須提供 `region_code`，除非 `place_type` 為「COUNTRY」。
`unit_code`	字串	要比對的 FIP 州/郡代碼 (僅限美國) 或 ISO-3166-1 國家/地區代碼。搭配使用 `unit_code` 欄位與 `place_type`，即可查詢區域地點 ID。例如：如果 `place_type` 為 `COUNTRY`，有效的 unit_code 可以是「US」(美國的 ISO-3166-1 Alpha-2 代碼) 或「BR」(巴西的 ISO-3166-1 Alpha-2 代碼)。如果 `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` ID

必要欄位：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`	多個候選項目與輸入內容相符。請檢查 `candidate_place_ids` (如適用)。
`PlaceNameNotUnderstood`	提供的地點名稱無法解析為區域。
`UnitCodeNotFound`	找不到單位代碼。請確認單位代碼是否有效，且提供的格式是否正確。
`PlaceTypeNotAllowed`	相符的地點 ID 不在地點類型和國家/地區的許可清單中。