客观
作为开发者,您经常使用包含客户地址的数据集,这些地址可能质量不佳。对于从客户 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:下图显示了如何使用大量地址验证逻辑来增强数据流水线。
根据《服务条款》,您可以缓存 addressComponent
中的以下数据:
confirmationLevel
inferred
spellCorrected
replaced
unexpected
因此,在这一实现步骤中,我们将根据 UserID 缓存上述字段。
如需了解详情,请参阅实际数据结构。
第 2 步:
在第 1 步中,我们收集了反馈,指出输入数据集中的某些地址可能质量不佳。在下一步中,我们将获取这些被标记的地址,并将其呈现给用户,并获得用户同意以更正存储的地址。
图 B:此图显示了用户意见征求流程的端到端集成方式,如下所示:
- 当用户登录时,首先检查系统是否缓存了任何验证标志。
- 如果存在标记,您应向用户显示一个用于更正和更新其地址的界面。
- 您可以使用更新后的地址或缓存的地址再次调用 Address Validation API,然后向用户显示更正后的地址进行确认。
- 如果地址的质量较高,Address Validation API 会返回
formattedAddress
。 - 如果进行了更正,您可以向用户显示该地址,如果没有更正,则静默接受。
- 用户接受后,您可以在数据库中缓存
formattedAddress
。
总结
在许多应用中,大批量地址验证是常见用例。本文档将尝试按照 Google Maps Platform 服务条款,演示一些场景和设计模式,了解如何实现此类解决方案。
我们在 GitHub 上进一步编写了大批量地址验证的参考实现,并将其作为开源库。立即查看,开始使用高容量地址验证功能快速进行构建。此外,您还可以参阅有关如何在不同场景中使用该库的设计模式的文章。
后续步骤
下载使用可靠的地址改进结账、送货和运营 白皮书,并观看利用地址验证改进结账、送货和运营 在线讲座。
建议深入阅读:
- 大量地址验证的应用
- GitHub 上的 Python 库
- 浏览地址验证演示
贡献者
本文由 Google 维护。它最初是由以下贡献者编写的。
主要作者:
Henrik Valve | 解决方案工程师
Thomas Anglaret | 解决方案工程师
Sarthak Ganguly | 解决方案工程师