使用 Address Validation API 處理大量地址

目標

開發人員經常會使用含有客戶地址的資料集，但這些地址的品質可能不佳。您必須確保地址正確無誤，才能用於客戶 ID 驗證、運送等用途。

地址驗證 API 是 Google 地圖平台產品，可用於驗證地址。不過，一次只能處理一個地址。本文將探討如何在不同情境下使用大量地址驗證，包括 API 測試、一次性地址驗證和週期性地址驗證。

用途

接下來，我們將瞭解 High Volume Address Validation 的實用情境。

測試

您通常會想執行數千個地址來測試 Address Validation API。您可能擁有逗號分隔值檔案中的地址，並想驗證地址品質。

一次性驗證地址

在導入 Address Validation API 時，您想根據使用者資料庫驗證現有的地址資料庫。

定期驗證地址

在下列情況下，您需要定期驗證地址：

  • 您可能已排定工作，以便驗證當天擷取的地址詳細資料，例如客戶註冊、訂單詳細資料、運送時間表。
  • 您可能會收到包含不同部門地址的資料傾印，例如銷售和行銷部門。接收地址的新部門通常會先驗證地址，再加以使用。
  • 您可能會在問卷調查或各種促銷活動中收集地址，然後在線上系統中更新。您希望在系統中輸入地址時，驗證地址是否正確。

深入探討技術

為方便說明，本文假設：

  • 您正在使用客戶資料庫 (即包含客戶詳細資料的資料庫) 中的地址呼叫 Address Validation API
  • 您可以在資料庫中，針對個別地址快取有效性標記。
  • 當個別消費者登入時，系統會從 Address Validation API 擷取有效性標記。

用於正式環境的快取

使用 Address Validation API 時，您通常會想快取 API 呼叫回應的某個部分。雖然我們的《服務條款》限制了可快取的資料，但凡是可從 Address Validation API 快取的資料，都必須針對使用者帳戶進行快取。也就是說，在資料庫中，地址或地址中繼資料必須根據使用者的電子郵件地址或其他主要 ID 進行快取。

如為「高用量地址驗證」使用案例，資料快取必須遵守地址驗證 API 服務專屬條款 (如第 11.3 節所述)。根據這項資訊，您就能判斷使用者的地址是否無效，並在使用者下次與應用程式互動時，提示他們輸入正確地址。

  • 來自 AddressComponent 物件的資料
    • confirmationLevel
    • inferred
    • spellCorrected
    • replaced
    • unexpected

如要快取實際地址的任何資訊，必須先取得使用者同意，才能快取該資料。確保使用者充分瞭解特定服務儲存地址的原因，並同意地址共用條款。

舉例來說，使用者在結帳頁面上直接與電子商務地址表單互動，即表示同意。我們瞭解您會快取及處理地址，以便運送包裹。

徵得使用者同意後，您可以從回應中快取 formattedAddress 和其他重要元件。不過，在無頭情境中，地址驗證是從後端進行，因此使用者無法提供同意聲明。因此，在無頭情境中，您可以快取非常有限的資訊。

瞭解回應

如果 Address Validation API 回應包含下列標記，則可確信輸入地址的品質足以供遞送：

  • Verdict 物件中的 addressComplete 標記為 true，
  • Verdict 物件中的 validationGranularity 為 PREMISE 或 SUB_PREMISE
  • 沒有任何 AddressComponent 標示為：
    • Inferred(注意: inferred=true可能發生於 addressComplete=true)
    • spellCorrected
    • replaced
    • unexpected，以及
  • confirmationLevel： AddressComponent 的確認層級設為 CONFIRMED 或 UNCONFIRMED_BUT_PLAUSIBLE

如果 API 回應不含上述標記，則輸入地址可能品質不佳，您可以在資料庫中快取標記來反映這點。快取標記表示地址整體品質不佳，而「已修正拼字」等更詳細的標記則表示特定類型的地址品質問題。下次與地址品質不佳的顧客互動時，您可以透過現有地址呼叫 Address Validation API。Address Validation API 會傳回修正後的地址，您可以透過 UI 提示顯示該地址。客戶接受格式化地址後，您可以從回覆中快取下列項目：

  • formattedAddress
  • postalAddress
  • addressComponent componentNames或
  • UspsData standardizedAddress

實作無標題地址驗證

根據上述討論內容：

  • 基於業務考量，通常需要快取地址驗證 API 回應的某個部分。
  • 不過，Google 地圖平台的《服務條款》限制了可快取的資料。

在下一節中，我們將討論如何遵守《服務條款》並實作大量地址驗證的兩步驟程序。

步驟 1：

首先，我們將探討如何從現有資料管道導入大量地址驗證指令碼。這個程序可讓您以符合《服務條款》的方式，儲存 Address Validation API 回應中的特定欄位。

圖表 A：下圖顯示如何使用大量地址驗證邏輯，強化資料管道。

alt_text

根據《服務條款》，您可以從 addressComponent 快取下列資料：

  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

因此，在實作的這一步驟中，我們會針對 UserID 快取上述欄位。

詳情請參閱實際資料結構。

步驟 2：

在步驟 1 中，我們收集到意見回饋，指出輸入資料集中的部分地址可能品質不佳。在下一個步驟中，我們會向使用者顯示這些標記的地址，並徵求同意修正儲存的地址。

圖表 B：這張圖表顯示使用者同意聲明流程的端對端整合方式：

alt_text

  1. 使用者登入時，請先檢查系統中是否已快取任何驗證標記。
  2. 如有任何標記，您應向使用者顯示 UI，讓他們修正及更新地址。
  3. 您可以再次呼叫 Address Validation API，使用更新或快取的地址，並向使用者顯示修正後的地址以供確認。
  4. 如果地址品質良好，Address Validation API 會傳回 formattedAddress。
  5. 如果地址已修正，您可以向使用者顯示修正後的地址；如果地址沒有修正，則可直接接受。
  6. 使用者接受後，您就可以在資料庫中快取 formattedAddress。

結論

大量地址驗證是您可能在許多應用程式中遇到的常見用途。本文將嘗試說明一些情境和設計模式，示範如何實作這類解決方案，同時遵守《Google 地圖平台服務條款》。

我們進一步在 GitHub 上以開放原始碼程式庫的形式，編寫了大量地址驗證的參考實作。歡迎參閱這份指南，瞭解如何快速開始使用大量地址驗證服務。此外，也請參閱這篇文章，瞭解如何在不同情境中使用程式庫的設計模式。

後續步驟

下載使用可靠的地址改善結帳、送貨和營運流程 白皮書，並觀看使用地址驗證改善結帳、送貨和營運流程 網路研討會。

建議閱讀：

貢獻者

本文由 Google 維護。以下是這篇文章的原始撰稿人。
主要作者：

Henrik Valve | 解決方案工程師
Thomas Anglaret | 解決方案工程師
Sarthak Ganguly | 解決方案工程師