建構驗證邏輯

本文件說明建構地址檢查系統的程序,以便處理 Address Validation API 的各種回應。這篇文章將說明如何建立邏輯,正確使用回應,調查 API 中的其他信號,以及何時及如何向客戶索取更多資訊。

一般來說,API 回應會決定系統應以下列方式處理地址:

  • 修正:地址品質不佳。 您應該會要求提供更多資訊。
  • 確認:地址品質良好,但與輸入的地址有所不同。您可能會收到確認提示。
  • 接受:地址品質良好。你可以接受提供的地址。

金鑰用途

這份文件可協助您修改系統,以便最佳化 API 回應分析,並決定要針對提供的地址採取哪些後續行動。以下是可能的流程,以擬似程式碼呈現。

if (the API response indicates significant problems in the address)
    FIX - prompt the user to fix the address
else if (the API response indicates less significant problems in the address)
    CONFIRM - confirm with the user that the address is correct
else
    ACCEPT - continue with the address returned by the API.

具體邏輯取決於您的情況。詳情請參閱實作指南。您也可以使用我們提供的開放原始碼實作邏輯,該邏輯位於 Extended Component Library 中。

工作流程總覽

下表概要說明系統的兩項動作:

  1. 根據修正、確認和接受行為,要使用的 workflow
  2. 第一個信號會檢查回應中的。這裡所述的信號來自 verdict 屬性,並非唯一要檢查的信號,但可提供地址品質的初始指標。每個行為類型都對應至本文件的某個部分,說明您可能還需要調查的其他信號。
系統行為
修正地址

verdict 的回應會指出缺少的重要資訊,您應提供這些資訊。Address Validation API 傳回的地址可能無法送達。

工作流程

  1. 視需要調查地址元件。
  2. 提示客戶修正地址問題。
  3. 要求驗證更新後的地址。
  4. (選用) 將要求傳送至 API 的意見回饋端點。請參閱「處理更新的地址」。
  5. 繼續輸入地址。

判定結果信號

下列任一情況

確認地址

verdict 的回應會指出可送達的地址,但會對原始輸入內容進行變更:推測已修正拼字錯誤的資料,或可確認的資料。

工作流程

  1. 需要修正的內容:
    1. 視需要調查地址元件。
    2. 要求驗證更新後的地址。
    3. (選用) 將要求傳送至 API 的意見回饋端點。請參閱「處理更新的地址」。
    4. 繼續輸入地址。
  2. 不需要修正:
    1. (選用) 將要求傳送至 API 的意見回饋端點。請參閱「處理更新的地址」。
    2. 繼續輸入地址。

判定結果信號

必須符合下列所有條件:

  • validationGranularity 包含 ROUTE 或更高版本。請參閱精細程度值。
  • addressCompletetrue
  • hasInferredComponents 欄位為 true,或 hasReplacedComponents 欄位為 true
接受地址

Address Validation API 回應表示地址品質極佳。

工作流程

繼續使用退回地址。

判定結果信號

必須符合下列所有條件:

  • validationGranularity 包含 PREMISE 或更高版本。請參閱精細度值。
  • addressCompletetrue
  • 沒有推斷或替換的元件。

實作指南

設計系統如何回應 Address Validation API 的信號時,您可以參考下列建議,建立更有效的回應模型。不過,這些都只是建議,因此請務必根據您的業務模式進行導入。

指引 詳細資料
風險等級

在要求使用者修正與接受輸入的地址之間取得平衡時,請考量您情況的容許程度。

Address Validation API 會傳回各種信號,您可以將這些信號與風險等級結合,以最佳化驗證程序。

舉例來說,如果地址有未經確認的街道號碼,您仍可接受該地址。另一方面,如果您的業務運作需要更精確的地址,您可以向使用者提出提示。如需任一類別的示例,請參閱「接受地址 - 示例」中的「非美國未經確認的街道號碼」

接受地址

如果客戶沒有回應提示,建議您讓系統接受原始輸入內容。

