Geocoding v3 から v4 に移行する

欧州経済領域（EEA）のデベロッパー

Geocoding API v4 では、API の v3 の機能を置き換える新しいメソッドがいくつか導入されています。このガイドでは、新しい v4 メソッドを使用するようにアプリを移行する方法について説明します。

既存の API キーは、新しい v4 メソッドで使用できます。ただし、API の v3 で割り当ての引き上げをリクエストした場合は、新しい v4 API で引き上げをリクエストする必要があります。

v3 の順方向ジオコーディングから移行する

v3 のジオコーディングを使用して住所をジオコーディングする場合は、GET リクエストを受け付ける v4 の住所のジオコーディング メソッドに移行する必要があります。

v4 API では、いくつかのパラメータの名前、構造、サポートが変更されています。レスポンスで返されるフィールドを指定するには、フィールド マスクを使用することを 強くおすすめします。

リクエスト パラメータの変更

v3 パラメータ v4 パラメータ メモ
address、components address 構造化されていない住所（v3 address）が URL パスで渡されるようになりました。コンポーネント フィルタ（v3 の components）が address.* クエリ パラメータとして渡されるようになりました。
bounds locationBias.rectangle 名前が変更され、構造がオブジェクトに変更されました。
language languageCode 名前変更済み
region regionCode 名前変更済み
extra_computations 削除済み

レスポンス フィールドの変更

v3 フィールド v4 フィールド メモ
status、error_message 削除済み v4 では HTTP ステータス コードとエラー本文が使用されます。
results.address_components.long_name / results.address_components.short_name results.addressComponents.longText / results.addressComponents.shortText 名前変更済み
results.geometry.location_type results.granularity 名前変更済み
results.geometry.location results.location フィールド名: lat/lng -> latitude/longitude
results.geometry.viewport results.viewport フィールド名: northeast/southwest -> high/low
results.postcode_localities results.postalCodeLocalities 名前変更済み1 つ以上の地域で返されるようになりました（v3 では 2 つ以上が必要でした）。
results.partial_match 削除済み
新機能 results.addressComponents.languageCode 特定の住所コンポーネントの言語。
新機能 results.bounds high/low を使用した明示的な境界。
新機能 results.place 場所のリソース名。
新機能 results.postalAddress 構造化された PostalAddress オブジェクト。

v3 のリバース ジオコーディングから移行する

v3 のリバース ジオコーディングを使用して座標を住所に変換する場合は、GET リクエストを受け付ける v4 の場所のリバース ジオコーディング メソッドに移行する必要があります。

v4 API では、いくつかのパラメータの名前、構造、サポートが変更されています。レスポンスで返されるフィールドを指定するには、フィールド マスクを使用することを 強くおすすめします。

リクエスト パラメータの変更

v3 パラメータ v4 パラメータ メモ
language languageCode 名前変更済み
region regionCode 名前変更済み
result_type types 名前が変更され、繰り返しクエリ パラメータを使用するようになりました。
location_type granularity 名前が変更され、繰り返しクエリ パラメータを使用するようになりました。
extra_computations 削除済み

レスポンス フィールドの変更

v3 フィールド v4 フィールド メモ
status、error_message 削除済み v4 では HTTP ステータス コードとエラー本文が使用されます。
results.address_components.long_name / results.address_components.short_name results.addressComponents.longText / results.addressComponents.shortText 名前変更済み
results.geometry.location_type results.granularity 名前変更済み
results.geometry.location results.location フィールド名: lat/lng -> latitude/longitude
results.geometry.viewport results.viewport フィールド名: northeast/southwest -> high/low
新機能 results.addressComponents.languageCode 特定の住所コンポーネントの言語。
新機能 results.bounds high/low を使用した明示的な境界。
新機能 results.place 場所のリソース名。
新機能 results.postalAddress 構造化された PostalAddress オブジェクト。

v3 の場所のジオコーディングから移行する

Geocoding v3 で place_id を使用して特定のプレイス ID の住所を取得する場合は、GET リクエストを受け付ける v4 の Place Geocoding メソッドに移行する必要があります。

v4 API では、いくつかのパラメータの名前、構造、サポートが変更されています。レスポンスで返されるフィールドを指定するには、フィールド マスクを使用することを 強くおすすめします。

リクエスト パラメータの変更

v3 パラメータ v4 パラメータ メモ
place_id リクエスト proto の place フィールド プレイス ID がパスパラメータ places/{place} として提供されるようになりました（例: https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw）。これは、基盤となるリクエストの place フィールドにマッピングされます。
language languageCode 名前変更済み
region regionCode 名前変更済み

レスポンス フィールドの変更

v3 フィールド v4 フィールド メモ
status、error_message 削除済み v4 では HTTP ステータス コードとエラー本文が使用されます。
results （ルート） v4 では results 配列ではなく、単一の結果オブジェクトが返されます。
results.address_components.long_name / results.address_components.short_name addressComponents.longText / addressComponents.shortText 名前変更済み
results.geometry.location_type granularity 名前変更済み
results.geometry.location location フィールド名: lat/lng -> latitude/longitude
results.geometry.viewport viewport フィールド名: northeast/southwest -> high/low
results.postcode_localities postalCodeLocalities 名前変更済み1 つ以上の地域で返されるようになりました（v3 では 2 つ以上が必要でした）。
新機能 addressComponents.languageCode 特定の住所コンポーネントの言語。
新機能 bounds high/low を使用した明示的な境界。
新機能 place 場所のリソース名。
新機能 postalAddress 構造化された PostalAddress オブジェクト。

