提高地理編碼準確度

歐洲經濟區 (EEA) 開發人員

GeocodeAddress 和 SearchDestinations 方法支援選用的 effort 參數，可讓您在回應延遲時間和地址解析準確度之間取得平衡。

雖然標準地理編碼能以不到一秒的延遲時間處理格式正確的郵寄地址，但實際輸入的地址往往不完整、不正式或複雜 (例如 "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West, Mumbai" 或 "where the warriors play, sf")。設定較高的 effort 層級，即可指示 Geocoding API 套用延伸推論和消除歧義，解析難以處理的地址。

努力程度

為 effort 參數指定下列其中一個值：

努力程度 說明 一般延遲時間 建議用途
EFFORT_UNSPECIFIED 預設值。運作方式與 LOW 努力程度相同。 不到一秒 預設標準地理編碼。
LOW 以最快的回應時間為目標。不會對難以辨識的地址執行擴充搜尋或消除歧義。 Sub-second 即時互動式查詢，大量標準地址驗證。
MEDIUM 兼顧速度與準確度。大多數要求都會以標準低延遲時間傳回。如果地址不明確或難以辨識，服務會進行額外處理來提高準確度，這可能需要幾秒鐘的時間。 標準地址不到一秒；模糊地址最多幾秒 (≤ 4 秒) 互動式使用者工作流程 (例如結帳時確認地址)，使用者可接受短暫暫停。
HIGH 針對不完整、非正式或複雜的地址，盡可能提高地址解析準確度。回覆時間可能會大幅延長。 複雜地址最多 20 秒 背景程序、大量地址定位、物流調度，或結帳後非同步地址修正。

要求範例

搜尋目的地 (SearchDestinations)

在向 https://geocode.googleapis.com/v4alpha/geocode/destinations 發出的 POST 要求 JSON 要求主體中，加入 effort 欄位。effort 參數主要會影響 addressQuery 解析度：

curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West, Mumbai"
  },
  "effort": "HIGH"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations

為地址進行地理編碼 (GeocodeAddress)

在向 /v4alpha/ 端點發出的 GET 要求中，將 effort 參數做為網址查詢參數傳遞：

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4alpha/geocode/address/where+the+warriors+play,+sf?effort=MEDIUM"

降低延遲時間影響

在應用程式中使用 MEDIUM 或 HIGH 工作時，傳送單次要求是最簡單的整合方式，但這些模式的要求可能會導致延遲時間較長，進而延遲同步、面向使用者和對延遲時間敏感的工作流程。

如要減輕延遲時間對互動式使用者流程 (例如結帳或預訂) 的影響，可以使用多階段工作流程：

  1. 第 1 階段 (互動式)：使用 effort=LOW (或預設) 傳送同步要求，立即驗證地址，延遲時間不到一秒。
  2. 第 2 階段 (背景)：使用 effort=MEDIUM 或 effort=HIGH 傳送非同步後續要求 (例如結帳後或出貨前)，將複雜地址解析為高精確度座標、入口和導航點，不影響使用者操作。

用量限制

在實驗 (v4alpha) 發布階段，effort 設為 MEDIUM 或 HIGH 的要求，頻率限制會比標準 (LOW) 要求更嚴格。如果應用程式超過這些頻率限制，API 會傳回 RESOURCE_EXHAUSTED (HTTP 429) 錯誤。如果遇到 HTTP 429 錯誤，或需要提高配額，請透過意見回饋管道與我們聯絡。

意見回饋

這是 Geocoding API 的實驗功能。歡迎透過 geocoding-feedback-channel@google.com 提供意見。