了解基本地址验证响应

注意： 本文档介绍了高质量地址的地址验证响应的基本要素。如需有关处理实际地址场景和围绕更复杂的响应构建逻辑的指南，请参阅构建验证逻辑。

地址验证 API 以 JSON 对象的形式提供响应正文，其中包含两个顶层属性：

• result，类型为 ValidationResult 的对象
• responseID

{
  "result": {
    // Validation verdict.
    "verdict": {},
    // Address details determined by the API.
    "address": {},
    // The geocode generated for the input address.
    "geocode": {},
    // Information indicating if the address is a business, residence, etc.
    "metadata": {},
    // Information about the address from the US Postal Service
    // ("US" and "PR" addresses only).
    "uspsData": {},
  },
  // A unique identifier generated for every request to the API.
  "responseId": "ID"
}

本文档重点介绍 result 对象。如需了解 responseID，请参阅处理更新后的地址。

verdict 属性

要点： 使用 verdict 属性可获取地址质量的基准摘要。

verdict 属性总结了地址验证的结果，在构建地址检查逻辑时，应首先评估此属性。该属性可以返回各种字段，具体取决于输出地址的质量。例如，以下示例展示了优质地址的 verdict 属性，该属性针对此特定请求返回了 4 个字段：

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true,
  "possibleNextAction": "ACCEPT"
}

以下部分总结了 verdict 属性中的所有字段。

请参阅参考指南中的Verdict。

可能的后续操作

possibleNextAction 属性可提供 API 响应其余部分的解释性摘要，旨在帮助您确定是否应提示客户查看或修改其地址。如需了解详情，请参阅构建验证逻辑。

地址的粒度

地址粒度是指用于确定地址或地理编码具体程度的详细程度。validationGranularity 响应中的地址具体程度是判断地址是否可送达的关键信号。

verdict 属性会返回以下粒度信号：

• inputGranularity - 描述了从发送到 Address Validation API 的地址中捕获的详细程度。请求中的地址详细程度会影响验证响应中的地址详细程度。 例如，inputGranularity 低于 PREMISE 级的地址通常不会导致 validationGranularity 达到 PREMISE 级。
• validationGranularity - Address Validation API 可以完全验证地址的精细度级别。在大多数情况下，粒度级别为 PREMISE 或 SUB_PREMISE 表示地址质量良好，很可能可以送达。
• geocodeGranularity - 描述与地址关联的地理编码的详细程度。例如，Google 记录可能表明存在某个公寓号码，但无法提供大型公寓楼内该特定公寓的精确位置。在这种情况下，validationGranularity 为 SUB_PREMISE，但 geocodeGranularity 为 isPREMISE。

请参阅参考指南中的粒度。

地址的完整性

判决结果会返回 addressComplete 属性，作为高质量地址的信号，这意味着该地址没有缺失、未解析或意外的组成部分：

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE",
    "addressComplete": true,
    "possibleNextAction": "ACCEPT"
}

如果地址缺少、未解析或包含意外的组成部分，则该字段会设置为 false。

注意： 如果手动检查后发现判决中未显示 addressComplete 属性，则其值为 false。根据您的编程语言，您可以查询判决是否存在 addressComplete 属性，也可以直接查询该属性。如需查看示例，请参阅下文中的地址质量部分。

请参阅参考指南中的Verdict和地址下的 addressComplete。

地址质量

许多可能的字段都表明地址组成部分存在问题或需要调整，例如推断出的地址组成部分或缺失的地址组成部分。例如，以下 verdict 属性表示地址包含未确认的组成部分，并且缺少 addressComplete 字段：

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

请参阅参考指南中的Verdict。

address 和 addressComponent 属性

要点： 使用 address 属性获取地址格式。您可以使用其子组件 addressComponent 来调查错误，并向客户提供有关这些错误的信息。不过，请勿构建依赖于地址组成部分的特定确认级别的集成。 如需集成指南，请参阅构建验证逻辑。

address 属性可为请求中提供的已处理地址提供格式，以及地址的组件级摘要，包括地址中拼写错误的部分、替换掉的错误部分和推断出的缺失部分。

请参阅参考指南中的 Address。

addressComponent 属性是 address 的一个子组件，用于详细列出 Address Validation API 已处理的地址的元素（或组件）。该 API 通过名称、类型和确认级别来标识每个组件字段。

请参阅参考指南中的 addressComponent。

geocode 属性

要点： 当您的逻辑之前调用过 Geocoding API 时，可以使用 geocode 属性方便地获取地理编码或地点 ID。

geocode 属性表示与输入地址关联的地理编码位置。此属性提供有关位置本身（例如其地点 ID）的详细信息。

请参阅参考指南中的 Geocode。

metadata 属性

要点： 使用 metadata 属性可确定与地址关联的房产类型：住宅、邮政信箱或营业场所。

此属性可能不会针对 Address Validation API 处理的每个地址进行填充，但会指明地址是住宅地址、商家地址还是邮政信箱地址。

请参阅 Address Validation API 覆盖范围和 Address metadata 的参考文档。

uspsData 属性

要点： 使用 uspsData 属性可获取美国境内的地址的投递可信度和其他 USPS 详细信息。

此属性可为美国邮政地址提供实用信息。不过，对于该服务验证的每个地址，我们无法保证该字段会完全填充。因此，您不应仅依靠此属性来验证地址，而应同时检查 verdict 和 address。

请参阅处理美国地址和 UspsData 的参考文档。