使用 Address Validation API 处理大量地址

目标

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

Address Validation API 是 Google Maps Platform 中的一款产品，可用于验证地址。不过，它一次只处理一个地址。在本文档中，我们将介绍如何在不同场景（从 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 服务专用条款。根据这些信息，您将能确定用户的地址是否无效。如果无效，则您需要在用户下次与您的应用互动时，提示用户输入正确的地址。

• Verdict 对象中的数据

  • inputGranularity
  • validationGranularity
  • geocodeGranularity
  • addressComplete
  • hasUnconfirmedComponents
  • hasInferredComponents
  • hasReplacedComponents

• 来自 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

实现无头地址验证

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

根据上述讨论内容：

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

在下文中，我们将讨论一个包含两个步骤的流程，了解如何遵守服务条款和实现大量地址验证。

第 1 步：

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

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

• 根据《服务条款》，在以无头方式验证地址时，您可以缓存 addressComplete,validationGranularity and validationFlags。

• 您可以针对客户数据库中的特定 UserID 缓存 addressComplete,validationGranularity and validationFlags, PlaceID。

因此，在实现这一步骤中，我们将针对 UserID 缓存上述字段。

如需了解详情，请参阅有关实际数据结构的详细信息。

第 2 步：

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

图 B：此图展示了用户意见征求流程的端到端集成大致如下所示：

1. 当用户登录时，请先检查您的系统中是否缓存了任何验证标志，例如：

   • addressComplete 为 true
   • ValidationGranularity 不是 PREMISE 或 SUB_PREMISE
   • validationFlags 为 inferred,spellCorrected,replaced,unexpected。
     • 如果没有标记，则高度确信现有缓存地址质量良好，可以使用它。

2. 如果存在标记，您应向用户显示一个用于更正/更新地址的界面。

3. 您可以使用更新后的地址或缓存的地址再次调用 Address Validation API，并将更正后的地址向用户显示进行确认。

4. 如果地址质量较高，Address Validation API 会返回 formattedAddress。

5. 您可以在更正后向用户显示该地址，也可以在没有更正时静默接受该地址。

6. 用户接受后，您可以将 formattedAddress 缓存在数据库中。

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

实现第 2 步的伪代码：

If addressComplete is FALSE

OR

If validationGranularity is Not PREMISE OR SUB_PREMISE

OR

If validationFlags is inferred OR spellCorrected OR replaced OR unexpected
  {

    # This means there are issues with the existing cached address

    Call UI to present the address to user

}
Else{

    # This means existing address is good
  Proceed to checkout
}

总结

高容量地址验证是许多应用中可能遇到的常见用例。本文档将介绍一些场景和设计模式，说明如何按照 Google Maps Platform 服务条款实现此类解决方案。

我们还在 GitHub 上进一步编写了 High Volume Address Validation 的参考实现，并将其作为开源库。请看一看，以便快速开始使用高容量地址验证功能进行构建。另请参阅有关设计模式的文章，了解如何在不同场景中使用该库。

后续步骤

下载利用可靠的地址改进结账、送货和运营 白皮书，并查看利用地址验证改进结账、送货和运营 在线讲座。

推荐阅读材料：

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

贡献者

本文由 Google 维护。最初由以下贡献者编写。
首席作者：

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