建構驗證邏輯

本文件說明建構地址檢查系統的程序，以便處理 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 或更高版本。請參閱精細程度值。
  • addressComplete 為 true。
  • hasInferredComponents 欄位為 true，或 hasReplacedComponents 欄位為 true。
接受地址

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

工作流程

繼續使用退回地址。

判定結果信號

必須符合下列所有條件：

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

實作指南

設計系統如何回應 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 N、D 或空白。

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

修正地址範例

確認地址

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

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

確認信號

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

1. 驗證精細程度

validationGranularity 為 ROUTE 以上即可，但 PREMISE 或 SUBPREMISE 可提供更強的信號，表示可順利放送。

2. 其他指標

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

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

3. 美國地址信號

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

dpvConfirmation S

如要進一步瞭解 dpvConfirmation，請參閱「處理美國地址」。
地址回應 包含值為 subpremise 的 missingComponentType 欄位。

確認地址範例

接受地址

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

接受信號

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

1. 驗證精細程度

validationGranularity 為 PREMISE 以上即可，但在某些情況下，ROUTE 仍會指出可送達的地址。

2. 其他指標

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

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

3. 美國地址信號

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

dpvConfirmation Y

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

接受地址範例

上一頁
瞭解基本回應