Geocoding v3 から v4 に移行する

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

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

既存の API キーは、新しい v4 エンドポイントで使用できます。ただし、API の v3 で割り当ての引き上げをリクエストした場合は、新しい v4 API で引き上げをリクエストする必要があります。JavaScript ユーザー向けの移行パスはありません。

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 では 1 より大きい値が必要です）。
results.partial_match 削除済み
新機能 results.addressComponents.languageCode 特定の住所コンポーネントの言語。
新機能 results.bounds high/low を使用した明示的な境界。
新機能 results.place プレイスのリソース名。
新機能 results.postalAddress 構造化された PostalAddress オブジェクト。

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 Place Geocoding から移行する

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

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

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

v3 パラメータ v4 パラメータ メモ
place_id リクエスト proto の place フィールド プレイス ID は、パス パラメータ places/{place}（例: https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw）として提供されるようになりました。これは、基盤となるリクエストの場所フィールドにマッピングされます。
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 では 1 より大きい値が必要です）。
新機能 addressComponents.languageCode 特定の住所コンポーネントの言語。
新機能 bounds high/low を使用した明示的な境界。
新機能 place プレイスのリソース名。
新機能 postalAddress 構造化された PostalAddress オブジェクト。

Geocoding Hyperlocal Data から Destinations への移行

Geocoding API v3 の次の機能は、Geocoding API v4 の SearchDestinations エンドポイントに置き換えられます。

  • 閲覧開始数
  • ナビゲーション ポイント
  • 建物の輪郭
  • 邸宅と庭園

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

閲覧開始数

destination に関連付けられているエントランスを取得するには、フィールド destination.entrances を使用します。

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

  • displayName - これは新しいオプション フィールドで、入り口の人間が読める名前（例: 「Gate B」）が含まれます。
  • location - LatLng タイプの位置情報です。Geocoding API v3 で使用される形式とは異なります。
  • tags - Geocoding API v3 のエントランスの tags フィールドと同じです。
  • place - Geocoding API v3 のエントランスの buildingPlaceId フィールドに類似しています。ただし、このフィールドのプレイス ID は、建物だけでなく、あらゆるタイプのプレイスの ID になる可能性があります。

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 の形式は、RFC 7946 形式を使用した GeoJSON 形式である Geocoding API v3 の建物の輪郭形式と一致します。

邸宅と庭園

建物の輪郭の作成と同様に、destination に関連付けられたグラウンドを取得するには、グラウンドを表す destination 内の placeView オブジェクトの displayPolygon フィールドを使用する必要があります。各 placeView について、placeView.structureType フィールドで根拠かどうかを確認できます。構造体の型が GROUNDS の場合、placeView.displayPolygon フィールドからアウトラインを取得できます。また、placeView には、Geocoding API v3 になかった理由を示す追加フィールドも含まれます。

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

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

placeView.displayPolygon の形式は、RFC 7946 形式を使用した GeoJSON 形式である Geocoding API v3 のグラウンド アウトライン形式と一致します。

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

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/v4alpha/geocode/destinations