验证地址

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

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

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

如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。

最后更新时间 (UTC)：2023-03-16。