建構驗證邏輯

本文件說明建構地址檢查系統的程序，以便處理 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. 要使用的 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，請參閱「處理美國地址」。

接受地址範例

上一頁
瞭解基本回應