了解基本地址验证响应

Address Validation API 以 JSON 对象的形式提供响应正文,其中包含以下两个顶级属性:

{
  "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 级别,则通常不会导致 validationGranularityPREMISE 级别。
  • validationGranularity - Address Validation API 能够完全验证地址的粒度级别。在大多数情况下,粒度级别为 PREMISESUB_PREMISE 表示可以递送的优质地址。
  • geocodeGranularity - 说明与地址关联的地理编码的详细程度。例如,Google 记录可能表明存在公寓号,但不是大型公寓综合体内该特定公寓的精确位置。在这种情况下,validationGranularitySUB_PREMISE,但为 geocodeGranularityisPREMISE`。
请参阅参考指南中的细化程度

地址的完整性

判定结果会返回 addressComplete 属性作为优质地址的信号,这意味着它没有缺失、未解析或意外的组成部分:

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

当地址包含缺失、未解析或非预期组成部分时,该字段会设置为 false

请参阅参考指南中判定地址下的 addressComplete

地址质量

一些可能的字段会指明地址组成部分存在问题或对地址组成部分进行的调整(例如推断出或缺失的地址组成部分)。例如,以下 verdict 属性表示包含未经确认的组件且缺少 addressComplete 字段的地址:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}
请参阅参考指南中的判定

addressaddressComponent 属性

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

请参阅参考指南中的 Address

addressComponent 属性是 address 的子组件,可提供 Address Validation API 已处理的地址元素(或组成部分)的详细列表。API 按名称、类型和确认级别标识提供的每个组件字段。

请参阅参考指南中的 addressComponent

geocode 属性

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

请参阅参考指南中的 Geocode

metadata 属性

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

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

uspsData 属性

此属性可提供有关美国邮政地址的实用信息。不过,我们无法保证针对服务验证的每个地址都完全填充了该地址。因此,您不应依赖此属性作为验证地址的唯一方式,而应同时检查 verdictaddress

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