地址验证 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,
"possibleNextAction": "ACCEPT"
}
以下部分总结了 verdict
属性中的所有字段。
请参阅参考指南中的Verdict。 |
可能的后续操作
possibleNextAction
属性可提供 API 响应其余部分的解释性摘要,旨在帮助您确定是否应提示客户查看或修改其地址。如需了解详情,请参阅构建验证逻辑。
地址的粒度
地址粒度是指用于确定地址或地理编码具体程度的详细程度。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,
"possibleNextAction": "ACCEPT"
}
如果地址缺少、未解析或包含意外的组成部分,则该字段会设置为 false
。
请参阅参考指南中的Verdict和地址下的 addressComplete 。 |
地址质量
许多可能的字段都表明地址组成部分存在问题或需要调整,例如推断出的地址组成部分或缺失的地址组成部分。例如,以下 verdict
属性表示地址包含未确认的组成部分,并且缺少 addressComplete
字段:
"verdict": {
"inputGranularity": "PREMISE",
"validationGranularity": "OTHER",
"geocodeGranularity": "OTHER",
"hasUnconfirmedComponents": true,
"hasInferredComponents": true
}
请参阅参考指南中的Verdict。 |
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 的参考文档。
|