构建验证逻辑

本文档介绍了构建地址检查系统以处理 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.

具体逻辑取决于您的具体情况。如需了解详情,请参阅实现指南。您还可以使用扩展组件库中我们对该逻辑的开源实现。

工作流程概览

下表总结了针对您的系统的两项操作:

  1. 要使用的工作流程(基于修正、确认和接受行为)。
  2. 从响应中检查的第一个信号。此处所述的信号来自 verdict 属性,并非唯一需要检查的信号,但它们提供了地址质量的初始指示。每种行为类型均对应于本文档中的一个部分,该部分介绍了您可能还需要调查的其他信号。
您的系统行为
修正地址

来自 verdict 的响应指明了应该提供的重要的缺失信息。Address Validation API 返回的地址可能质量不佳。

工作流

  1. 必要时调查地址组成部分。
  2. 提示客户解决地址问题。
  3. 请求验证更新后的地址。
  4. (可选)向该 API 的反馈端点发送请求。 请参阅处理更新后的地址
  5. 输入地址。

判定信号

存在以下任一情况:

确认地址

来自 verdict 的响应表明地址可送达,但对原始输入进行了更改:推断拼写正确的数据或可以确认的数据。

工作流

  1. 需要更正:
    1. 必要时调查地址组成部分。
    2. 请求验证更新后的地址。
    3. (可选)向该 API 的反馈端点发送请求。 请参阅处理更新后的地址
    4. 输入地址。
  2. 无需更正:
    1. (可选)向该 API 的反馈端点发送请求。 请参阅处理更新后的地址
    2. 输入地址。

判定信号

以下所有条件均适用:

  • validationGranularity 包含 ROUTE 或更高版本。请参阅粒度值。
  • addressCompletetrue
  • hasInferredComponents 字段为 truehasReplacedComponents 字段为 true
接受地址

Address Validation API 响应表明地址的质量非常好。

工作流

继续使用已退回的地址。

判定信号

以下所有条件均适用:

  • validationGranularity 包含 PREMISE 或更高版本。 请参阅粒度值。
  • addressCompletetrue
  • 没有推断的或被替换的组件。

实现方案指导

在设计系统如何响应来自 Address Validation API 的信号时,以下建议可以帮助您构建更有效的响应模型。不过,这些只是建议,因此请记住,您的实现应适合您的业务模式。

指南 详细信息
风险级别

在提示更正和接受输入的地址之间取得平衡时,请考虑您遇到的情况的容忍程度。

Address Validation API 会返回各种信号,您可以将这些信号与风险级别结合起来来优化验证流程。

例如,如果地址包含未经确认的门牌号,您仍然可以接受它。另一方面,如果您的业务运营需要更高的地址精确度,您可以提示用户。有关可属于任一类别的示例,请参阅接受地址 - 示例中的未经确认的美国境外门牌号

接受地址

如果客户没有回应提示,最好让您的系统接受原始条目。

在这些情况下,客户可能输入了系统中没有的地址(例如用于新建设的地址)。

提供反馈

重新发出地址验证请求时,您也可以向 provideValidationFeedback 端点发送请求。

以便 Google 了解您最终如何处理最终响应。 请参阅处理更新后的地址

修正地址

当结果明确表明某个地址无法送达时,请修正该地址。然后,您的系统可以提示客户提供必要的信息,之后您需要重新开具工作流程,以获取配送地址。

修正信号

Address Validation API 提供了许多信号,可让您了解是否应修正某个地址。

1. 验证粒度和缺失的组件

以下两个信号最准确地说明了有问题的地址:

  • 每当 validationGranularity 字段为 OTHER 时,您的系统都应调查地址组成部分信号,以详细了解错误的出现位置以及如何修正错误。
  • 每当经过后处理的 address 对象返回 missingComponentTypes 字段时,您的系统都应检查该组件。如果缺少组件,也会导致地址不完整且无法送达。

2. 其他信号

Address Validation API 还提供了其他信号来帮助诊断特定问题:

可疑组件 当组件的确认级枚举为 UNCOMFIRMED_AND_SUSPICIOUS 时,该组件很可能不正确。
未解析的组成部分 unresolvedToken 是输入的一部分,但未被识别为地址的有效部分。

3. 美国地址信号

某些仅适用于美国地址的字段提供了有用的信号,表明该地址无法送达,应予以修正。对于需要修复的地址,您应看到以下内容:

dpvConfirmation 值为 ND 或为空。

如需详细了解 dpvConfirmation,请参阅处理美国地址

修正地址示例

确认地址

当判定结果表明 Address Validation API 推断出或更改地址组成部分时,您确认地址以生成经过验证的地址。在这些情况下,您会得到一个可送达的地址,但更希望确定生成的地址就是客户想要的地址。

为了向客户提供正确的提示,您的逻辑会识别由服务标记的组件,以确定应用于该组件的操作或标志,例如 inferredreplacedspellCorrected。请参阅参考文档中的 AddressComponent

确认信号

Address Validation API 提供了许多信号,可让您知道是否应确认某个地址。

1. 验证粒度

可以接受 ROUTE 或更高的 validationGranularity,但 PREMISE 或 SUBPREMISE 可以提供更强的可交付性信号。

2. 其他信号

在决定与客户确认输入地址时,判定结果还会提供以下内容,以确定要调查的组件:

推断的数据 hasInferredComponents 字段为 true 时,您知道 API 已填充了它从其他地址组成部分收集的信息。
替换的数据 hasReplacedComponents 字段为 true 时,API 会将输入的数据替换为其认为使地址有效的数据。

3. 美国地址信号

某些仅适用于美国地址的字段表示您的逻辑应向客户确认详细信息。可能出现以下任一情况:

dpvConfirmation S

如需详细了解 dpvConfirmation,请参阅处理美国地址

地址响应 包含值为 subpremisemissingComponentType 字段。

确认地址示例

接受地址

当判定结果高度可信时,表示地址可以递送,且在下游流程中无需客户进一步互动即可使用,即表示您接受该地址。

接受信号

Address Validation API 提供了许多信号,可让您知道是否应确认某个地址。

1. 验证粒度

可以接受 PREMISE 或更高的 validationGranularity,但在某些情况下,ROUTE 仍表示可送达地址。

2. 其他信号

优质地址的判定结果还应提供以下内容:

  • 没有已替换的数据。在此示例中为 hasReplacedComponents: FALSE
  • 没有推断的组成部分。在此示例中为 hasInferredComponents: FALSE

3. 美国地址信号

某些仅适用于美国地址的字段表示可以送往的高质量地址。对于可接受的美国地址,您应看到以下内容:

dpvConfirmation Y

如需详细了解 dpvConfirmation,请参阅处理美国地址

接受地址示例