在這種情況下,客戶可能輸入的地址不在系統中,例如新建建築物。

提供意見回饋

重新提出地址驗證要求時,您也可以將要求傳送至 provideValidationFeedback 端點。

這樣一來,Google 就能瞭解你最終如何處理最終回應。 請參閱「處理更新的地址」。

修正地址

如果結果明確指出地址無法送達,請修正該地址。系統接著可提示消費者提供必要資訊,之後您就能重新發出工作流程,取得可送達的地址。

修正信號

Address Validation API 會提供多種信號,讓您知道是否應修正地址。

1. 驗證精細程度和缺少的元件

以下兩種信號最能指出有問題的地址:

  • 每當 validationGranularity 欄位為 OTHER 時,系統應調查地址元件信號,進一步瞭解錯誤發生的位置和修正方式。
  • 每當經過後置處理的 address 物件傳回 missingComponentTypes 欄位時,系統就應檢查該元件。缺少的元件也會導致地址不完整,無法送達。

2. 其他指標

Address Validation API 也會提供其他信號,協助診斷特定問題:

可疑元件 如果元件的確認層級為UNCOMFIRMED_AND_SUSPICIOUS,表示元件可能有誤。
未解析的元件 unresolvedToken 是輸入內容的一部分,系統無法將其視為地址的有效部分。

3. 美國地址信號

某些僅適用於美國地址的欄位可提供實用的信號,指出地址無法送達,因此應予以修正。對於需要修正的地址,你應該會看到以下畫面:

dpvConfirmation ND 或空白。

如要進一步瞭解 dpvConfirmation,請參閱「處理美國地址」。

修正地址範例

確認地址

當判定結果指出 Address Validation API 已推斷或變更地址元件,以產生已驗證的地址時,您便可確認該地址。在這種情況下,您有可送達的地址,但希望更確信產生的地址是客戶想要的地址。

為了向客戶提供正確的提示,您的邏輯會識別服務標示的元件,以便判斷 API 會將哪些動作或標記套用至元件,例如 inferredreplacedspellCorrected。請參閱參考資料中的 AddressComponent

確認信號

Address Validation API 會提供多種信號,讓您知道是否應確認地址。

1. 驗證精細程度

validationGranularityROUTE 以上即可,但 PREMISE 或 SUBPREMISE 可提供更強的信號,表示可順利放送。

2. 其他指標

在決定是否要與客戶確認地址輸入內容時,判定結果也會提供下列資訊,以便判斷要調查哪些元件:

推論資料 如果 hasInferredComponents 欄位為 true,表示 API 已填入從其他地址元件中擷取的資訊。
已取代的資料 如果 hasReplacedComponents 欄位為 true,API 會將輸入的資料替換為系統認為可讓地址有效的資料。

3. 美國地址信號

某些僅適用於美國地址的欄位表示您的邏輯應與客戶確認詳細資料。符合下列任一情況:

dpvConfirmation S

如要進一步瞭解 dpvConfirmation,請參閱「處理美國地址」。

地址回應 包含值為 subpremisemissingComponentType 欄位。

確認地址範例

接受地址

當判定結果提供高度信心,表示地址可送達且可在下游程序中使用,不需進一步與客戶互動時,您就會接受該地址。

接受信號

Address Validation API 會提供多種信號,讓您知道是否應確認地址。

1. 驗證精細程度

validationGranularityPREMISE 以上即可,但在某些情況下,ROUTE 仍會指出可送達的地址。

2. 其他指標

高品質地址的判定結果也應提供下列資訊:

  • 沒有替換的資料。在這種情況下:hasReplacedComponents: FALSE
  • 沒有推斷的元件。在這種情況下:hasInferredComponents: FALSE

3. 美國地址信號

部分欄位僅適用於美國地址,可用來指出可送達的優質地址。對於可接受的美國地址,您應該會看到下列內容:

dpvConfirmation Y

如要進一步瞭解 dpvConfirmation,請參閱「處理美國地址」。

接受地址範例