地理編碼是指將地址 (例如街道地址) 轉換為地理座標 (經緯度) 的程序，可用於在地圖上放置標記或定位地圖。本文旨在說明將地址進行地理編碼時的注意事項。說明何時最適合使用 Geocoding API，以及何時適合使用 Places API Place Autocomplete 服務。
一般來說，如要為完整地址 (例如「48 Pirrama Rd, Pyrmont, NSW, Australia」) 進行地理編碼，請使用 Geocoding API。如要對模糊 (不完整) 地址進行地理編碼，或用於對延遲時間敏感的應用程式 (例如回應使用者輸入內容)，請使用 Places API Place Autocomplete 服務。
用途和 API 建議
| 用途和 API 建議 | |
|---|---|
| 實際抵達、進階目的地選擇、最後一哩路、共乘接送、建築物入口或校園導航 | 使用 Geocoding API v4 的「搜尋目的地」(SearchDestinations) 方法，擷取建築物入口、可規劃路線的導航點、建築物輪廓和附近地標。請參閱「選擇地理編碼方法」。 |
| 即時回應使用者輸入內容 (包括使用者輸入的地址不完整、格式不正確、拼字錯誤或難以確定) | 使用 Places API Place Autocomplete 服務取得地點 ID，然後呼叫 SearchDestinations (取得超地方詳細資料) 或 GeocodePlace (取得基本座標)。 |
| 自動化系統處理完整、明確的郵寄地址 (例如「48 Pirrama Rd, Pyrmont, NSW, Australia」) | 使用 Geocoding API v4 Web 服務 (SearchDestinations 取得超地方詳細資料，或 GeocodeAddress 查詢座標)。 |
| 自動化系統處理模糊查詢 (例如不完整、格式不佳或拼寫錯誤的地址) | 建議自動化系統使用 Geocoding API 網路服務。不過，如果自動化系統中，使用者輸入的查詢有很高比例模糊不清、不完整或拼寫錯誤，則可加入互動式 Place Autocomplete 小工具，讓使用者選取結果，避免拼錯地址。 |
| 使用 Directions API (舊版) 或 Distance Matrix API (舊版) 時，如果起點、目的地或路線控點指定為地址字串，會發生延遲問題 | 使用 Places API Place Autocomplete 服務取得地點 ID，然後將地點 ID 傳遞至 Directions API (舊版) 或 Distance Matrix API (舊版)，即可縮短地理編碼延遲時間。 |
回應使用者輸入內容
即時回應使用者輸入內容的應用程式，有兩項主要考量會影響 API 的選擇：
- 使用者輸入內容通常涉及逐步輸入地址 (例如「123 Main Street」)，因此能夠對不完整、模糊的地址進行地理編碼，有助於使用者更快取得結果。
- 回應使用者輸入內容的應用程式對延遲時間高度敏感。
基於這兩項考量， Places API 中的 Place Autocomplete 服務非常適合用於回應使用者輸入內容。Place Autocomplete 旨在傳回多個可能選項，供使用者選擇。Places API 可限制為僅搜尋地理編碼或地址，並排除商家。此外，您也可以調整自動完成查詢函式，傳回特定位置的結果。Places API 會傳回地點 ID，可做為完全明確的位置傳遞至 Geocoding API Web 服務，後者會傳回完整的地址詳細資料，並將地址地理編碼為經緯度。地點 ID 也可以傳遞至其他 API，例如 Directions API (舊版) 和 Distance Matrix API (舊版) (請參閱「縮短延遲時間」)。
Geocoding API 的地址地理編碼延遲時間較長，且如果查詢不完整或模稜兩可，產生的結果也較不準確，因此不建議用於必須即時回應使用者輸入內容的應用程式。
進一步瞭解 Android、iOS、JavaScript 和 Places API 的 Place Autocomplete 服務。
自動化系統
自動化系統處理完整、明確的郵寄地址：明確的查詢 (例如完整郵寄地址字串，像是「48 Pirrama Rd, Pyrmont, NSW, Australia」)，最適合由 Geocoding API Web 服務處理。地址地理編碼後端提供更廣泛的全球地址涵蓋範圍，並經過最佳化，可為這類完整、明確的查詢提供高品質結果。
自動化系統處理模糊查詢：模糊查詢是指含有格式不正確、不完整或拼寫錯誤地址的查詢。如果是自動化系統，建議使用 Geocoding API 網路服務。不過，Geocoding API 並非設計用來處理模稜兩可的查詢，因此可能會產生不夠準確的結果，或不傳回任何結果。如果自動化系統處理使用者輸入內容時，產生大量模稜兩可的查詢，建議您使用 Places API 中的 Place Autocomplete 服務，在應用程式中加入互動元素，因為這項服務可傳回多個可能選項，供使用者選擇。Places API 會傳回地點 ID，可做為完全明確的位置傳遞至 Geocoding API Web 服務，後者會傳回完整的地址詳細資料，並將地址地理編碼為經緯度。進一步瞭解 Android、iOS、JavaScript 和 Places API 的 Place Autocomplete 服務。
縮短 Directions API (舊版) 和 Distance Matrix API (舊版) 的延遲時間
如果起點、目的地或路線控點是以地址字串指定，Directions API (舊版) 和 Distance Matrix API (舊版) 會使用與 Geocoding API 相同的後端，先對這些地址進行地理編碼，再計算路線。與指定經緯度或地點 ID 的相同地點相比，這會大幅增加延遲時間。
如果您的應用程式在對延遲時間敏感的情況下 (例如回應使用者輸入內容) 使用 Directions API (舊版) 或 Distance Matrix API (舊版)，且起點、目的地或路線控點一開始是以地址字串指定，建議您使用 Places API 的 Place Autocomplete 服務，將地址字串轉換為地點 ID，然後將地點 ID 傳遞至 Directions API (舊版) 或 Distance Matrix API (舊版)，盡可能縮短延遲時間。進一步瞭解 Android、iOS、JavaScript 和 Places API 的 Place Autocomplete 服務。另請參閱 Place Autocomplete 和路線規劃的 JavaScript 範例。
結論
視用途而定，您可以單獨使用 Geocoding API，也可以搭配 Place Autocomplete 服務。這樣一來，您就能建構提供準確地理編碼結果，且延遲時間較短的應用程式。
管理錯誤和重試
如果收到 UNKNOWN_ERROR 回應，表示發生暫時性錯誤，建議稍候片刻再重試。建議您使用 Google 地圖平台網路服務
用戶端程式庫，其中包含重試邏輯，並支援 Google 地圖平台付費方案驗證。Google 地圖服務適用的 Java 用戶端、Python 用戶端、Go 用戶端和 Node.js 用戶端都是社群支援的用戶端程式庫，可供下載並在 GitHub 上提供貢獻，您也可以在 GitHub 上找到安裝操作說明和程式碼範例。
如果收到 OVER_QUERY_LIMIT 狀態碼回應，表示您已超過 API 的用量限制。建議您嘗試這些
用量最佳化策略。