Table of Contents

Google Integration

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

Credentials

Before utilizing the integration, the setup and configuration of a service account is required. It is assumed that an active project with the Google Address Validation API enabled and available.

To create the service account, you can refer to the following article, or if you have access to the gcloud CLI you can run the following:

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

After the service account has been created, it will need to be granted a Domain-wide Delegation for the scope https://www.googleapis.com/auth/cloud-platform. You can execute the following command to get the oauth2ClientId value, otherwise you can retrieve it from 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 and store it in a safe location as it will be needed 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

At application startup, you will need to register the integration with the Microsoft DI container:

builder.Services.AddGoogleAddressValidation();
Important

HybridCache is required for authentication caching. Please 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

Formatting of the PrivateKey value must be preserved (newlines included).

Important

PrivateKey should be stored encrypted at rest. See the Security for additional details.

Standard Example

With the setup and configuration now complete, you can leverage 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 and will only be true if the Country is US.

Tip

When re-validating an address, be sure to set the property PreviousResponseId value within GoogleAddressValidationRequest. The value can be retrieved from the CustomResponseData dictionary with the key responseId.

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

The isResidential value returned should be treated as a suggestion and not a guarantee.

Note

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

Note

The Suggestions collection will always be empty for responses returned as 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. You will find these results in the Warnings and Errors collections from the IAddressValidationResponse object.

Items within the Suggestion collection are not processed by the internal validator.

Edit this page