本文档介绍了构建地址检查系统以处理来自 Address Validation API 的各种响应的过程。它介绍了如何构建逻辑以正确使用响应、调查 API 中的其他信号,以及何时以及如何提示客户了解更多信息。
一般来说,API 响应会确定系统应通过以下方式处理地址:
- 修正 - 地址质量不佳。 您应提示您提供更多信息。
- 确认 - 地址质量较高,但与输入地址相比有变化。您可能会提示进行确认。
- 接受 - 地址质量较高。您可以接受所提供的地址。
密钥用途
本文档可帮助您修改系统,以更好地分析 API 响应,并确定对提供的地址采取的后续操作。以下伪代码展示了一种可能的流程。
if (the API response indicates significant problems in the address)
FIX - prompt the user to fix the address
else if (the API response indicates less significant problems in the address)
CONFIRM - confirm with the user that the address is correct
else
ACCEPT - continue with the address returned by the API.
确切的逻辑取决于您的具体情况。如需了解详情,请参阅实现指南。您还可以使用此逻辑的开源实现(位于扩展组件库中)。
工作流程概览
下表总结了系统可以执行的两项操作:
- 根据修正、确认、接受行为要使用的工作流程。
- 响应中要检查的第一个信号。此处描述的信号来自
verdict
属性,不是唯一需要检查的信号,但它们提供了地址质量的初始指标。每种行为类型都对应于本文档中一个部分,其中介绍了您可能还需要调查的其他信号。
系统行为 | |||
---|---|---|---|
修正地址 |
来自
|
||
确认地址 |
来自
|
||
接受地址 |
Address Validation API 响应表示质量出色的地址。
|
实现方案指导
在设计系统响应来自 Address Validation API 的信号的方式时,以下建议可帮助您构建更有效的响应模型。不过,这些只是建议,因此请注意,您的实现方式应适合您的业务模式。
指南 | 详细信息 | |
---|---|---|
风险等级 |
当您在提示更正和接受输入的地址之间取得平衡时,请考虑针对您的情况的容忍级别。 |
Address Validation API 会返回各种信号,您可以将这些信号与风险级别相结合,以优化验证流程。 例如,如果地址具有未确认的门牌号,您仍然可以接受它。另一方面,如果您的业务运营对地址的精确度要求更高,则可以提示用户。如需查看可归入任一类别的示例,请参阅“接受地址 - 示例”中的“非美国未经确认的门牌号”。 |
接受地址 |
如果客户未回应提示,最好允许系统接受原始条目。 |
在这些情况下,客户可能输入了系统中不存在的地址,例如用于新建设的地址。 |
提供反馈 |
当您重新发出地址验证请求时,您还可以向 |
这有助于 Google 了解您最终如何处理最终响应。 请参阅处理更新后的地址。 |
修正地址
当结果明确表明某个地址无法送达时,修正某个地址。然后,您的系统可以提示用户提供必要的信息,之后您将重新发出工作流以获取可交付地址。
修正信号
Address Validation API 会提供多种信号,让您知道某个地址是否应修正。
1. 验证粒度和缺失组件
以下两个信号最能表明地址有问题:
- 只要
validationGranularity
字段为OTHER
,系统就应调查地址组成部分信号,以详细了解错误的发生位置及解决方法。 - 每当后处理的
address
对象返回missingComponentTypes
字段时,系统都应检查该组件。缺少组成部分还会导致地址不完整且无法送达。
2. 其他信号
Address Validation API 还提供有助于诊断特定问题的其他信号:
可疑组件 | 当组件的确认级别枚举为 UNCOMFIRMED_AND_SUSPICIOUS 时,该组件很可能不正确。
|
---|---|
无法解析的组件 | unresolvedToken 是输入的一部分未被识别为地址的有效部分。 |
3. 美国地址信号
某些仅适用于美国地址的字段可提供有用的信号,表明相应地址无法递送,应予以修正。对于需要修复的地址,您应该会看到以下内容:
dpvConfirmation
|
N 、D 或空。
|
---|
如需详细了解 dpvConfirmation
,请参阅处理美国地址。
确认地址
如果判定结果表明 Address Validation API 是推断地址的或更改了地址组成部分,以生成已验证的地址,您确认的是地址。在这些情况下,您已经有了可配送地址,但更希望确保生成的地址是客户预期的地址。
为了向客户提供正确的提示,您的逻辑会识别服务标记的组件,以确定对组件应用的操作或标记应用于该组件的 API,例如 inferred
、replaced
或 spellCorrected
。请参阅参考中的 AddressComponent。
确认信号
Address Validation API 会提供多种信号,让您知道是否应确认某个地址。
1. 验证粒度
validationGranularity
为 ROUTE
或更优值是可以接受的,但 PREMISE 或 SUBPREMISE 可提供更强的传递性信号。
2. 其他信号
在决定与客户确认地址输入时,判定结果还会提供以下信息,以确定要调查哪些部分:
推断的数据 | 如果 hasInferredComponents 字段为 true ,则表示 API 填充了从其他地址组成部分收集的信息。
|
---|---|
已替换的数据 | 当 hasReplacedComponents 字段为 true 时,API 会将输入的数据替换为它认为使地址有效的数据。 |
3. 美国地址信号
某些仅适用于美国地址的字段表示您的逻辑应向客户确认详细信息。以下两种情况之一:
dpvConfirmation
|
S
如需详细了解 |
---|---|
地址响应 | 包含值为 subpremise 的 missingComponentType 字段。
|
接受地址
如果认定结果高度可信,认为该地址可以送达,并且无需客户进一步互动,即可在下游流程中使用,此时您就可以接受该地址。
接受信号
Address Validation API 会提供多种信号,让您知道是否应确认某个地址。
1. 验证粒度
我们接受 validationGranularity
为 PREMISE
或更高的值,但在某些情况下,ROUTE
仍表示一个可递送地址。
2. 其他信号
优质地址的判定结果还应提供以下信息:
- 没有已替换的数据。在此示例中为
hasReplacedComponents: FALSE
。 - 没有任何推断的组件。在此示例中为
hasInferredComponents: FALSE
。
3. 美国地址信号
某些仅适用于美国地址的字段表示可以送货的高品质地址。如需查看可接受的美国地址,您应该会看到以下内容:
dpvConfirmation
|
Y
如需详细了解 |
---|