大量地址驗證指南

目標

開發人員經常會處理含有客戶地址的資料集，但這些資料集的品質可能不佳。無論是客戶身分驗證、送貨等用途，都必須確保地址正確無誤。

Address Validation API 是 Google Maps Platform 的一項產品，可用於驗證地址。不過，這個函式一次只能處理一個地址。本文將探討如何在不同情境下使用大量地址驗證，包括 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 回應包含下列標記，就表示輸入的地址可送達：

• 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

實作無頭地址驗證

注意： 什麼是無頭？可在沒有圖形使用者介面的裝置上運作的軟體，例如伺服器端或指令列執行的指令碼。我們將使用這個詞彙，描述在沒有 GUI 的情況下使用軟體。

根據上述討論：

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

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

步驟 1：

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

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

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

• confirmationLevel
• inferred
• spellCorrected
• replaced
• unexpected

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

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

步驟 2：

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

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

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

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

結論

大量地址驗證是許多應用程式常見的用途。本文將示範一些情境和設計模式，說明如何實作符合《Google 地圖平台服務條款》的解決方案。

我們也進一步在 GitHub 上，以開放原始碼程式庫的形式，提供大量地址驗證的參考實作。歡迎參考，快速開始使用大量地址驗證功能。此外，您也可以參閱設計模式相關文章，瞭解如何在不同情境中使用程式庫。

後續步驟

下載「Improve checkout, delivery, and operations with reliable addresses 」(提供可靠的地址，改善結帳、送貨和營運流程) 白皮書，並觀看「Improving checkout, delivery, and operations with Address Validation 」(使用地址驗證改善結帳、送貨和營運流程) 網路研討會。

建議進一步閱讀：

• 大量地址驗證的應用
• GitHub 上的 Python 程式庫
• 觀看 Address Validation 示範

貢獻者

這篇文章由 Google 維護。以下是原始作者。
主要作者：

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