建構驗證邏輯

本文件說明如何建立地址檢查系統，以處理 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.

確切的邏輯則視您的情況而定，詳情請參閱「實作指南」。您也可以使用擴充元件程式庫中的這個邏輯開放原始碼實作方式。

工作流程總覽

下表總結了您系統執行的兩項操作：

  1. 使用的工作流程，用於根據修正項目、確認並接受行為。
  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 已推論或對元件進行變更，以便產生經過驗證的地址，您將會確認地址。在此情況下，您會有一個可寄送的地址，但希望最終產生的地址才是客戶預期的地址。

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

確認信號

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

1. 驗證精細程度

可以使用 ROUTE 以上的 validationGranularity 或更好的值，但 PREMISE 或 SUBPREMISE 的傳送結果信號可能較強。

2. 其他指標

在決定向客戶確認輸入地址時，判定結果還會包含下列資訊，以判斷要調查的組成部分：

推測資料 當 hasInferredComponents 欄位為 true，就表示 API 填入了從其他地址元件收集到的資訊。
取代的資料 如果 hasReplacedComponents 欄位為 true，API 會將輸入的資料替換成判定為有效地址的資料。

3. 美國地址信號

某些僅適用於美國地址的欄位，代表您的邏輯應向客戶確認詳細資料。適用以下任一項：

dpvConfirmation S

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

確認地址範例

接受地址

如果判定結果非常有信心，該地址可以交付，且可在下游過程中使用時，無需進一步客戶互動，您就可以接受地址。

接受信號

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

1. 驗證精細程度

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

2. 其他指標

判斷優質地址是否符合標準時，也必須提供下列資訊：

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

3. 美國地址信號

某些僅適用於美國地址的欄位代表可送達的高品質地址。如果是可接受的美國地址，您應該會看到以下內容：

dpvConfirmation Y

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

接受地址範例

上一頁
瞭解基本回應