Send an address validation request

Send an address validation request by issuing a POST request to one of the following endpoints:

Your request should also pass a JSON request body to the request that defines the address to validate. The following request body contains one field and three subfields:

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=API_KEY"

You can also omit locality and specify it as an element in the addressLines array:

{
  "address": {
    "regionCode": "US",
    "addressLines": ["1600 Amphitheatre Pkwy", "Mountain View, CA, 94043"]
  },
}

Address request fields

The request body consists of a single field:

  • address — a field of type PostalAddress, which must contain at least one entry in addressLines.

When sending the address field to the Address Validation API, you need only supply one field: addressLines. However, the simplest address request should contain the following subfields:

  • regionCode — Recommended. This is an optional field, but if omitted, the Address Validation API infers the region from the address. However, for best results, include the regionCode if you know it. For the list of supported regions, see supported regions.
  • addressLines — Required. An array with addresses describing the lower structure of the address.
See PostalAddress in the reference guide.

USPS CASS™ option

The United States Postal Service® (USPS®)1 maintains the Coding Accuracy Support System (CASS™) to support and certify address validation providers.

For US and PR regions only, you can enable CASS processing by setting enableUspsCass to true in the request body. For best results when using CASS, provide an address that includes the street and street number along with the city, state, and ZIP code:

{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "administrativeArea": "CA",
    "postalCode": "94043",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  },
  "enableUspsCass": true
}

  1. Google Maps Platform is a non-exclusive Licensee of the United States Postal Service®. The following trademark(s) are owned by the United States Postal Service® and used with permission: United States Postal Service®, CASS™, CASS Certified™.