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
,但为geocodeGranularity
is
PREMISE`。
请参阅参考指南中的粒度。 |
地址的完整性
判定结果返回 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
}
请参阅参考指南中的判定。 |
address
和 addressComponent
属性
address
属性用于为请求中提供的已处理地址提供格式,以及地址的组成部分级摘要,包括地址的拼写错误部分、替换的错误部分以及推断的缺失部分。
请参阅参考指南中的 Address 。 |
addressComponent
属性是 address
的子组件,用于提供 Address Validation API 已处理的地址元素(或组件)的详细列表。该 API 按组件的名称、类型和确认级别来识别提供的每个组件字段。
请参阅参考指南中的 addressComponent 。 |
geocode
属性
geocode
属性指示与输入地址关联的经过地理编码的位置。此属性提供有关营业地点本身的详细信息,例如地点 ID。
请参阅参考指南中的 Geocode 。 |
metadata
属性
对于 Address Validation API 处理的每个地址,可能不会填充此属性,但会指明地址是住宅、企业还是邮政信箱类型。
请参阅 Address Validation API 覆盖率和 Address metadata 参考文档。
|
uspsData
属性
该属性提供了美国邮政地址的实用信息。
但是,我们无法保证针对该服务验证的每个地址都完整填充数据。因此,您不应依赖此属性作为验证地址的唯一方式,而应检查 verdict
和 address
。
请参阅处理美国地址以及 UspsData 的参考文档。
|