此页面由 Cloud Translation API 翻译。

使用 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 服务专用条款。根据这些信息，您可以确定用户的地址是否无效，在这种情况下，您需要在用户下一次与您的应用互动时提示用户输入正确的地址。

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

实现无头地址验证

根据上述讨论内容：

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

在下一部分，我们将讨论如何遵循服务条款和实现大量地址验证的两个步骤。

第 1 步：

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

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

alt_text

根据《服务条款》，您可以在以无头方式验证地址时缓存 addressComplete,validationGranularity and validationFlags。
您可以根据客户数据库中的特定 UserID 来缓存 addressComplete,validationGranularity and validationFlags, PlaceID。

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

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

第 2 步：

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

图 B：此图展示了端到端的用户意见征求流程集成情况：

alt_text

用户登录时，请先检查您是否在系统中缓存了任何验证标志，例如：
- addressComplete 为 true
- validationGranularity 不是 PREMISE 或 SUB_PREMISE
- validationFlags 为 inferred,spellCorrected,replaced,unexpected。
  - 如果没有标记，则很有把握，现有缓存地址质量良好，可以使用。
如果存在标记，您应向用户显示用于更正/更新地址的界面。
您可以使用更新后的或缓存的地址再次调用 Address Validation API，并向用户显示更正后的地址进行确认。
如果地址质量较高，Address Validation API 会返回 formattedAddress。
您可以在更正地址时向用户显示该地址；如果没有更正，则默认接受。
用户接受后，您可以将 formattedAddress 缓存在数据库中。

实现第 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 上进一步编写了高容量地址验证的参考实现，作为开源库。立即查看，以便快速开始使用大批量地址验证功能进行构建。另请参阅有关如何在不同场景中使用该库的设计模式文章。

后续步骤

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

建议深入阅读：

贡献者

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

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