Send an address validation request

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

• validateAddress (REST)
• ValidateAddress (gRPC)

Note: This documentation uses REST for its examples, but the approach is similar with gRPC.

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"]
  },
}

Try it!

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®)¹ maintains the Coding Accuracy Support System (CASS™) to support and certify address validation providers.

Note: The Address Validation API is confirmed as a CASS-Certified™ service. This means the service is confirmed for its ability to fill in missing address information, standardize it, and update it to the most current and accurate address.

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
}

Note: If you don't require CASS processing, or if you are validating addresses outside of the US and PR regions, Google does not recommend enabling this feature.

Try it!

The API Explorer lets you make sample requests so that you can get familiar with the API and the API options.

1. Select the API icon, , on the right side of the page.

2. Optionally expand Show standard parameters and set the fields parameter to the field mask.

3. Optionally edit the Request body.

4. Select Execute button. In the dialog, choose the account that you want to use to make the request.

5. In the API Explorer panel, select the expand icon, , to expand the API Explorer window.

---

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™. ↩