使用 Address Validation API 处理大量地址

目标

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

地址验证 API 是 Google Maps Platform 的一项产品，可用于验证地址。不过，它一次只能处理一个地址。本文档将介绍如何在不同场景下使用 High Volume Address Validation，包括 API 测试、一次性地址验证和定期地址验证。

使用场景

现在，我们将了解大批量地址验证的适用场景。

测试

您通常需要通过运行数千个地址来测试 Address Validation API。您可能拥有一个逗号分隔值文件，其中包含一些地址，并且您希望验证这些地址的质量。

一次性验证地址

在开始使用 Address Validation API 时，您希望根据用户数据库验证现有地址数据库。

定期验证地址

在以下多种情况下，需要定期验证地址：

  • 您可能已安排作业来验证白天捕获的详细信息的地址，例如客户注册信息、订单详情、送货时间表。
  • 您可能会收到包含不同部门（例如销售部门和营销部门）地址的数据转储。接收地址的新部门通常希望在使用之前对其进行验证。
  • 您可能会在调查或各种促销活动期间收集地址，然后在在线系统中更新这些地址。您希望在系统中输入地址时验证地址是否正确。

技术层面的深入探讨

就本文档而言，我们假设：

  • 您正在使用客户数据库（即包含客户详细信息的数据库）中的地址调用 Address Validation API
  • 您可以在数据库中针对各个地址缓存有效性标志。
  • 当个人客户登录时，系统会从 Address Validation API 中检索有效性标志。

用于生产的缓存

使用 Address Validation API 时，您通常希望缓存 API 调用返回的部分响应。虽然我们的服务条款限制了可以缓存的数据，但从 Address Validation API 缓存的任何数据都必须针对用户账号进行缓存。这意味着，在数据库中，地址或地址元数据必须根据用户的电子邮件地址或其他主要 ID 进行缓存。

对于“大批量地址验证”使用情形，数据缓存必须遵循地址验证 API 服务专用条款（第 11.3 条中概述）。根据这些信息，您将能够确定用户的地址是否可能无效，如果无效，您将在用户下次与您的应用互动时提示用户提供更正后的地址。

  • 来自 AddressComponent 对象的数据
    • confirmationLevel
    • inferred
    • spellCorrected
    • replaced
    • unexpected

如果您想缓存有关实际地址的任何信息，则必须在征得用户同意后才能缓存该数据。这样可确保用户清楚了解特定服务存储其地址的原因，并且同意共享其地址的条款。

用户同意的一个示例是直接与结账页面上的电子商务地址表单互动。我们了解，您会缓存和处理地址，以便配送包裹。

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

了解响应

如果地址验证 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 将返回更正后的地址，您可以使用界面提示显示该地址。客户接受格式化地址后，您可以从响应中缓存以下内容：

  • formattedAddress
  • postalAddress
  • addressComponent componentNames或
  • UspsData standardizedAddress

实现无头地址验证

根据上述讨论：

  • 出于业务原因，通常需要缓存地址验证 API 的部分响应。
  • 不过，Google Maps Platform 的服务条款限制了可以缓存的数据。

在下一部分中，我们将讨论如何通过两步流程来遵守服务条款并实现大批量地址验证。

第 1 步：

在第一步中，我们将了解如何从现有数据流水线实现大批量地址验证脚本。此流程可让您以符合《服务条款》的方式存储地址验证 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 Maps Platform 服务条款的此类解决方案。

我们还在 GitHub 上以开源库的形式编写了高容量地址验证的参考实现。不妨查看一下，快速开始使用高容量地址验证服务进行构建。您还可以访问有关设计模式的文章，了解如何在不同场景中使用该库。

后续步骤

下载通过可靠的地址提升结账、配送和运营效率 白皮书，并观看通过地址验证提升结账、配送和运营效率 网络研讨会。

建议的延伸阅读内容：

贡献者

Google 负责维护本文。以下贡献者最初撰写了此内容。
主要作者：

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