使用 Address Validation API 处理大量地址

目标

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

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=trueaddressComplete=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 | 解决方案工程师