大批量地址验证指南

目标

作为开发者，您经常会处理包含客户地址的数据集，这些地址可能质量不佳。您需要确保地址正确无误，以便用于客户身份验证、配送等各种应用场景。

Address Validation API 是 Google Maps Platform 提供的一款产品，可用于验证地址。不过，它一次只能处理一个地址。在本文档中，我们将探讨如何在不同场景下使用 High Volume Address Validation，从 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 缓存地址或地址元数据。

对于大批量地址验证用例，数据缓存必须遵循第 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 将返回更正后的地址，您可以使用界面提示显示该地址。客户接受格式化地址后，您可以从响应中缓存以下内容：

• formattedAddress
• postalAddress
• addressComponent componentNames或
• UspsData standardizedAddress

实现无头地址验证

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

根据上述讨论：

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

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

第 1 步：

在第一步中，我们将探讨如何通过现有数据流水线实现大批量地址验证脚本。通过此流程，您可以按照符合服务条款的方式存储 Address Validation API 响应中的特定字段。

图 A：下图展示了如何使用大批量地址验证逻辑来增强数据流水线。

根据服务条款，您可以缓存 addressComponent 中的以下数据：

• confirmationLevel
• inferred
• spellCorrected
• replaced
• unexpected

因此，在实现过程的这一步中，我们将根据 UserID 缓存上述字段。

如需了解详情，请参阅实际数据结构。

第 2 步：

在第 1 步中，我们收集了反馈，其中指出输入数据集中的某些地址可能质量不高。在下一步中，我们将获取这些标记的地址并将其呈现给用户，并征得用户同意以更正存储的地址。

图 B：此图展示了用户意见征求流程的端到端集成可能是什么样的：

1. 当用户登录时，首先检查您的系统中是否缓存了任何验证标志。
2. 如果存在标记，您应向用户显示一个界面，以便他们更正和更新其地址。
3. 您可以使用更新后的地址或缓存的地址再次调用 Address Validation API，并向用户显示更正后的地址以供确认。
4. 如果地址质量良好，Address Validation API 会返回 formattedAddress。
5. 如果地址已更正，您可以向用户显示该地址；如果未更正，您可以静默接受。
6. 用户接受后，您可以在数据库中缓存 formattedAddress。

注意： 此工作流完成后，应删除缓存的 validationFlags。

总结

大批量地址验证是一种常见用例，您可能会在许多应用中遇到。本文档旨在演示一些场景和设计模式，说明如何实现符合 Google Maps Platform 服务条款的解决方案。

我们还在 GitHub 上编写了 High Volume Address Validation 的参考实现，作为一个开源库。欢迎查看，快速开始使用 High Volume 地址验证 进行构建。另请参阅有关如何在不同场景中使用该库的设计模式的文章。

后续步骤

下载通过可靠的地址提升结账、配送和运营体验 白皮书，并观看通过地址验证提升结账、配送和运营体验 在线讲座。

建议的补充阅读材料：

• 大批量地址验证的应用
• GitHub 上的 Python 库
• 探索 Address Validation 演示

贡献者

本文由 Google 维护。以下贡献者是其最初的作者。
主要作者：

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