如需使用 Address Validation API 验证地址，请调用 validateAddress 方法 (REST) 或 ValidateAddress 方法 (gRPC)。本文档使用 REST 作为示例，但此方法与 gRPC 类似。
验证地址后，您可以选择通过调用 provideValidationFeedback 方法 (REST) 或 ProvideValidationFeedback 方法 (gRPC) 向 Google 返回有关地址验证结果的信息。如需了解相关信息和示例，请参阅提供地址验证反馈。
地址验证请求
通过向 validateAddress 方法发送 POST 请求来验证地址：
https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY
将 JSON 正文传递给定义要验证的地址的请求：
curl -X POST -d '{
"address": {
"regionCode": "US",
"locality": "Mountain View",
"addressLines": ["1600 Amphitheatre Pkwy"]
}
}' \
-H 'Content-Type: application/json' \
"https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY"
请求正文中类型为 postalAddress 的 address 字段必须至少包含一个 addressLines 条目。
regionCode字段为可选字段。如果省略此参数，API 会通过地址推断区域。但是，为实现最佳性能，建议您添加regionCode（如果您知道）。如需查看支持的区域列表，请参阅支持的区域。address字段的总长度不得超过 280 个字符。
（可选）验证地址时启用 CASSTM
美国邮政服务 (USPS®)1 维护着编码准确性支持系统 (CASSTM)，以便为地址验证提供商提供支持和认证。我们确认了 CASS CertifiedTM 服务（例如 Address Validation API）能够填充地址中缺失的信息，对其进行标准化并更新这些信息，以便为您提供最新、最准确的地址。
仅适用于“美国”和“公关”区域，您可以选择在请求正文中将 enableUspsCass 设置为 true，从而启用 CASS 处理。
为了在使用 CASS 时获得最佳效果，请提供包含街道和门牌号以及城市、州和邮政编码的地址：
{
"address": {
"regionCode": "US",
"locality": "Mountain View",
"administrativeArea": "CA",
"postalCode": "94043",
"addressLines": ["1600 Amphitheatre Pkwy"]
},
"enableUspsCass": true
}
您还可以将完整地址指定为 addressLines 数组中的两个字符串：
{
"address": {
"regionCode": "US",
"addressLines": ["1600 Amphitheatre Pkwy", "Mountain View, CA, 94043"]
},
"enableUspsCass": true
}
地址验证响应
如果请求成功，服务器将返回一个 HTTP 200 OK 状态代码以及一个包含经过验证的地址的响应正文。
响应的 result 字段包含 ValidationResult 对象。该对象包含以下内容：
address字段，类型为 Address，包含有关地址的详细信息。geocode字段，其类型为 Geocode，包含地址的地理编码信息。verdict字段，类型为 Verdict，其中包含地址验证和地理编码结果。metadata字段，类型为 AddressMetadata，包含地址的元数据。uspsData字段，其类型为 USPSData，其中包含地址的 USPS 数据。此数据仅适用于美国和波多黎各的地址。
由于以下响应包含设置为 true 的 addressComplete，则该响应表明此地址是完全有效的，因此无需进一步验证。如果响应表明地址的某些部分无效，请提示用户检查并确认其地址输入。
{
"result": {
"verdict": {
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"addressComplete": true,
"hasInferredComponents": true
},
"address": {
"formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
"postalAddress": {
"regionCode": "US",
"languageCode": "en",
"postalCode": "94043-1351",
"administrativeArea": "CA",
"locality": "Mountain View",
"addressLines": [
"1600 Amphitheatre Pkwy"
]
},
"addressComponents": [
{
"componentName": {
"text": "1600",
"languageCode": "en"
},
"componentType": "street_number",
"confirmationLevel": "CONFIRMED"
},
{
"componentName": {
"text": "Amphitheatre Parkway",
"languageCode": "en"
},
"componentType": "route",
"confirmationLevel": "CONFIRMED"
},
{
"componentName": {
"text": "Mountain View",
"languageCode": "en"
},
"componentType": "locality",
"confirmationLevel": "CONFIRMED"
},
{
"componentName": {
"text": "USA",
"languageCode": "en"
},
"componentType": "country",
"confirmationLevel": "CONFIRMED"
},
{
"componentName": {
"text": "94043"
},
"componentType": "postal_code",
"confirmationLevel": "CONFIRMED",
"inferred": true
},
{
"componentName": {
"text": "CA",
"languageCode": "en"
},
"componentType": "administrative_area_level_1",
"confirmationLevel": "CONFIRMED",
"inferred": true
},
{
"componentName": {
"text": "1351"
},
"componentType": "postal_code_suffix",
"confirmationLevel": "CONFIRMED",
"inferred": true
}
]
},
"geocode": {
"location": {
"latitude": 37.4223878,
"longitude": -122.0841877
},
"plusCode": {
"globalCode": "849VCWC8+X8"
},
"bounds": {
"low": {
"latitude": 37.4220699,
"longitude": -122.084958
},
"high": {
"latitude": 37.4226618,
"longitude": -122.0829302
}
},
"featureSizeMeters": 116.538734,
"placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g",
"placeTypes": [
"premise"
]
},
"metadata": {
"business": false,
"poBox": false
},
"uspsData": {
"standardizedAddress": {
"firstAddressLine": "1600 AMPHITHEATRE PKWY",
"cityStateZipAddressLine": "MOUNTAIN VIEW CA 94043-1351",
"city": "MOUNTAIN VIEW",
"state": "CA",
"zipCode": "94043",
"zipCodeExtension": "1351"
},
"deliveryPointCode": "00",
"deliveryPointCheckDigit": "0",
"dpvConfirmation": "Y",
"dpvFootnote": "AABB",
"dpvCmra": "N",
"dpvVacant": "N",
"dpvNoStat": "Y",
"carrierRoute": "C909",
"carrierRouteIndicator": "D",
"postOfficeCity": "MOUNTAIN VIEW",
"postOfficeState": "CA",
"fipsCountyCode": "085",
"county": "SANTA CLARA",
"elotNumber": "0103",
"elotFlag": "A",
"addressRecordType": "S"
}
},
"responseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}
验证更新后的地址
在某些情况下，您可能必须针对单个地址多次调用 Address Validation API。例如，用户在看到第一个验证的结果之后，可能会更改或更正地址。然后，您可以对更新后的地址执行第二次验证。
每个 Address Validation API 调用都会在响应的 responseId 字段中返回一个唯一值。如果您尝试重新验证的地址需要重新验证，请将 previousResponseId 字段中所有后续验证请求的 responseId 传递给 Address Validation API。
通过在新请求中添加 previousResponseId 字段，您可以帮助我们提高 API 的整体准确性。
例如，上述响应包括 responseId 字段：
"responseId": "de22bed8-7f52-44cb-8526-faceac57150a"
然后，您想将街道地址从 1600 更改为 1500，从而重新验证地址。重新验证地址时，请添加 previousResponseId 字段以及第一个响应中 responseId 的值：
{
"address": {
"regionCode" : "US",
"locality" : "Mountain View",
"addressLines" : ["1500 Amphitheatre Pkwy"]
},
"previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}
对于使用 CASS 的请求：
{
"address": {
"regionCode" : "US",
"locality" : "Mountain View",
"addressLines" : ["1500 Amphitheatre Pkwy"]
},
"previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a",
"enableUspsCass": true
}
每次后续调用的结果都会在 responseId 字段中返回一个新值。不过，对于对地址的更新的所有后续调用，请继续从 previousResponseId 字段中的第一个响应的 responseId 传递值。
错误处理
Address Validation API 会在对方法调用的响应中返回错误消息。例如，如果您在请求中省略 API 密钥，该方法会返回：
{
"error": {
"code": 403,
"message": "The request is missing a valid API key.",
"status": "PERMISSION_DENIED"
}
}
如果省略必需的正文参数（例如 addressLines），该方法会返回：
{
"error": {
"code": 400,
"message": "Address lines missing from request.",
"status": "INVALID_ARGUMENT"
}
}
如需详细了解错误和错误处理，请参阅错误。
-
Google Maps Platform 是美国邮政®的非独家被许可人。以下商标由美国邮政® 所有并经许可使用：美国邮政®、CASSTM、CASS 认证 TM。🎁?