使用 Address Validation API 處理大量地址

目標

開發人員經常處理內含客戶地址的資料集，但該資料的品質可能不太理想。您必須確保地址正確無誤，適用於客戶 ID 驗證、運送等用途。

Address Validation API 是 Google 地圖平台的產品，可用來驗證地址。不過，一次只處理一個地址。在本文件中，我們會探討如何在不同情境下使用高量地址驗證，包括 API 測試、一次性和週期性的地址驗證。

用途

現在，我們來瞭解高磁碟區位址驗證的用途。

測試

您通常會想要執行數千個位址來測試 Address Validation API。您可能在「逗號分隔值」(逗號分隔值) 檔案中填入這些地址，但想要驗證這些地址的品質。

一次性驗證地址

加入 Address Validation API 時，您想針對使用者資料庫驗證現有地址資料庫。

定期驗證地址

在一些情境中，您必須定期驗證地址：

• 您排定的工作可能會針對當天擷取的詳細資料驗證地址，例如客戶註冊、訂單詳細資料、配送時間表等。
• 您可能會收到包含不同部門地址的資料傾印，例如從銷售到行銷等。接收地址的新部門通常希望先進行驗證，再使用地址。
• 您可以在問卷調查期間收集地址，或針對多種促銷活動收集地址，之後再到線上系統更新。建議您在系統中輸入地址時，確認地址正確無誤。

深入探討技術

就本文件而言，我們假設以下情況：

• 您使用客戶資料庫 (即內含客戶詳細資料的資料庫) 中的地址呼叫 Address Validation API
• 您可以快取資料庫中個別地址的有效性旗標。
• 個別客戶登入時，系統會從 Address Validation API 擷取有效性旗標。

立即試用：前往 Google Cloud 控制台啟用 Address Validation API。

快取以用於實際工作環境

注意： 下一節所述的特定回應元素最多可以連續儲存 30 天。所有回應元素都必須在 30 天後刪除。

使用 Address Validation API 時，您通常會希望快取 API 呼叫中的部分回應。雖然我們的《服務條款》限制了可快取的資料，但是所有可透過 Address Validation API 快取的資料都必須針對使用者帳戶快取。這表示在資料庫中，系統必須根據使用者的電子郵件地址或其他主要 ID，快取地址或地址中繼資料。

如為高用量地址驗證用途，資料快取必須遵守 Address Validation API 服務專屬條款，如第 11.3 節所述。根據這項資訊，您可以判斷使用者的地址是否無效；在此情況下，系統會在使用者下次和應用程式互動時，提示他們提供正確的地址。

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

如要快取任何有關實際地址的資訊，則必須取得使用者同意才能快取這些資料。這麼做能確保使用者清楚瞭解某項服務儲存地址的原因，且使用者也同意分享地址的條款。

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

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

瞭解回應

注意： 另外，您也可以參考「建構驗證邏輯」指南，瞭解如何解讀回應。

如果 Address Validation API 回應包含下列標記，即可確定輸入地址的交付品質具有可信度：

• 判定結果物件中的 addressComplete 標記為 true，
• 判定結果物件中的 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

實作無頭地址驗證

注意： 什麼是無頭影片？一種軟體可在沒有圖形使用者介面的裝置上運作，例如伺服器端或指令列執行指令碼。我們將使用此字詞說明軟體在沒有 GUI 的情況下使用的時機。

根據以上討論內容：

• 基於業務考量，通常必須快取 Address Validation API 的部分回應。
• 不過，Google 地圖平台的《服務條款》會限制可快取的資料。

我們將在下一節討論一個兩個步驟，說明如何符合《服務條款》規定，並實行大量的地址驗證功能。

步驟 1：

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

圖 A：下圖顯示如何利用高磁碟區位址驗證邏輯強化資料管道。

• 根據《服務條款》的規定，在以無頭的方式驗證地址時，您可以快取 addressComplete, validationGranularity and validationFlags。

• 您可以依據客戶資料庫中的特定 UserID 將 addressComplete,validationGranularity and validationFlags, PlaceID 快取。

因此，在實作這個步驟中，我們會根據 UserID 快取上述欄位。

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

步驟 2：

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

圖 B：上圖顯示使用者同意聲明流程的端對端整合方式如下：

1. 使用者登入時，請先檢查系統是否已快取任何驗證旗標，例如：

   • addressComplete為 true
   • validationGranularity不是 PREMISE 或 SUB_PREMISE
   • validationFlags 代表 inferred,spellCorrected,replaced,unexpected。
     • 如果沒有標記，就表示現有的快取位址的良好品質良好且可使用。

2. 如果有旗標，則應向使用者顯示正確/更新地址的 UI。

3. 您可以使用已更新或快取的地址再次呼叫 Address Validation API，並向使用者顯示正確的地址以進行確認。

4. 如果地址品質良好，Address Validation API 會傳回 formattedAddress。

5. 如果已完成修正，您可以向使用者提供該地址；如果沒有修正，也可以不通知使用者。

6. 使用者接受後，您就可以在資料庫中快取 formattedAddress。

注意： 完成這項工作流程後，應刪除快取的 validationFlags。

實作步驟 2 的虛擬程式碼：

If addressComplete is FALSE

OR

If validationGranularity is Not PREMISE OR SUB_PREMISE

OR

If validationFlags is inferred OR spellCorrected OR replaced OR unexpected
  {

    # This means there are issues with the existing cached address

    Call UI to present the address to user

}
Else{

    # This means existing address is good
  Proceed to checkout
}

結論

高磁碟區位址驗證是常見的用途，在許多應用程式中可能會遇到這種狀況。本文件將展示一些使用情境和設計模式，說明如何實作這類符合《Google 地圖平台服務條款》的解決方案。

我們進一步將高磁碟區位址驗證的參考實作撰寫為 GitHub 上的開放原始碼程式庫。請參閱相關說明， 開始運用高磁碟區地址驗證功能快速開始建構內容另請參閱有關設計模式的文章，瞭解如何在不同情境下使用程式庫。

後續步驟

下載「透過可靠的地址改善結帳、配送及營運流程 」白皮書，並參閱「利用地址驗證改善結帳、配送和營運成效 」網路研討會。

建議的延伸閱讀：

• 大量位址驗證的應用程式
• GitHub 上的 Python 程式庫
• 瀏覽地址驗證的示範

協作者

Google 維護這篇文章。以下著作人最初編寫過這個草稿。
主體作者：

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