了解验证响应

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

Address Validation API 将地址作为输入。然后，API 会返回包含以下内容的响应：

  • 用于验证整个地址以及验证每个地址组成部分（街道编号、街道名称、城市等）的认定结果。

  • 包含由 API 确定的完整地址的单个字符串。

  • 包含地址的每个组成部分的个人属性，由 API 确定。

  • 任何缺少的地址组成部分、任何未经确认的地址组成部分以及所有无法解析的地址组成部分。

  • 地址的地理编码。

  • 对于“US”和“PR”区域，其地址的 USPS 数据。

使用 API 响应，您可以确保地址存在且符合您需求的质量。如果 API 的响应表明某个地址不完整或不正确，您可以提示用户更新地址。用户完成更新后，请使用 API 验证更新后的地址。

本文档介绍了如何处理 API 响应，以及如何处理 API 检测到的输入地址中的一些常见错误。

注意：如需更好地了解 API 如何处理输入地址的错误，请试用演示版。该演示可让您输入地址，然后以可视化图表内容和 JSON 对象的形式查看响应。

关于响应

代表验证响应的 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 属性包含以下属性：

  • inputGranularity

    表示通过解析地址但未验证所确定的输入地址的粒度。例如，这些属性可以包含 PREMISE（对于解析为建筑级结果的地址）、BLOCK（对于解析为块的地址）或 ROUTE（对于细化到路线的地址，例如街道、道路或高速公路）。

  • validationGranularity

    指明 API 可以验证地址的粒度。请注意，这是已验证地址的粒度，而不是 address.formattedAddress 或 address.postalAddress 中返回的地址的粒度。

  • geocodeGranularity

    指明生成的地理编码位置的粒度。

  • addressComplete

    如果 API 认为地址完整，则为 true。也就是说，address 属性中未列出任何未解析的令牌（地址字符串或符号）、意外的地址组成部分或缺失的地址组成部分。

  • hasUnconfirmedComponents、hasInferredComponents、hasReplacedComponents

    用于指明至少一个地址组成部分无法分类或验证、推断（添加）至少一个不在地址中的地址组成部分且是否至少替换了一个地址组成部分的属性。

对包含推断组件的完整地址做出判定

以下示例展示了包含推断组成部分的完整地址的 verdict 属性：

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

请注意，粒度解析为前提并且地址是完整的，但 API 推断出某些组件的值。在此示例中，输入地址中省略了美国邮政编码（API 能够根据该地址的其余部分推断出该地址）。如需查看更完整的示例，请参阅推断的地址组成部分。

包含未确认组成部分的地址的认定结果

虽然即使存在推断组成部分，输入地址也会被视为完整地址，但如果有任何未解析的地址令牌、意外的地址组成部分或地址组成部分缺失，则相应地址会被视为未完成。

在下一个示例中，hasUnconfirmedComponents 设置为 true，以表示该地址至少有一个无法分类或验证的地址组成部分：

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

在这种情况下，已验证且经过地理编码的地址的粒度设置为 OTHER，并且响应中会忽略 addressComplete 属性，以表明地址不完整。如需查看更完整的示例，请参阅地址缺失和未经确认的地址。

示例回复

以下部分显示了针对不同场景（包括完整地址和常见地址验证错误）的响应。在这些示例中：

  • 如果响应包含设置为 true 的 addressComplete，则表示 API 已确定输入地址的质量较高。

  • 如果 Address Validation API 指示它对地址进行了重大更改，或者地址存在错误，那么您需要与客户确认返回的地址。

提供优质地址的完整地址

当 API 确定某个地址是完整的地址后，便会在响应的 verdict 属性中将 addressComplete 设置为 true。

例如：

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

响应的 address 属性包含由 API 确定的地址的所有详细信息。响应中包含 formattedAddress 属性，该属性包含经过更正和验证的地址（单行字符串）。我们建议您为完整地址使用 formattedAddress 字段中包含的单行地址，因为该地址可能包含美国的细微更正和增补信息，例如大写字母和 ZIP+4。

address 属性还会指明每个地址组成部分是否存在任何问题（具体由 API 确定）。对于每个组成部分（例如街道名称或城市），address 字段都包含一个 confirmationLevel 字段。可能的值包括：

  • CONFIRMED 表示 API 能够验证该组件是否存在
  • UNCONFIRMED_BUT_PLAUSIBLE 表示组件无法确认，但可能可信
  • UNCONFIRMED_AND_SUSPICIOUS 表示该组件未经确认，可能是错误的。

例如：

"address": {
  // Validated address as a single string.
  "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
  // Individual validated address components.
  "postalAddress": {
    "regionCode": "US",
    "languageCode": "en",
    "postalCode": "94043-1351",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1600 Amphitheatre Pkwy"
    ]
  },
  // Validation results for each component.
  "addressComponents": [
    {
      "componentName": {
        "text": "1600",
        "languageCode": "en"
      },
      "componentType": "street_number",
      "confirmationLevel": "CONFIRMED"
    },
    {
      "componentName": {
        "text": "Amphitheatre Pkwy",
        "languageCode": "en"
      },
      "componentType": "route",
      "confirmationLevel": "CONFIRMED"
    },
    …
  ]
  // List of any missing, unconfirmed, or unresolved address components.
  // These properties are omitted from the response if they are empty.
  "missingComponentTypes": [],
  "unconfirmedComponentTypes": [],
  "unresolvedTokens": []
}

