Address Validation API 将地址作为输入。然后，该 API 会返回包含以下内容的响应：
用于验证整个地址以及验证每个地址组成部分（门牌号、街道名称、城市等）的判定结果。
包含 API 确定的完整地址的单个字符串。
包含 API 确定的地址的每个组成部分的各个属性。
所有缺失的地址组成部分、任何未经确认的地址组成部分以及所有无法解析的地址组成部分的列表。
地址的地理编码。
对于“美国”和“波多黎各”区域，表示地址的 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”作为地址的市行政区部分，而不是输入“Mountain View”：
{
"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
}
另请注意，由于 API 无法解析地址，因此 validationGranularity 和 geocodeGranularity 已设为 OTHER。
在 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。
这项安全措施旨在通过检测您提交的地址是否属于人为构建的地址，以及是否通过合法方式获取地址列表，以防止人为创建地址列表。这种情况应该极少发生。