您已全部設定完成!

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

啟用 Google Maps Geocoding API

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

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

新正向地理編碼器常見問題

此常見問題涵蓋了網誌文章 Address Geocoding in the Google Maps APIs 中公布的新正向地理編碼器的相關問題。另請參閱為地址進行地理編碼時的最佳做法

針對所有 Google Maps APIs 的共通問題,請參閱 Google Maps APIs 常見問題

開始使用

疑難排解

開始使用

新的正向地理編碼器何時開始成為預設?
  • 對於針對地理編碼服務的 Google Maps Geocoding API 和 Google Maps JavaScript API 要求,新的正向地理編碼器現已是未識別要求與標準方案客戶的預設地理編碼器。針對使用這些 API 的 Premium Plan 客戶,此變更預定於 2017 年 1 月進行。
  • 針對使用 Google Maps Directions API、Google Maps Distance Matrix API、Google Static Maps API、Google Street View Image API 的所有客戶(標準方案與 Premium Plan),以及對於路線規劃、距離矩陣服務的 Google Maps JavaScript API 要求,新的正向地理編碼器預定於 2017 年 1 月 24 日起成為預設。
  • 舊地理編碼器將於 2017 年 3 月底永久淘汰。

若發生意外問題或同時間有其他功能推出,則這些日期可能會延期。如果在新地理編碼器漸次推出前,您有想為系統進行的變更,則您應致力在這些日期前就將變更送入生產階段。

哪些 API 將使用新的正向地理編碼器?

下列 Google Maps APIs 針對以下要求使用相同的地理編碼器:

注意:新的正向地理編碼器不可用於擷取地點 ID 詳細資料。

新的正向地理編碼器開始成為預設前,我該如何使用它?

針對 Geocoding API、Directions API、Distance Matrix API,以及 Maps JavaScript API 中的地理編碼路線規劃距離矩陣服務,您現已可使用新的正向地理編碼器。

針對 Geocoding API、Directions API、Distance Matrix API,請新增選擇性 new_forward_geocoder=true 參數至您的要求。

針對 Google Maps APIs Web 服務用戶端程式庫,請新增 new_forward_geocoder=true 至您的要求來使用新正向地理編碼器。這是最近新增至用戶端程式庫的自訂網址參數。

在 Maps JavaScript API 的地理編碼路線規劃距離矩陣服務中,請在適當的要求物件中設定新的選擇性參數 newForwardGeocoder: true。此參數可於實驗功能版本和發行版本中取得。

Google Maps API Geocoder Tool 已更新選擇性設定。使用此工具時,如果您想根據新的正向地理編碼器功能來產生結果,請選擇「Use the new forward geocoder」。

注意:Static Maps API 和 Street View Image API 尚未提供新的正向地理編碼器。

舊的正向地理編碼器不再是預設後,我該如何使用它?

舊的正向地理編碼器於 2017 年 3 月 29 日永久淘汰前,您可以繼續使用它。

針對 Geocoding API、Directions API、Distance Matrix API,請新增選擇性 new_forward_geocoder=false 參數至您的要求。

針對 Google Maps APIs Web 服務用戶端程式庫,請新增 new_forward_geocoder=false 至您的要求來使用舊正向地理編碼器。這是最近新增至用戶端程式庫的自訂網址參數。

在 Maps JavaScript API 的地理編碼路線規劃距離矩陣服務中,請在適當的要求物件中設定新的選擇性參數 newForwardGeocoder: false。此參數可於實驗功能版本和發行版本中取得。

注意:針對 Static Maps API 和 Street View Image API,目前尚無法使用新的正向地理編碼器,因此不需將此選項設為 false。目前 Static Maps API 和 Street View Image API 將繼續使用舊的正向地理編碼器。

為何進行此變更?

新的正向地理編碼器和消費者 Google Maps 應用程式所使用的地理編碼器相同。舊的地理編碼器將被淘汰。

此變更向下相容嗎?

是,Geocoding API 保留相同的要求、回應格式。新的地理編碼器可能會針對許多查詢產生不同的結果,但要求將繼續以目前格式運作,且新結果將傳回相同的欄位。

疑難排解

使用新的地理編碼器時,我接到更多傳回 ZERO_RESULTS 的查詢。發生什麼事了?

在新地理編碼器中,不明確、不完整、格式錯誤的查詢容易產生 ZERO_RESULTS。這些查詢在舊地理編碼器中通常產生不正確的結果,例如,如果找不到地址,則傳回該郊區。我們認為在這種情況下,傳回 ZERO_RESULTS 實際上是較正確的回應。

