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.* 參數會合併為一個地址,且不會篩選結果;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。
  • 問題:與 v3 和其他 v4 方法不同,SearchDestinations 傳回的結果可能沒有精確的主要地址。修正方式:如果只需要精確的主要地址結果,請將 placeFilter.addressability 設為 PRIMARY。請參閱 /maps/documentation/geocoding/geocoding-v4-migrate。
  • 問題:為 Geocoding API v3 編寫的程式碼在 v4 REST 回應中會中斷:v4 使用 lowerCamelCase 欄位名稱 (addressComponents,而非 address_components)、移除 status 和 error_message,並從 GeocodePlace 傳回單一根物件,而非 results 陣列。修正方式:檢查 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 的用途

請參閱下方連結的各項工作指南,或在功能探索工具中比較各項產品。