Provide address validation feedback

To help us improve the quality of the Address Validation API, you can optionally provide feedback to Google to let us know if a validated address is accepted by the end user. This feedback helps us to improve the overall accuracy of the API.

Address validation feedback request

To provide feedback after a call to an address validation method, make a call to the provideValidationFeedback method (REST) or ProvideValidationFeedback method (gRPC). The following example makes a POST request to the REST API:

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

Pass a JSON body to the POST request defining the conclusion of the address validation:

{
  "conclusion": "VALIDATED_VERSION_USED",
  "responseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}

Where:

• The conclusion field should reflect the actual outcome of the validation.

  In this example, you pass VALIDATED_VERSION_USED as the value of the conclusion field to indicate that the address you ended up using was the one returned by the API.

  If you eventually use the address provided by the end user, pass USER_VERSION_USED.

  For all possible values for conclusion, see ValidationConclusion.

• The responseId field specifies which address validation results you are providing feedback for. This value must be the same as the responseId value returned by a previous call to the validateAddress method.

  For examples on calling the validateAddress method, see Validate an address.

How to set responseID

Each Address Validation API call returns a unique value in the responseId field of the response.

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

If an address you're trying to validate needs to be re-validated, pass the responseId from the first response in the previousResponseId field in all follow-up requests to the Address Validation API.

Each response to these follow-up requests contains a new responseId, but continue to use the value from the first responseId in the previousResponseId until the validation is done.

For more information on validating an updated address, see Validate an updated address.

At the end of a series of validations, we recommend you make a call to the Provide Validation Feedback API to let us know the final outcome of all the validations. Pass the responseId from the first response in the Provide Validation Feedback API request.

This sequence diagram shows the desired flow: