Table of Contents

Google Integration

AddressValidation offers a complete integration to the Google Address Validation API to provide validation for over 39 countries.

Note

This integration does not yet support batch validation.

Credentials

Set up a service account before you use this integration. You need an active project with the Google Address Validation API enabled.

To create the service account, follow this article. If you have access to the gcloud CLI, run the following commands instead:

gcloud iam service-accounts create $SA_NAME \
    --description="Address Validation Service" \
    --display-name="Address Validation Service"

After you create the service account, grant it Domain-wide Delegation for the scope https://www.googleapis.com/auth/cloud-platform. Run the following command to get the oauth2ClientId value. You can also find it on the service accounts dashboard, under the heading OAuth 2 Client ID:

gcloud iam service-accounts describe $SA_NAME@$PROJECT_ID.iam.gserviceaccount.com

Finally, create your service account key. Store it in a safe location — you need it later.

gcloud iam service-accounts keys create /tmp/$SA_NAME-key.json \
    --iam-account=$SA_NAME@$PROJECT_ID.iam.gserviceaccount.com
Note

There are no plans to support API Key authentication at this time.

Installation

The easiest way to install the integration into a project is through NuGet:

dotnet package add VisusIO.AddressValidation.Integration.Google

Register the integration with the Microsoft DI container at application startup:

builder.Services.AddGoogleAddressValidation();
Important

HybridCache caches access tokens. See the Caching section for details.

Configuration

Configuration is bound from the AddressValidationSettings:Google section. The necessary values can be extracted from the $SA_NAME-key.json file produced in the credentials step.

{
  "AddressValidationSettings": {
    "Google": {
      "ServiceAccountEmail": "<client_email from key file>",
      "ProjectId": "<project_id from key file>",
      "PrivateKey": "<private_key from key file>",
      "ClientEnvironment": "PRODUCTION"
    }
  }
}
Property Required Description
ServiceAccountEmail Yes Maps to client_email in the service account key file
ProjectId Yes Maps to project_id in the service account key file
PrivateKey Yes Maps to private_key in the service account key file
ClientEnvironment No Accepted values: PRODUCTION, DEVELOPMENT, SANDBOX. Defaults to PRODUCTION
EndpointUriOverride SANDBOX only Custom endpoint URI; required when ClientEnvironment is SANDBOX
AuthenticationUriOverride SANDBOX only Custom authentication URI; required when ClientEnvironment is SANDBOX
Important

Preserve the formatting of the PrivateKey value, including newlines.

Important

Store PrivateKey encrypted at rest. See Security for more details.

Standard Example

After you complete setup and configuration, use the validator:

public class ValidateController
{
    private readonly IAddressValidationService<GoogleAddressValidationRequest> _validationService;

    public ValidateController(IAddressValidationService<GoogleAddressValidationRequest> validationService)
    {
        _validationService = validationService ?? throw new ArgumentNullException(nameof(validationService));
    }

    [HttpPost]
    public async Task<IActionResult> Post([FromBody] GoogleAddressValidationRequest request, CancellationToken cancellationToken = default)
    {
        IAddressValidationResponse? response = await _validationService.ValidateAsync(request, cancellationToken);
        
        return response is null
            ? new NotFoundResult()
            : response.Errors.Count > 0
                ? new UnprocessableEntityObjectResult(response)
                : new OkObjectResult(response);
    }
}
Note

EnableUspsCass is a computed property. It is true only when Country is US.

Tip

When you revalidate an address, set PreviousResponseId on GoogleAddressValidationRequest. Get this value from the CustomResponseData dictionary, under the key responseId.

{
  "address": {
    "addressLines": [
      "1600 Pennsylvania Ave NW"
    ],
    "administrativeArea": "DC",
    "locality": "Washington",
    "postalCode": "20500",
    "regionCode": "US"
  },
  "enableUspsCass": true
}
Warning

Treat the returned isResidential value as a suggestion, not a guarantee.

Note

The properties googlePlaceId, latitude, longitude, and responseId are always present in customResponseData. When USPS® CASS™ is supported for the destination (currently only US), those properties are present in customResponseData.

Note

The Suggestions collection is always empty. The Google Address Validation API does not provide address suggestions.

Note

AddressValidation runs an internal validation engine under the covers to validate both the request and the response. These results appear in the Warnings and Errors collections on the IAddressValidationResponse object.

The internal validator does not process items in the Suggestions collection.

Edit this page