使用 Address Validation API 處理大量地址

目標

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

Address Validation API 是 Google 地圖平台的產品，可用來驗證地址。但是一次只處理一個地址。本文件將說明如何在不同情境下使用高磁碟區地址驗證，包括 API 測試、一次性和週期性的地址驗證。

用途

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

測試

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

一次性驗證地址

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

定期驗證地址

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

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

深入探討技術

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

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

用於實際工作環境的快取

使用 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=trueaddressComplete=true 可能發生)
    • spellCorrected
    • replaced
    • unexpected和
  • confirmationLevel：AddressComponent 的確認等級已設為 CONFIRMEDorUNCONFIRMED_BUT_PLAUSIBLE

如果 API 回應不含上述標記，則輸入位址的品質很可能會不佳，您可以快取資料庫中的標記來反映這一點。快取旗標表示整個位址的品質不佳，而更詳細的標記 (例如「拼寫校正」等) 表示是特定類型的地址品質問題。下次與遭標記為品質不佳的地址進行客戶互動時，您可以使用現有地址呼叫 Address Validation API。Address Validation API 會傳回正確的地址，您可以使用 UI 提示顯示。客戶接受格式化的地址後，您就可以從回應中快取下列項目：

  • formattedAddress
  • postalAddress
  • addressComponent componentNames 或
  • UspsData standardizedAddress

實作無頭地址驗證

根據以上討論內容：

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

我們將在下一節討論兩個步驟，說明如何符合《服務條款》及實作大量地址驗證程序。

步驟 1：

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

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

alt_text

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

  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

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

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

步驟 2：

在步驟 1 中，我們收集到意見回饋，指出輸入資料集中部分地址可能並非高品質的地址。在下一個步驟中，我們會將這些標記的地址提供給使用者，並取得使用者同意，讓他們修正已儲存的地址。

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

alt_text

  1. 使用者登入時，請先檢查您是否已在系統中快取任何驗證標記。
  2. 若有標記，您應向使用者顯示使用者介面，以修正及更新其地址。
  3. 您可以使用更新或快取的地址再次呼叫 Address Validation API，並向使用者顯示正確的位址來確認。
  4. 如果位址的品質良好，Address Validation API 會傳回 formattedAddress。
  5. 如果已完成修正，您可以向使用者提供該位址；如果沒有修正，則可在不發出通知的情況下接受。
  6. 使用者接受後，您就可以在資料庫中快取 formattedAddress。

結論

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

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

後續步驟

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

建議的延伸閱讀：

協作者

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

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