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 を使用する手順は次のとおりです。

  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 コードを受け取り、プレイス 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 が、場所タイプと国の許可リストに含まれていません。