推断的地址组成部分

如果输入地址不包含完整地址，则 API 会尝试将任何缺少的地址组成部分添加到响应中。这些添加的组件被称为推断的地址组件。

例如，您可以使用以下输入地址：

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1600 Amphitheatre Pkwy"]
  }
}

请注意，此输入地址未包含美国邮政编码。该 API 可以根据输入地址的其余部分确定邮政编码，并将其添加到响应中。

在此示例中，verdict 属性将 hasInferredComponents 设置为 true，以表示 API 推断出一个或多个组件的值。不过，由于这是一个很小的更正，API 将 addressComplete 设置为 true，以表明输入地址仍具有较高的质量。

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

对于推断出的组件，该 API 会在 address 属性的 addressComponents 数组的相应元素中将 inferred 设置为 true：

{
  "componentName": {
    "text": "94043"
  },
  "componentType": "postal_code",
  "confirmationLevel": "CONFIRMED",
  "inferred": true
}

输入地址存在拼写错误

输入地址中的拼写错误（例如城市或州/省/自治区/直辖市的拼写错误）很常见。例如，您可以输入“MontainView”作为地址的市行政区部分，而不是“山景城”：

{
  "address": {
    "regionCode" : "US",
    "locality" : "MontainView",
    "addressLines" : ["1600 Amphitheatre Pkwy"]
  }
}

在此示例中，verdict 属性表示它推断了一个或多个组件的值，并将 addressComplete 设置为 true 以表明输入地址的质量较高，因为它仍能解析地址：

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

API 会尝试将地址解析为正确的拼写。address 属性的 addressComponents 数组中的相应地址元素会在 text 属性中显示更正后的字符串，并且还会通过将 spellCorrected 设置为 true 来指示存在拼写错误：

{
    "componentName": {
        "text": "Mountain View",
        "languageCode": "en"
    },
    "componentType": "locality",
    "confirmationLevel": "CONFIRMED",
    "spellCorrected": true
}

地址组成部分缺失和未经确认

用户可能会省略部分输入地址。在下面的示例中，用户输入的是门牌号，而不是街道名：

{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "addressLines": ["1600"]
  }
}

在这种情况下，判定结果省略了 addressComplete 属性，因为缺少的信息过多，导致 API 无法解析地址。该 API 还会将 hasUnconfirmedComponents 设置为 true，以指明该地址包含未经确认的组成部分：

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

另请注意，validationGranularity 和 geocodeGranularity 设置为 OTHER，因为 API 无法解析地址。

在 address 属性的 addressComponents 数组中，API 会将门牌号组件标记为 UNCONFIRMED_BUT_PLAUSIBLE：

{
  "componentName": {
    "text": "1600",
    "languageCode": "en"
  },
  "componentType": "street_number",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
}

最后，API 会使用输入中缺少的组件和它无法确认的组件填充 address 属性的 missingComponentTypes 和 unconfirmedComponentTypes 数组：

"missingComponentTypes": [
  "route",
  "postal_code"
],
"unconfirmedComponentTypes": [
  "street_number"
]

了解不同的粒度值

通过响应中的粒度值，您可以深入了解该 API 解析地址的粗略程度或精确程度。例如，您可以使用以下输入地址：

{
  "address": {
    "regionCode": "US",
    "locality": "Northampton",
    "addressLines": ["6 South Main Street APT 456"]
  }
}

在此示例中，API 在 USPS 数据库中找到了门牌号，但找不到公寓号。此外，API 无法查找门牌号“6”的精确地理编码，但可以找到“4”和“8”的精确地理编码。在这种情况下，该 API 会返回以下 verdict：

"verdict": {
    "inputGranularity": "SUB_PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE_PROXIMITY",
    "addressComplete": true,
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

在此响应中：

  • inputGranularity 为 SUB_PREMISE，因为 API 可以将输入地址解析为公寓级别。inputGranularity 仅适用于解析输入地址的 API 功能。它不适用于对地址执行的验证。

  • validationGranularity 为 PREMISE，因为 API 可以验证是否存在门牌号“6”，但不能验证“APT 456”。虽然该 API 无法验证“APT 456”，但它仍包含在输出 formattedAddress 和 postalAddress 字段中。

  • geocodeGranularity 为 PREMISE_PROXIMITY，因为此 API 只能插入地理编码位置，而找不到确切的输入街道地址的地理编码。

由 USPS 检测到的人为创建地址

当 USPS 发现人为创建的地址时，响应的 uspsData 属性的 errorMessage 字段包含描述问题的错误消息。例如：

"uspsData": {
    "errorMessage": "AMS API processing was terminated due to the detection of
    what is determined to be an artificially created address. No address beyond
    this point has been validated and/or processed. If you believe this address
    was identified in error, please contact your Vendor."
}

向该 API 发送人为创建的地址可能会导致您无法访问 USPS 数据库。收到此错误消息后，我们建议您调查地址的来源，以防向该 API 发送更多虚假地址。

此安全措施旨在检测提交的地址似乎是人为创建的，并且并非合法获得，从而防止人为创建地址列表。这种情况很少见。