Send an address validation request

To validate an address using the Address Validation API, call the validateAddress method (REST) or ValidateAddress method (gRPC). This documentation uses REST for its examples, but the approach is similar with gRPC.

After you validate an address, you can optionally return information to Google about the outcome of the address validation by calling the provideValidationFeedback method (REST) or ProvideValidationFeedback method (gRPC). For information and examples, see Provide address validation feedback.

Address validation request

Validate an address by sending a POST request to the validateAddress method:

https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY

Pass a JSON body to the request defining the address to validate:

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"

The address field in the request body, of type PostalAddress, must contain at least one entry in addressLines.

• The regionCode field is optional. If omitted, the API infers the region from the address. However, for best performance, we recommend that you include the regionCode if you know it. For the list of supported regions, see supported regions.

• The total length of the address field is limited to 280 characters.

Optionally enable CASS™ when validating an address

The United States Postal Service® (USPS®)¹ maintains the Coding Accuracy Support System (CASS™) to support and certify address validation providers. A CASS Certified™ service, such as the Address Validation API, has been confirmed for its ability to fill in information missing from an address, standardize it, and update it to give you the most current and most accurate address.

For the "US" and "PR" regions only, you can optionally 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
}

You can also specify the complete address as two strings in the addressLines array:

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

Address validation response

If the request succeeds, the server responds with an HTTP 200 OK status code and a response body containing information about the validated address.

The result field of the response contains a ValidationResult object. This object includes:

• An address field, of type Address, containing detailed information about the address.

• A geocode field, of type Geocode, containing geocode information for the address.

• A verdict field, of type Verdict, containing the address validation and geocode result.

• A metadata field, of type AddressMetadata, containing the metadata for the address.

• A uspsData field, of type USPSData, containing the USPS data for the address. This data is only available for addresses in the United States and Puerto Rico.

Because the following response contains addressComplete set to true, the response indicates that this address is fully valid, so no further validation is required. If the response indicates that some part of the address is invalid, prompt your user to check and confirm their address entry.

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

Validate an updated address

In some cases, you might have to make multiple calls to the Address Validation API for a single address. For example, the user might make changes or corrections to their address after seeing the results of the first validation. You then perform a second validation on the updated address.

Each Address Validation API call returns a unique value in the responseId field of the response. If an address you're trying to validate needs to be re-validated, pass the responseId from the first validation response in the previousResponseId field for all follow-up requests to the Address Validation API.

By including the previousResponseId field in the new request, you can help us to improve the overall accuracy of the API.

For example, the response shown above includes the responseId field:

  "responseId": "de22bed8-7f52-44cb-8526-faceac57150a"

You then want to re-validate the address with a change to the street number from 1600 to 1500. When you re-validate the address, include the previousResponseId field with the value of the responseId from the first response:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1500 Amphitheatre Pkwy"]
  },
  "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}

For a request using CASS:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1500 Amphitheatre Pkwy"]
  },
  "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a",
  "enableUspsCass": true

}

The results of each subsequent call return a new value in the responseId field. However, continue to pass the value of the responseId from the first response in the previousResponseId field on all subsequent calls for updates to the address.

Error handling

The Address Validation API returns error messages as part of the response to a method call. For example, if you omit the API key from the request, the method returns:

{
  "error": {
    "code": 403,
    "message": "The request is missing a valid API key.",
    "status": "PERMISSION_DENIED"
  }
}

If you omit a required body parameter, such as addressLines, the method returns:

{
  "error": {
    "code": 400,
    "message": "Address lines missing from request.",
    "status": "INVALID_ARGUMENT"
  }
}

For more information on errors and error handling, see Errors.