构建验证逻辑

本文档介绍了如何构建地址检查系统，以处理来自 Address Validation API 的各种响应。其中介绍了如何构建逻辑以正确使用响应、如何调查来自 API 的其他信号，以及何时以及如何提示客户提供更多信息。

一般来说，API 响应决定了系统应通过以下方式处理地址：

• handyman 修正 - 地址质量不佳。 您应该提示用户提供更多信息。
• edit Confirm - 地址质量较高，但与输入地址相比有所变化。您可能会提示用户进行确认。
• check 接受 - 地址质量高。您可以接受系统提供的地址。

密钥用途

本文档可帮助您修改系统，以便更好地分析 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 属性，并非唯一需要检查的信号，但可作为地址质量的初步指标。每种行为类型都对应本文档中的一个部分，其中介绍了您可能还需要调查的其他信号。

您的系统行为
handyman 修正地址	verdict 的响应表明缺少应提供的重要信息。API 返回的地址可能不符合可送达质量标准。 工作流 如有必要，请调查地址组成部分。 提示客户修正地址问题。 请求验证更新后的地址。 继续使用该地址。 裁定信号 符合以下任何条件： validationGranularity 设置为 OTHER。 addressComplete 为 false。
edit 确认地址	verdict 的响应表示地址可送达，但对原始输入进行了更改：推断拼写更正的数据或可以确认的数据。 工作流 需要更正： 如有必要，请调查地址组成部分。 请求验证更新后的地址。 继续使用该地址。 无需更正： 继续使用该地址。 裁定信号 所有以下条件均适用： validationGranularity 包含 ROUTE addressComplete 为 true。 hasInferredComponents 字段为 true，或者 hasReplacedComponents 字段为 true。
check 接受地址	Address Validation API 响应表明地址质量极佳。 工作流 继续使用返回的地址。 裁定信号 所有以下条件均适用： validationGranularity 包含 PREMISE 或更高级别的芯片。 addressComplete 为 true。 没有推断或替换的组件。

实现方案指导

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

	指导	详情
风险等级	在提示更正和接受输入的地址之间进行权衡时，请考虑您的情况对容错程度的要求。	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. 验证粒度

ROUTE 或更好的 validationGranularity 是可以接受的，但 PREMISE 或 SUBPREMISE 可提供更强的可递送性信号。

2. 其他信号

在决定是否与客户确认地址输入时，判定结果还会提供以下信息，以确定要调查哪些组成部分：

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

3. 美国地址信号

某些字段仅适用于美国地址，这表明您的逻辑应与客户确认详细信息。符合以下任一条件：

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

确认地址示例

接受地址

如果判定结果表明地址可送达，并且可以在下游流程中直接使用，而无需与客户进一步互动，则您可以接受该地址。

接受信号

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

1. 验证粒度

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

2. 其他信号

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

• 无替换数据。在此示例中为 hasReplacedComponents: FALSE。
• 没有推断的组件。在此示例中为 hasInferredComponents: FALSE。

3. 美国地址信号

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

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

接受的地址示例