Geocoding API クイック リファレンス

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 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_n addressComponents(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 v4 SearchDestinations メソッド(POST /v4/geocode/destinations)。移行ガイドをご覧ください。

Geocoding API でできること

各タスクについては、以下のリンク先のガイドをご覧ください。また、機能エクスプローラでプロダクトを比較することもできます。