您已全部設定完成!

若要開始開發,請參閱我們的開發人員文件

啟用 Google Maps Geocoding API

為協助您開始,我們將先引導您使用 Google Developers Console 來執行一些動作:

  1. 建立或選擇專案
  2. 啟用 Google Maps Geocoding API
  3. 建立適當的金鑰
繼續

為地址進行地理編碼時的最佳做法

地理編碼是將地址(例如街道地址)轉換為地理座標(緯度與經度)的程序,您可以用來在地圖上放置標記或定位地圖。此文件主要說明為地址進行地理編碼時的注意事項。本文將介紹使用 Google Maps Geocoding API 的最佳時機,以及何時使用 Places API 地點自動完成服務或 Places API 文字搜尋服務會最有幫助。

一般而言,為完整地址(例如「48 Pirrama Rd, Pyrmont, NSW, Australia」)進行地理編碼時,請使用 Google Maps Geocoding API。為模糊(不完整)地址進行地理編碼,或因應高延遲狀況(例如回應使用者輸入的內容時)時,請使用 Places API 地點自動完成服務。在自動系統中為模糊地址進行地理編碼,沒有使用者來在自動完成建議中進行選擇時,請使用 Places API 文字搜尋服務 而非地點自動完成。

使用案例與 API 建議

使用案例 API 建議
完整郵政地址 Google Maps Geocoding API Web 服務
使用者輸入的模糊查詢 (例如不完整或格式不正確的地址) 請使用 Places API 地點自動完成服務來取得地點 ID,然後使用 Geocoding API 來將地點 ID 地理編碼為 Latlng。
自動系統中的模糊查詢 (例如不完整或格式不正確的地址) 請使用 Places API 文字搜尋服務來取得地點 ID,然後使用 Geocoding API 來將地點 ID 地理編碼為 Latlng。
即時回應使用者輸入的內容 請使用 Places API 地點自動完成服務來取得地點 ID,然後使用 Geocoding API 來將地點 ID 地理編碼為 Latlng。
使用 Google Maps Directions API 或 Distance Matrix API,將起點、目的地或途經地點指定為地址字串時的延遲問題 請使用 Places API 地點自動完成服務來取得地點 ID,然後將地點 ID 傳遞至 Directions API 或 Distance Matrix API 來縮短地理編碼延遲時間。

完整地址

處理完整郵政地址字串(例如「48 Pirrama Rd, Pyrmont, NSW, Australia」)這類明確查詢的最佳方式是使用 Geocoding API Web 服務。地址地理編碼後端提供的全球地址涵蓋範圍更廣,能為這類完整、明確查詢提供高品質的結果。

模糊查詢

模糊查詢包含格式不正確、不完整的地址或多餘的地址組成部分。Geocoding API Web 服務地理編碼器並非是設計來處理模糊查詢的,在回應模糊查詢時可能產生較不準確的結果或甚至無結果,特別是當查詢中包含數個錯字或非地址字詞時。

若使用者可能輸入模糊查詢(例如「123 Main Street」),建議您使用 Places API 中的地點自動完成服務,此服務是設計來傳回多個可能選項,並讓使用者從中挑選。您可限制 Places API 僅搜尋地理編碼或地址而排除商家。此外,您可設定自動完成查詢功能,使其傳回特定於某位置的結果。Places API 傳回的地點 ID 可作為完整、明確的位置傳遞給 Geocoding API Web 服務,接著再傳回完整地址詳情並將地址地理編碼為 Latlng。了解更多關於 AndroidiOSJavaScript 上的地點自動完成服務與 Places API Web Service 的相關資訊。

如果您需要在自動系統中使用地址地理編碼,查詢可能模糊或不完整,但沒有使用者可從數個可能結果中進行選擇,請使用 Places API 文字搜尋服務 而非地點自動完成服務。相較於 Geocoding API,地點搜尋較適合處理模糊查詢,可讓您將搜尋範圍限制在特定區域,或按照距離排序結果,在模糊不完整的查詢得到的結果中進行更精確的篩選及排序。

回應使用者輸入內容

即時回應使用者輸入內容的應用程式有兩大考量,影響 API 的選擇:

  1. 使用者輸入地址速度通常較慢,因此若能為模糊不完整地址進行地理編碼,將有助於使用者較快取得結果。
  2. 回應使用者輸入內容的應用程式無法接受延遲。

這兩大考量令 Places API 中的地點自動完成服務成為回應使用者輸入內容的理想解決方案。Geocoding API 中的地址地理編碼延遲時間較長,對於模糊不完整查詢也會產生較不正確的結果,因此不建議用於需要即時回應使用者輸入內容的應用程式。了解更多關於 AndroidiOSJavaScript 上的地點自動完成服務與 Places API Web Service 的相關資訊。

縮短 Directions API 與 Distance Matrix API 延遲時間

指定起點、目的地或途經地點為地址字串時,Google Maps Directions API Distance Matrix API 使用的後端與 Geocoding API 相同,將地址進行地理編碼後再計算出路線。比起使用 Latlng 或地點 ID 指定相同位置,這會大幅增加延遲時間。

若應用程式在無法接受延遲的情況下(例如回應使用者輸入內容)使用 Directions API 或 Distance Matrix API,而起點、目的地或途經地點已指定為地址字串,建議您使用 Places API 的地點自動完成服務來將地址字串轉換為地點 ID,再將地點 ID 傳遞給 Directions API 或 Distance Matrix API 來將延遲時間縮至最短。了解更多關於 AndroidiOSJavaScript 上的地點自動完成服務與 Places API Web Service 的相關資訊。另請參考 JavaScript 地點自動完成及路線規劃範例

結論

取決於使用案例,為地址進行地理編碼時,請使用 Geocoding API 或 Places API;使用地點自動完成服務或地點搜尋服務搭配 Geocoding API 可打造能為使用者提供準確地理編碼結果,同時縮短延遲時間的應用程式。

管理錯誤及重試

若您收到 UNKNOWN_ERROR 回應,這是由暫時性錯誤所導致的,最好是稍候片刻再重試。建議您使用 Google Maps APIs Web 服務用戶端程式庫,其中包含了重試邏輯並支援 Google Maps APIs Premium Plan 驗證。Google Maps Services 的 Java ClientPython ClientGo 用戶端Node.js 用戶端 為社群支援的用戶端程式庫,可於 GitHub 上下載或做出進一步貢獻,同時您亦可找到安裝指南及範例程式碼。

若您收到 OVER_QUERY_LIMIT 狀態碼,代表您已超過 API 使用量限制。建議您嘗試這些使用量最佳化策略

傳送您對下列選項的寶貴意見...

這個網頁
Google Maps Geocoding API
Google Maps Geocoding API
需要協助嗎?請前往我們的支援網頁