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:相關產品
Geocoding API:常見錯誤
- 問題:
SearchDestinations要求若未提供欄位遮罩,會失敗並傳回錯誤;與GeocodeAddress、GeocodeLocation和GeocodePlace不同,欄位遮罩為必要。修正方式:在每個SearchDestinations要求中設定X-Goog-FieldMask標頭或$fields參數。請參閱 /maps/documentation/geocoding/choose-fields。 - 問題:v4
GeocodeAddress沒有硬性元件篩選器 (v3components=country:US)。結構化address.*參數會合併為一個地址,且不會篩選結果;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。 - 問題:與 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 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 地點 ID 的建築物輪廓經緯度座標。
- 傳回地址建築物入口的經緯度座標。
- 針對一組經緯度座標,傳回建築物入口的經緯度座標。
- 傳回 Google 地點 ID 的建築物入口經緯度座標。