如果您的應用程式會處理使用者輸入的地址,那麼 Places API 中的地點自動完成功能應可產生品質更佳的結果。地點自動完成可讓使用者從根據輸入內容產生的結果中進行選擇,讓他們在名稱相近的結果中挑選,如果地址拼錯,也能調整查詢。

如果應用程式會接收來自自動系統的輸入內容、沒有使用者可從自動完成建議中進行選擇,且可能會處理不明確或不完整的查詢,或可能包含非地址元件(例如商家名稱)的查詢,則 Places API 文字搜尋可能是較好的選項。由於不明確查詢中可能包含 Geocoding API 不考慮的商家名稱,因此文字搜尋較有可能會對這類查詢傳回結果。

如果您的應用程式會處理不明確、不完整查詢,或可能包含非地址元件的查詢,建議您使用 Places API,而非 Geocoding API 中的正向地理編碼器。如需詳細資料,請參閱為地址進行地理編碼時的最佳做法 以及 Address Geocoding in the Google Maps APIs 網誌文章

我需要快速回應,但新的地理編碼器對我的應用程式來說太慢了。要使用什麼才能得到更快的回應?

建議需回應使用者輸入內容而無法接受延遲的應用程式使用 Places API 中的地點自動完成功能(也可於 JavaScriptAndroidiOS 取得),而非地址地理編碼。地點自動完成已針對互動式使用最佳化,因此其延遲時間極短。

Geocoding API 中的地址地理編碼已最佳化來搭配完整、明確、格式正確的地址使用(例如輸入到線上表單的收件者地址),因此延遲時間比地點自動完成長。舊正向地理編碼器的情況便是如此。地點自動完成和新正向地理編碼器的延遲時間差異更大,因為新地理編碼器涵蓋範圍更廣、結果品質更佳,但代價是延遲時間較長。

如何縮短 Directions API 和 Distance Matrix API 上的延遲時間?

請使用地點 ID (而非地址)來指定途經地點、起點與目的地。最好從 Places API 中的地點自動完成功能或 Maps JavaScript API 中的 Places 程式庫取得地點 ID。另請參閱 placeIdOnly 選項的資訊,此選項可用來降低地點自動完成的成本。

以地址字串(而非地點 ID 或 latlng)查詢 Directions API 或 Distance Matrix API 時,它們使用和 Geocoding API 相同的後端來在計算路線規劃前,將地址轉換為地點 ID。地點自動完成的速度比地址地理編碼快。針對在無法接受延遲的情況下(例如回應使用者的輸入內容)使用 Directions API 或 Distance Matrix API 的應用程式,建議您使用地點自動完成來取得對應到那些地址的地點 ID,並將地點 ID 傳遞至 Directions API 或 Distance Matrix API。即便是和舊的地址地理編碼器相比,這種方式也能大幅縮短延遲時間。請參閱我們的文件來取得如何搭配路線規劃使用地點自動完成的範例

我是 Premium Plan 客戶,Places API 太貴了。怎麼降低費用?

建議使用 Maps JavaScript API Place autocomplete 小工具。若要降低使用 autocomplete 小工具的費用,請使用新的 placeIdOnly 選項來啟用地點自動完成服務中,地點 ID 的直接存取。針對僅需地址、不需完整商家詳細資訊的應用程式,placeIdOnly 選項會略過地點詳細資料要求。若要取得對應的地址,請將地點 ID 傳遞至地理編碼服務或 Geocoding API。您也可以將地點 ID (而非地址文字字串或緯度/經度組合)傳遞至路線規劃、距離矩陣服務,或 Directions API、Distance Matrix API。

Google Maps API Geocoder Tool地點自動完成與路線規劃範例已更新來示範如何使用新的 placeIdOnly 選項。

如何回報新地理編碼器中的錯誤?

如果您有任何針對新正向地理編碼器服務的錯誤報告功能要求,請使用公開問題追蹤器來讓我們知道。

新的地理編碼器無法針對我的使用案例產生好的結果。有哪些可用的協助?

請使用公開問題追蹤器來讓我們知道,並與我們分享幾個使用新地理編碼器產生較差結果的具體查詢,以利我們研究是否有任何錯誤或系統問題導致結果品質問題,或是否能對最佳做法指南進行任何變更,來幫助開發人員取得更佳的結果。

新地理編碼器中的元件篩選運作方式和舊地理編碼器不同。如何使用新地理編碼器的元件篩選來取得最佳結果?

