了解基本地址验证响应

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

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 的 IP 地址。在 则会影响验证响应中的地址详情级别。 例如，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 属性

要点： 使用 geocode 属性可方便地获取地理编码或 地点 ID。

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

请参阅参考指南中的 Geocode。

metadata 属性

要点 ：使用 metadata 属性来确定属性的类型 与该地址相关联的：住宅、邮政信箱或企业。

系统可能不会为 Address Validation API，但指明地址是否为住宅。 商家或邮政信箱。

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

uspsData 属性

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

此属性可提供有关美国邮政地址的实用信息。不过，我们无法保证针对验证的每个地址都完整填充此字段 。因此，您不应将此属性作为验证地址的唯一方式，而应同时检查 verdict 和 address。

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