了解基本地址验证响应

Address Validation API 响应包含以下顶级属性：

{
  // Address details determined by the API.
  "address": {},
  // Validation verdict.
  "verdict": {},
  // 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"
}

verdict 属性

verdict 属性总结了地址验证的结果，并且应该是构建地址检查逻辑时要评估的第一个属性。该属性可以返回各种字段，具体取决于输出地址的质量。例如，以下内容显示了质量良好的地址的 verdict 属性，该属性针对此特定请求返回了以下字段：

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "possibleNextAction": "ACCEPT",
  "addressComplete": true,
  "hasUnconfirmedComponents": false,
  "hasInferredComponents": true,
  "hasReplacedComponents": false
}

以下部分总结了 verdict 属性中的所有字段。

请参阅参考指南中的 Verdict 。

地址的粒度

地址粒度是指在确定地址或地理编码的特异性时使用的详细程度。validationGranularity 响应中的地址特异性是地址是否可送达的关键信号。

verdict 属性会返回以下粒度信号：

  • inputGranularity ：描述从发送到 Maps JavaScript API 中“地址验证”的地址捕获的详细程度。请求中的地址详细程度会影响验证响应中的地址详细程度。 例如，inputGranularity 低于 PREMISE 级别的地址通常不会导致 validationGranularity 达到 PREMISE 级别。
  • validationGranularity ：Maps JavaScript API 中地址验证可以完全验证地址的粒度级别。在大多数情况下， 粒度级别为 PREMISE 或 SUB_PREMISE 表示地址质量良好， 可能可以送达。
  • geocodeGranularity ：描述与地址关联的地理编码的详细程度。例如，Google 记录可能表明存在公寓号码，但不会表明大型公寓楼内该特定公寓的确切位置。在这种情况下， validationGranularity 为 SUB_PREMISE，但 geocodeGranularity 为 PREMISE。
请参阅参考指南中的 Granularity Granularity。

地址的完整性

判决会返回 addressComplete 属性作为高质量地址的信号，具体而言，这意味着该地址没有缺失、未解析或意外的组成部分：

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

如果地址缺少、未解析或意外的组成部分，则该字段会设置为 false。

请参阅参考指南中 Verdict和 Address下的addressComplete。

地址质量

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

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

可能的后续操作

possibleNextAction 判决字段提供了 API 响应的解释性摘要，旨在 帮助确定可能采取的后续操作。此字段派生自 API 响应中的其他字段，不应被视为地址准确性或可送达性的保证。

address 和 addressComponent 属性

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

请参阅参考指南中的 Address。

addressComponent 属性是 address 的子组件，它提供了 Maps JavaScript API 中 Address Validation 已处理的地址的元素（或组成部分）的详细列表。API 会按名称、类型和确认级别标识每个组成部分字段。

请参阅参考指南中的 addressComponent。

geocode 属性

geocode

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

请参阅参考指南中的 Geocode。

metadata 属性

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

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

uspsData 属性

此属性提供有关美国邮政地址的实用信息。 不过，对于服务验证的每个地址，此属性不保证会完全填充。因此，您不应仅依赖此属性来验证地址，而应同时检查 verdict 和 address。

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