构建验证逻辑

本文档介绍了一个用于构建地址检查系统的流程，该系统可以处理 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 的响应表明缺少应提供的重要信息。API 返回的地址可能 无法投递。

工作流程

  1. 根据需要调查地址组成部分。
  2. 提示客户修正地址问题。
  3. 请求验证更新后的地址。
  4. 继续使用地址。

判定信号

满足以下任一 条件：
确认地址

The response from the verdict indicates a deliverable address, but has made changes to the original input: inferring data that is either spell corrected, or data that can be confirmed.

工作流程

  1. 需要更正：
    1. 根据需要调查地址组成部分。
    2. 请求验证更新后的地址。
    3. 继续使用地址。
  2. 无需更正：
  3. 继续使用地址。

判定信号

满足以下所有 条件：
接受地址

Address Validation API 响应表明地址质量优异。

工作流程

继续使用返回的地址。

判定信号

满足以下所有 条件：

实现方案指导

在设计系统如何响应地址验证信号时，以下建议可帮助您构建更有效的响应模型。不过，这些建议仅供参考，请注意，您的实现应适合您的业务模式。

指导 详情
风险等级

在提示客户进行更正和接受输入的地址之间进行权衡时，请考虑您的情况的容忍度。

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

例如，如果地址的街道号码未经确认，您仍然可以接受该地址。另一方面，如果您的业务运营需要 更高的地址准确性，您可能需要提示用户。如需了解可能属于任一类别的示例，请参阅接受地址 - 示例中的“非美国未确认街道号码”。
接受地址

如果客户未响应提示，最好允许系统接受原始条目 。

在这些情况下，客户可能输入了系统中没有的地址，例如新建筑的地址。

修正地址

当结果明确表明地址无法投递时，请修正地址。然后，您的系统可以提示客户提供必要的信息，之后您重新发出工作流程以获取可投递的地址。

修正信号

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

如需详细了解 dpvConfirmation，请参阅 处理美国地址。
地址响应 包含 missingComponentTypes 字段，其值为 subpremise.

确认地址示例

接受地址

当判定提供高度的信心表明地址可投递，并且可以在下游流程中无需进一步的客户互动即可使用时，您需要接受地址。

接受信号

Address Validation API 提供了许多信号，可让您了解是否应确认地址。

1. 验证粒度

validationGranularity 为 PREMISE 或更高级别是可以接受的，但在某些情况下，ROUTE 仍然表示地址可投递。

2. 其他信号

高质量地址的判定还应提供以下信息：

  • 没有替换的数据 。在这种情况下，hasReplacedComponents: FALSE。
  • 没有推断的组成部分 。在这种情况下，hasInferredComponents: FALSE。

3. 美国地址信号

某些仅适用于美国地址的字段表明地址质量较高，可以投递。对于可接受的美国地址，您应看到以下内容：

dpvConfirmation Y

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

接受地址示例