在新地理編碼器中,僅地址層級的結果完整支援元件篩選。國家/地區代碼(例如 components=country:GB)、郵遞分區的郵遞區號限制、更高層級的結果都僅有部分支援。下列範例示範如何根據您所需的結果,最妥善地利用元件篩選。在範例的要求網址中,請務必將 ‘YOUR_API_KEY’ 取代為您真正的 API 金鑰。

  • 若要將地址(包括建築物、街道)限制在政治區域(國家/地區、郵遞分區等)內,請以和舊地理編碼器相同的方式使用元件篩選。新的地理編碼器支援這種用法。例如:address=gordon&components=locality:dublin 會傳回 "Gordon Way, Dublin, OH 43017, USA"。
    https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&address=gordon&components=locality:dublin&key=YOUR_API_KEY
    
  • 若要將郵遞區號限制在特定國家/地區內,請以和舊地理編碼器相同的方式使用元件篩選,但請務必使用 ISO 3166-2 國家/地區代碼指定國家/地區限制。新的地理編碼器支援這種用法。例如:components=country:CH|postal_code:2000 會傳回 "2000 Neuchâtel, Switzerland"。
    https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&components=country:CH%7Cpostal_code:2000&key=YOUR_API_KEY
    
  • 若要將其他非地址查詢(例如城市或社區)限制在特定國家/地區內,請以和舊地理編碼器相同的方式使用元件篩選,但請務必使用 ISO 3166-2 國家/地區代碼指定國家/地區限制。在新地理編碼器中,已不再保證這會找到和舊地理編碼器相同的結果。請使用地點自動完成來取得限制在所需的國家/地區內的較佳結果。

    範例:

    • 使用舊地理編碼器時,components=country:US%7Clocality:paris 的地理編碼會傳回數個稱為「Paris」的美國城市。
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=false&components=country:US%7Clocality:paris&key=YOUR_API_KEY
      
    • 使用新地理編碼器時,components=country:US%7Clocality:paris 的地理編碼會傳回 "Paris, TX, USA",但不包含美國其他稱為「Paris」的城市。
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&components=country:US%7Clocality:paris&key=YOUR_API_KEY
      
    • 針對 input=paris&components=country:us&types=(regions) 使用地點自動完成,並使用 locationradius 指定檢視點來偏移位置結果,可產生包含數個稱為「Paris」的美國城市的回應。
      https://maps.googleapis.com/maps/api/place/autocomplete/json?location=37.386052,-122.083851&radius=10000&input=paris&components=country:us&types=(regions)&key=YOUR_API_KEY
      
  • 若要將其他非地址查詢(例如城市或社區)限制在特定國家/地區以外的區域內,在新地理編碼器中使用元件篩選不保證會找到和舊地理編碼器相同的結果。請使用地點自動完成來取得偏向指定區域(locationradius)的較佳結果。您也可以使用新的 strictbounds 參數來將結果限制在指定區域內。

    範例:

    • 使用舊地理編碼器時,administrative_area:Anaga|locality:Santa+Cruz 的地理編碼會傳回聖克魯斯-德特內里費的郵遞分區,以及阿那加的行政區域。
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=false&components=administrative_area:Anaga%7Clocality:Santa%20Cruz&key=YOUR_API_KEY
      
    • 使用新地理編碼器時,administrative_area:Anaga|locality:Santa+Cruz 的地理編碼僅會傳回阿那加的行政區域,而非所需的聖克魯斯-德特內里費的郵遞分區。
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&components=administrative_area:Anaga%7Clocality:Santa%20Cruz&key=YOUR_API_KEY
      
    • 針對 input=santa+cruz&location=28.494168,-16.275751&radius=20000&types=geocode 使用地點自動完成,首先會傳回 "Santa Cruz de Tenerife, Spain",以及其他城市如 "Santa Cruz de La Palma" (在不同島上)和 "Santa Cruz, CA, United States"。
      https://maps.googleapis.com/maps/api/place/autocomplete/json?input=santa+cruz&location=28.494168,-16.275751&radius=20000&types=geocode&key=YOUR_API_KEY
      
    • 請新增 strictbounds 到上述地點自動完成要求,以傳回限制在指定區域(「Anaga」)內的結果。
      https://maps.googleapis.com/maps/api/place/autocomplete/json?input=santa+cruz&location=28.494168,-16.275751&radius=20000&types=geocode&strictbounds&key=YOUR_API_KEY
      

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

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