AddressValidation

Package	Version	Downloads
VisusIO.AddressValidation
VisusIO.AddressValidation.Integration.FedEx
VisusIO.AddressValidation.Integration.Google
VisusIO.AddressValidation.Integration.PitneyBowes
VisusIO.AddressValidation.Integration.Ups

AddressValidation is a .NET library that provides a unified, provider-agnostic API for validating physical mailing addresses.

Note

AddressValidation supports trimming and native AOT deployments.

Integrations

Service	Coverage	Status
FedEx® Address Validation API	46 countries
Google Address Validation API	39 countries
Pitney Bowes Address Validation API	United States
UPS® Address Validation API	United States
USPS® Address Validation API	United States

Quick Start

Installation

Install the integration package for your chosen provider via the .NET CLI:

dotnet package add VisusIO.AddressValidation.Integration.FedEx

Registration

All integrations require HybridCache for OAuth token caching. Register it alongside the integration at application startup:

builder.Services.AddHybridCache();
builder.Services.AddFedExAddressValidation();

Configuration

Configuration is read from appsettings.json under the AddressValidationSettings:<Provider> section. For FedEx:

{
  "AddressValidationSettings": {
    "FedEx": {
      "AccountNumber": "<your account number>",
      "ClientId": "<your client id>",
      "ClientSecret": "<your client secret>",
      "ClientEnvironment": "PRODUCTION"
    }
  }
}

Property	Required	Description
AccountNumber	Yes	Your FedEx account number
ClientId	Yes	OAuth 2.0 client ID
ClientSecret	Yes	OAuth 2.0 client secret
ClientEnvironment	No	PRODUCTION, DEVELOPMENT, or SANDBOX. Defaults to DEVELOPMENT

Important

ClientId and ClientSecret should be stored encrypted at rest. See Security in the documentation for recommended approaches.

Each provider has its own set of configuration properties. See the documentation for the full reference.

Usage

Inject IAddressValidationService<TRequest> into your service or controller and call ValidateAsync:

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

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

    [HttpPost]
    public async Task<IActionResult> Post([FromBody] FedExAddressValidationRequest 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);
    }
}

Each integration package exposes its own TRequest type (e.g., FedExAddressValidationRequest, GoogleAddressValidationRequest) and a corresponding Add*AddressValidation() extension method. See the documentation for provider-specific options.

Documentation

Full documentation is available at https://ave.projects.visus.io/.