Announcement: New basemap styling is coming soon to Google Maps Platform. This update to map styling includes a new default color palette, modernized pins, and improvements to map experiences and usability. All map styles will be automatically updated in March 2025. For more information on availability and how to opt in earlier, see New map style for Google Maps Platform.

Region Lookup API を使用する

Region Lookup API を使用すると、地域のプレイス ID を確認し、そのプレイス ID を使用して、境界線用データドリブンスタイル設定で境界線ポリゴンのスタイルを設定できます。Region Lookup API では、次の 2 種類のリクエストがサポートされます。

地域照合は、地名、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 タイピングが一式用意されています。

地域照合リクエストの場合は、以下をインポートします。

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 — 照合する場所の 2 文字の ISO-3166 国 / 地域コード。place_type が COUNTRY の場合、region_code は省略可能です。
language — 「en-US」や「sr-Latn」などの BCP-47 言語コード。指定しない場合、デフォルトは 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 が「サンタクララ郡」で、place_type が LOCALITY の場合、サンタクララ郡のプレイス ID が候補として返されます。

地域照合レスポンス

結果が見つかった場合、LookupRegionResponse オブジェクトには matched_place_id が含まれます。結果が見つからない場合は、信頼度の低いプレイス ID が候補 ID として、デバッグ情報を含むエラーコードとともに返されます。

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

地域検索リクエスト

特定の場所を含む地域を検索するには、次のパラメータで SearchRegionRequestData を指定して searchRegion を呼び出します。

address、latlng、または place_id（必須） — 地域に含まれている構造化されていない住所の文字列、latlng、プレイス ID のいずれかが含まれます（例: 地図上の場所、建物など）。指定しない場合はエラーが返されます。
place_type（必須） — 検索する地域のタイプの場所タイプ値。
region_code — 照合する場所の 2 文字の ISO-3166 国 / 地域コード。address を指定する場合は、region_code を指定する必要があります。
language — 「en-US」や「sr-Latn」などの BCP-47 言語コード。指定しない場合、デフォルトは 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 が含まれます。一致するものが見つからなかった場合、レスポンスには 1 つ以上のプレイス 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 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`	文字列	照合している場所の 2 文字の 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`	文字列	照合する場所の 2 文字の ISO-3166 国 / 地域コード。住所を指定する場合は `region_code` が必要です。

場所タイプ

値	説明
`POSTAL_CODE`	対象の国内で郵便物の宛先として使用される郵便番号。
`ADMINISTRATIVE_AREA_LEVEL_1`	国の 1 段階下の行政区画。米国内の場合、州がこの行政区画レベルに相当します。
`ADMINISTRATIVE_AREA_LEVEL_2`	国の 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 が、場所タイプと国の許可リストに含まれていません。