使用 Address Validation API 处理大量地址

目标

作为开发者，您经常使用包含客户地址的数据集，但这些数据集可能质量不佳。您需要确保地址正确无误，适用于客户 ID 验证、配送等各种用例。

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 节）。根据这些信息，您可以确定用户的地址是否无效，在这种情况下，您会在用户下一次与您的应用互动时提示用户输入正确的地址。

• Verdict 对象中的数据

  • inputGranularity
  • validationGranularity
  • geocodeGranularity
  • addressComplete
  • hasUnconfirmedComponents
  • hasInferredComponents
  • hasReplacedComponents

• 来自 AddressComponent 对象的数据

  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

如果您想缓存关于实际地址的任何信息，则只能在用户同意的情况下缓存这些数据。这样可确保用户清楚特定服务存储其地址的原因，且用户接受共享其地址的条款。

例如，用户在结账页上与电子商务地址表单直接互动就属于用户意见征求。我们了解到，您将出于配送包裹的目的而缓存并处理地址。

在征得用户同意后，您可以从响应中缓存 formattedAddress 和其他关键组件。不过，在无头场景中，用户无法表示同意，因为地址验证是从后端进行。因此，在这种无头场景中，您可以缓存非常有限的信息。

了解响应

如果 Address Validation API 响应包含以下标记，那么您可以确信输入地址具有可交付质量：

• Verdict 对象中的 addressComplete 标记为 true，
• Verdict 对象中的 validationGranularity 为 PREMISE 或 SUB_PREMISE
• 所有 AddressComponent 均未标记为：
  • Inferred（注意：: inferred=trueaddressComplete=true 可能会发生这种情况）
  • spellCorrected
  • replaced
  • unexpected和
• confirmationLevel：AddressComponent 的确认级别设置为 CONFIRMED 或 UNCONFIRMED_BUT_PLAUSIBLE

如果 API 响应不包含上述标记，则输入地址可能质量不佳，您可以在数据库中缓存标志以反映这一点。缓存标记表示整个地址质量不佳，而拼写更正等更详细的标记则表示地址质量问题的具体类型。下次客户与标记为质量不佳的地址互动时，您可以使用现有地址调用 Address Validation API。Address Validation API 将返回更正后的地址，您可以通过界面提示显示该地址。客户接受设置了格式的地址后，您可以从响应中缓存以下内容：

• formattedAddress
• postalAddress
• addressComponent componentNames 或
• UspsData standardizedAddress

实现无头地址验证

注意 ：什么是无头？能够在没有图形界面的设备上运行的软件，例如服务器端或命令行执行的脚本。我们将使用此术语来说明在没有 GUI 的情况下使用该软件的情况。

基于上述讨论：

• 出于业务原因，通常需要缓存 Address Validation API 中的部分响应。
• 不过，Google Maps Platform 的服务条款对可缓存的数据进行了限制。

在下面的部分中，我们将讨论两个步骤，了解如何遵循《服务条款》并实施大量地址验证。

第 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. 如果存在标记，您应该向用户显示用于更正/更新地址的界面。

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 Maps Platform 服务条款实现此类解决方案。

我们在 GitHub 上以开源库的形式进一步编写了大容量地址验证的参考实现。立即查看，快速开始使用大容量地址验证功能进行构建。另请参阅有关设计模式的文章，了解如何在不同场景中使用该库。

后续步骤

下载利用可靠的地址改进结账、送货和运营 白皮书，并查看利用地址验证改进结账、送货和运营 在线讲座。

推荐的更多阅读资料：

• 大容量地址验证的应用
• GitHub 上的 Python 库
• 浏览地址验证演示

贡献者

本文由 Google 维护。该文档最初是以下贡献者。
首席作者：

Henrik Valve | 解决方案工程师
Thomas Anglaret | 解决方案工程师
Sarthak Ganguly | 解决方案工程师