Geocoding のハイパーローカル データから Destinations に移行する

Geocoding API v3 の次の機能は、 SearchDestinations Geocoding API v4 のメソッドに置き換えられます。

  • 入り口
  • ナビゲーション ポイント
  • 建物の輪郭
  • 敷地

上記の機能に Geocoding API v3 を使用していた場合は、このドキュメントを参考にして、代わりに SearchDestinations メソッドを使用してこれらの機能を取得してください。 このドキュメントでは、SearchDestinations レスポンスでこれらの機能を見つける場所と、Geocoding API v3 と Geocoding API v4 の SearchDestinations メソッドでこれらの機能が API レスポンスでどのように表現されるかの違いについて説明します。

入り口

destination に関連付けられた入り口を取得するには、フィールド destination.entrances を使用します。

entrance の形式は、Geocoding API v3の入り口の形式と若干異なります。destination.entrances の各入り口には、次のフィールドがあります。

destination に関連付けられたナビゲーション ポイントを取得するには、フィールド destination.navigationPoints を使用します。

navigationPoint の形式は、Geocoding API v3のナビゲーション ポイントの形式と若干異なります。destination.navigationPoints の各ナビゲーション ポイントには、次のフィールドがあります。

  • displayName - ナビゲーション ポイントのわかりやすい 名前（"5th Ave" など）を含む新しいオプション フィールドです。
  • location - LatLng 型の場所です。 Geocoding API v3 で使用される形式とは異なります。
  • travelModes - Geocoding API v3 の ナビゲーション ポイントの restrictedTravelModes フィールドに似ています。列挙型の値は同じですが、このフィールドは制限された移動手段ではなく、ナビゲーション ポイントで許容される移動手段を表すようになりました。
  • usage - ナビゲーション ポイントでサポートされているユースケースを含む新しいフィールドです。ほとんどのナビゲーション ポイントでは UNKNOWN の使用状況になりますが、ナビゲーション ポイントの使用状況が制限されているとは限りません。

建物の輪郭

destination に関連付けられた建物の輪郭を取得するには、建物を表す destination の placeView オブジェクトの displayPolygon フィールドを使用します。placeView ごとに、 placeView.structureType フィールドを使用して建物かどうかを確認できます。構造タイプが BUILDING の場合は、placeView.displayPolygon フィールドから輪郭を取得できます。placeView には、Geocoding API v3 にはなかった建物の追加フィールドもあります。

destination には、次のフィールドに建物を表す placeView オブジェクトを含めることができます。

  • destination.primary - デスティネーションのプライマリ プレイスです。
  • destination.containingPlaces - プライマリ プレイスを「含む」より大きなプレイスを保持できる繰り返しフィールドです。たとえば、プライマリ プレイスが subpremise の場合、containingPlaces には通常、建物を表す placeView が保持されます。
  • destination.subDestinations - プライマリ プレイスの サブデスティネーションを保持できる繰り返しフィールドです。たとえば、建物の個々のアパート・マンションのユニットなどです。通常、このフィールドには建物を表す placeView はありません。

placeView.displayPolygon の形式は、Geocoding API v3 の建物の輪郭 の形式（RFC 7946 形式の GeoJSON 形式）と一致します。

敷地

建物の輪郭と同様に、destination に関連付けられた敷地を取得するには、敷地を表す destination の placeView オブジェクトの displayPolygon フィールドを使用します。placeView ごとに、 フィールドを使用して敷地かどうかを確認できます。placeView.structureType構造タイプが GROUNDS の場合は、placeView.displayPolygon フィールドから輪郭を取得できます。placeView には、Geocoding API v3 にはなかった敷地の追加フィールドもあります。

destination には、次のフィールドに敷地を表す placeView オブジェクトを含めることができます。

  • destination.primary
  • destination.containingPlaces
  • destination.subDestinations

placeView.displayPolygon の形式は、Geocoding API v3 の グラウンディングの輪郭 の形式（RFC 7946 形式の GeoJSON 形式）と一致します。

フィールド マスクを使用してこれらの機能をリクエストする

SearchDestinations メソッドには、返されるフィールドを 選択するで説明されているように、フィールド マスクが必要です。フィールド マスクを * に設定してすべてのフィールドを返すことも、受信する特定のフィールドに設定することもできます。たとえば、次の API リクエストでは、デスティネーションの入り口、ナビゲーション ポイント、建物の輪郭、敷地を取得するために必要なすべてのフィールドを受信するようにフィールド マスクを設定します。

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4/geocode/destinations

セキュリティ上の考慮事項

Geocoding API v4 は、サーバー間 API として設計されています。JavaScript ユーザーが v3 から v4 に直接移行する方法はありません。API キーを使用してクライアントサイド JavaScript（ブラウザなど）から v4 メソッドを直接呼び出すと、API キーが盗難や不正使用のリスクにさらされます。

HTTP リファラ制限は便利ですが、リクエストで Referer ヘッダーを偽装する攻撃者によって簡単に回避される可能性があるため、ウェブサービス エンドポイントを十分に保護することはできません。

Geocoding API v4 を使用するおすすめの方法は、独自のバックエンド サーバーから使用することです。 クライアント アプリケーションは、この仲介サーバーにリクエストを送信します。このサーバーは、保護された API キー（環境変数または Secret Manager に保存されているキーなど）を使用して Google API を安全に呼び出します。これにより、API キーがフロントエンド コードで公開されることはありません。

クライアントサイドのニーズに対応する代替手段

ジオコーディングが必要なクライアントサイドのニーズがある場合は、既存のクライアントサイド ソリューションのいずれかを使用することを検討してください。