验证地址

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

如需使用 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"

请求正文中类型为 postalAddressaddress 字段必须至少包含一个 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,包含有关地址的详细信息。

  • 类型为 Geocodegeocode 字段,其中包含地址的地理编码信息。

  • verdict 字段,类型为 Verdict,其中包含地址验证和地理编码结果。

  • metadata 字段,类型为 AddressMetadata,包含地址的元数据。

  • uspsData 字段,其类型为 USPSData,其中包含地址的 USPS 数据。此数据仅适用于美国和波多黎各的地址。

由于以下响应包含设置为 trueaddressComplete,因此该响应表明此地址是完全有效的,因此无需进一步验证。如果响应表明地址的某些部分无效,请提示用户检查并确认其地址条目。

{
  "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"
  }
}

如需详细了解错误和错误处理,请参阅错误

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2023-02-02 UTC.