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