了解基本地址验证响应

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

Address Validation 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
}

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

请参阅参考指南中的Verdict。

地址的粒度

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

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

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

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

地址的完整性

判定结果会将 addressComplete 属性作为高质量地址的信号返回，这具体意味着地址没有缺失、未解析或意外的组件：

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

如果地址包含缺失、未解析或意外的组件，则该字段会设置为 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 的参考文档。