使用 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 節所述。根據這項資訊,您可以判斷使用者的地址是否無效;在此情況下,系統會在使用者下次和應用程式互動時,提示他們提供正確的地址。

  • 來自判定結果物件的資料

    • inputGranularity
    • validationGranularity
    • geocodeGranularity
    • addressComplete
    • hasUnconfirmedComponents
    • hasInferredComponents
    • hasReplacedComponents
  • AddressComponent 物件的資料

    • confirmationLevel
    • inferred
    • spellCorrected
    • replaced
    • unexpected

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

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

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

瞭解回應

如果 Address Validation API 回應包含下列標記,即可確定輸入地址具有可送達的品質:

  • 判定結果物件中的 addressComplete 標記為 true
  • 判定結果物件中的 validationGranularityPREMISESUB_PREMISE
  • 沒有任何 AddressComponent 標示為:
    • Inferred(注意:: inferred=true如果發生 addressComplete=true,就可能發生)
    • spellCorrected
    • replaced
    • unexpected
  • confirmationLevelAddressComponent 的確認等級已設為 CONFIRMEDUNCONFIRMED_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

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

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

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

詳情請參閱實際資料結構

步驟 2:

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

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

alt_text

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

    • addressComplete為 true
    • validationGranularity不是 PREMISESUB_PREMISE
    • validationFlags 代表 inferred,spellCorrected,replaced,unexpected
      • 如果沒有標記,就表示現有的快取位址的良好品質良好且可使用。
  2. 如果有旗標,則應向使用者顯示正確/更新地址的 UI。

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

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

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

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

實作步驟 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 上的開放原始碼程式庫。閱讀指南,快速開始運用高磁碟區地址驗證功能建構內容。另請參閱,瞭解各種設計模式,瞭解如何在不同情境下使用程式庫。

後續步驟

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

建議的延伸閱讀:

貢獻者

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

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