Geocoding API は、住所を座標とプレイス ID に変換したり、座標やプレイス ID を住所に変換したりするウェブサービスです。v4 の SearchDestinations メソッドでは、建物の入り口、ナビゲーション ポイント、建物や敷地の輪郭、近くのランドマークなど、目的地に関する詳細情報も返されます。
Geocoding API: 重要なポイント
- プロダクト: Geocoding API
- カテゴリ: 場所
- プラットフォーム: ウェブサービス(REST)
- 実行場所: サーバー(バックエンド コード)
- リリース ステージ: GA
- ライフサイクル: 有効
- 概要: Geocoding API の概要
Geocoding API: 使用するタイミング
Geocoding API を使用する場合:
- バックエンド サーバーで、番地を緯度 / 経度の座標とプレイス ID に変換する必要があります。
- GPS 座標または既知のプレイス ID の表示アドレスまたは行政区域(市区町村、郵便番号)が必要です。
- ドライバーや配達員を目的地に案内するには、建物の入り口、ルート設定可能なナビゲーション ポイント、建物や敷地の輪郭が必要です。
- 大規模な複合施設(空港、ショッピング モール、キャンパス)内の目的地を、サブ目的地または近くのランドマークに解決する必要がある。
Geocoding API を使用すべきでない場合:
- クライアントサイドのブラウザ JavaScript からのジオコーディングが必要な場合。公開された API キーを使用して v4 を呼び出すと、セキュリティ上のリスクが生じます。代わりに Maps JavaScript API を使用してください。
- ジオコーディングされた目的地までのルートまたは到着予定時刻を計算する必要がある。代わりに Routes API を使用してください。
- Android アプリでナビゲーション ポイント トークンへのターンバイターン方式のルート案内が必要な場合は、代わりに Navigation SDK for Android を使用してください。
- iOS アプリでナビゲーション ポイント トークンへのターンバイターン方式のルート案内が必要な場合は、代わりに Navigation SDK for iOS を使用してください。
Geocoding API: 設定
- 有効にするサービス:
geocoding-backend.googleapis.com - 認証: API キー、OAuth 2.0、サービス アカウント
- 使ってみる: Geocoding API を設定する
- リファレンス: Geocoding API リファレンス
- 料金: Geocoding API の使用量と請求額
- ポリシー: Geocoding API のポリシー
- リリースノート: Geocoding API のリリースノート
Geocoding API: 関連プロダクト
- よく併用される API: Routes API、Navigation SDK for Android、Navigation SDK for iOS
Geocoding API: よくある間違い
- 問題: フィールド マスクのない
SearchDestinationsリクエストはエラーで失敗します。GeocodeAddress、GeocodeLocation、GeocodePlaceとは異なり、フィールド マスクは必須です。修正: すべてのSearchDestinationsリクエストにX-Goog-FieldMaskヘッダーまたは$fieldsパラメータを設定します。/maps/documentation/geocoding/choose-fields をご覧ください。 - 問題: v4 の
GeocodeAddressには、ハード コンポーネント フィルタ(v3 のcomponents=country:US)がありません。構造化されたaddress.*パラメータは 1 つのアドレスに結合され、結果をフィルタしません。また、regionCodeには v4 のデフォルトがありません(v3 のデフォルトはus)。 修正: クライアントサイドでresultsをフィルタします。大文字のregionCodeをpostalAddress.regionCodeに一致させ、大文字の 2 文字の管理エリアをpostalAddress.administrativeAreaとadministrative_area_level_naddressComponents(shortText)に一致させます。入力とpostalAddress.postalCodeの両方を正規化します(スペースやハイフンを削除し、地域ルールを適用します)。/maps/documentation/geocoding/geocoding-v4-migrate をご覧ください。 - 問題: ブラウザの JavaScript から Geocoding API v4 を直接呼び出すと、API キーが公開されます。HTTP リファラーの制限は、
Refererヘッダーを偽造することで回避できます。修正方法: 保護されたキーを使用して独自のバックエンドから v4 を呼び出すか、クライアントサイドのニーズに Maps JavaScript API Geocoding Service(v3 バックエンド)を使用します。/maps/documentation/geocoding/geocoding-v4-migrate をご覧ください。 - 問題:
SearchDestinationsは、v3 や他の v4 メソッドとは異なり、正確なプライマリ アドレスを持たない結果を返すことがあります。修正方法: 正確なプライマリ アドレスを含む結果のみが必要な場合は、placeFilter.addressabilityをPRIMARYに設定します。/maps/documentation/geocoding/geocoding-v4-migrate をご覧ください。 - 問題: Geocoding API v3 用に作成されたコードが v4 REST レスポンスで機能しなくなります。v4 では、フィールド名に lowerCamelCase(
address_componentsではなくaddressComponents)が使用され、statusとerror_messageが削除され、results配列ではなくGeocodePlaceから単一のルート オブジェクトが返されます。修正: v4 REST 呼び出しの HTTP ステータス コードとエラー本文を確認し、lowerCamelCase フィールド(addressComponents、postalAddress)を読み取ります。gRPC レスポンスでは引き続きスネークケースが使用されます。/maps/documentation/geocoding/geocoding-v4-migrate をご覧ください。
Geocoding API: 以前の機能と非推奨の機能
- Geocoding API v3 の地域密着型データ(
extra_computations:BUILDING_AND_ENTRANCES、NAVIGATION_POINTS、GROUNDS、レスポンス フィールドbuildings.entrances、navigation_points、buildings.building_outlines、grounds): 2025 年 8 月 13 日より非推奨。代替: Geocoding API v4SearchDestinationsメソッド(POST /v4/geocode/destinations)。移行ガイドをご覧ください。
Geocoding API でできること
各タスクについては、以下のリンク先のガイドをご覧ください。また、機能エクスプローラでプロダクトを比較することもできます。
- 住所の緯度と経度の座標を返す(ジオコーディング)。
- 緯度と経度の座標セットに対応する住所を返す(リバース ジオコーディング)。
- ジオコーディング リクエストを制限して、特定のビューポート内の結果を返すようにします。注: Geocoding API v4 では、locationBias は結果を厳密に制限するのではなく、指定されたビューポートに優先的に表示します。
- ジオコーディング リクエストまたはリバース ジオコーディング リクエストを制限して、特定の地域、国、郵便番号内の結果のみを返すようにします。注: Geocoding API v4 では、regionCode は結果を厳密に制限するのではなく、指定された CLDR リージョンに偏らせます。国または郵便番号による従来の v3 コンポーネント フィルタリングについては、https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding#ComponentFiltering をご覧ください。
- リバース ジオコーディング リクエストを制限して、指定した住所タイプの結果のみを返すようにします。注: Geocoding API v4 では、types パラメータは、基盤となる検索を制限するのではなく、検索後に返されたリバース ジオコーディングの結果を住所タイプでフィルタします。
- 住所のランドマークやエリアへの近接性に関する情報を返します。
- 一連の緯度と経度の座標について、ランドマークやエリアへの近接性に関する情報を返します。
- Google の場所 ID のランドマークやエリアへの近接性に関する情報を返します。
- Google プレイス ID の住所を返します。
- 住所の建物の輪郭の緯度と経度の座標を返します。
- 一連の緯度と経度の座標について、建物の輪郭の緯度と経度の座標を返します。
- Google Place 識別子に対応する建物の輪郭の緯度と経度の座標を返します。
- 住所の建物の入り口の緯度と経度の座標を返します。
- 一連の緯度と経度の座標について、建物の入り口の緯度と経度の座標を返します。
- Google プレイス ID の建物の入り口の緯度と経度の座標を返します。