了解基本地址验证响应

注意 ：本文档介绍了优质地址的地址验证响应的基本元素。如需获取有关如何使用实际地址场景以及围绕更复杂的响应构建逻辑的指导，请参阅构建验证逻辑。

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 属性中的所有字段。

请参阅参考指南中的认定结果。

地址的细化程度

地址粒度是指确定地址或地理编码的具体性时使用的详细程度。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 属性，也可以直接查询该属性。有关示例，请参阅下文的地址质量。

请参阅参考指南中认定结果和地址下的 addressComplete。

地址质量

有许多可能的字段表示地址组成部分存在问题或对其进行了调整，例如地址组成部分推断或缺失。例如，以下 verdict 属性表示地址包含未经确认的组成部分但缺少 addressComplete 字段：

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

请参阅参考指南中的判定。

address 和 addressComponent 属性

要点 ：使用 address 属性可设置地址格式。请使用其子组件 addressComponent 调查错误并向客户提供这些错误的相关信息。但是，请不要构建依赖地址组成部分的特定确认级别。如需获取集成方面的指导，请参阅构建验证逻辑。

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

请参阅参考指南中的 Address。

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

请参阅参考指南中的 addressComponent。

geocode 属性

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

geocode 属性指示与输入地址关联的经过地理编码的位置。此属性提供有关营业地点本身的详细信息，例如地点 ID。

请参阅参考指南中的 Geocode。

metadata 属性

要点 ：使用 metadata 属性来确定与地址关联的房源类型：住宅、邮政信箱或商家。

对于 Address Validation API 处理的每个地址，可能不会填充此属性，但会指明地址是住宅、企业还是邮政信箱类型。

请参阅 Address Validation API 覆盖率和 Address metadata 参考文档。

uspsData 属性

要点 ：使用 uspsData 属性可获取送货置信度以及有关美国地址的其他 USPS 详细信息。

该属性提供了美国邮政地址的实用信息。 但是，我们无法保证针对该服务验证的每个地址都完整填充数据。因此，您不应依赖此属性作为验证地址的唯一方式，而应检查 verdict 和 address。

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