使用 Address Validation API 處理大量地址

目標

身為開發人員，您經常會使用含有客戶地址的資料集，而這些地址的品質可能不佳。您必須確保地址正確無誤，才能執行各種用途，例如客戶 ID 驗證和運送作業等。

地址驗證 API 是 Google 地圖平台的產品，可用於驗證地址。不過，它一次只能處理一個地址。在本文件中，我們將探討如何在不同情境下使用大量地址驗證功能，從 API 測試到一次性和週期性地址驗證。

用途

接下來，我們將說明大量地址驗證的用途。

測試

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

一次性驗證地址

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

定期驗證地址

有許多情況需要定期驗證地址：

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

深入探討技術

為方便說明，我們假設：

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

快取正式版使用

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

針對大量地址驗證用途，資料快取必須遵循第 11.3 節所述的 Address Validation API 服務特定條款。您可以根據這項資訊判斷使用者的地址是否無效，如果是的話，您可以在使用者下次與應用程式互動時，提示他們提供正確的地址。

  • 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

實作無頭地址驗證

根據上述討論內容：

  • 基於商業考量，通常需要快取 Address Validation 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 | 解決方案工程師