验证地址

如需使用 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,包含有关地址的详细信息。

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

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

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


  1. Google Maps Platform 是美国邮政®的非独家被许可人。以下商标由美国邮政® 所有并经许可使用:美国邮政®、CASSTM、CASS 认证 TM。🎁?