了解基本地址验证响应

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 属性，该属性会针对此特定请求返回 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。

地址质量

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

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

address 和 addressComponent 属性

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

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

geocode 属性

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

metadata 属性

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

uspsData 属性

此属性可提供有关美国邮政地址的实用信息。但是，系统并不能保证为服务验证的每个地址都完全填充了该地址。因此，您不应将此属性作为验证地址的唯一方式，而应同时检查 verdict 和 address。