使用 Address Validation API 处理大量地址

目标

作为开发者，您经常会处理包含质量不佳的客户地址的数据集。您需要确保地址正确无误，以便在各种用例（例如客户身份证件验证、配送等）中使用。

Address Validation API 是 Google Maps Platform 的一款产品，可用于验证地址。不过，它一次只能处理一个地址。在本文档中，我们将探讨如何在不同场景（从 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 会返回经过更正的地址，您可以使用界面提示显示该地址。客户接受经过格式设置的地址后，您可以从响应中缓存以下内容：

  • formattedAddress
  • postalAddress
  • addressComponent componentNames 或
  • UspsData standardizedAddress

实现无头地址验证

根据上述讨论：

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

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

第 1 步：

在第一步中，我们将探讨如何通过现有数据流水线实现高量地址验证脚本。通过此流程，您可以以符合服务条款的方式存储 Address Validation 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 | 解决方案工程师