Table of Contents

AddressValidation

AddressValidation is a .NET library. It validates physical addresses through a simple, streamlined process.

Note

AddressValidation supports trimming and native AOT deployments.

Integrations

AddressValidation comes with several service integrations pre-built and ready to use. Reference the table below for details on available integrations.

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

If no integration exists for the service you want, open a feature request. You can also build a custom integration.

Batch Validation

IBatchAddressValidationService<TRequest> is an opt-in interface for integrations whose provider API natively supports validating multiple addresses in a single call. Where available, submit a list of requests and get back a positionally-aligned list of responses, instead of one call per address.

FedEx is currently the only integration that implements it. If you are building a custom integration against a provider that supports multi-address requests, see the Batch Validation section of the custom integration guide.

Caching

All AddressValidation integrations require HybridCache to cache access tokens and maximize performance. Register it at application startup:

builder.Services.AddHybridCache();

By default, HybridCache uses an in-process (L1) cache. This cache is sufficient for single-server deployments, local development, and testing environments. For multi-server deployments, also register an IDistributedCache provider as the distributed (L2) cache layer. See the documentation for available providers.

Note

Currently only access tokens are cached. Caching of requests and responses is not natively supported for two reasons:

  • Privacy regulations: address data constitutes personally identifiable information (PII) subject to GDPR and CCPA.
  • Provider Terms of Service: Google, Pitney Bowes, and UPS all restrict caching of API responses. Google and Pitney Bowes permit temporary caching for up to 30 days under specific conditions (user consent, secure storage, no cross-user reuse). UPS prohibits all use of response data not explicitly permitted by its agreement.

Security

Important

AddressValidation does not provide a way to encrypt or decrypt sensitive information. Read this section carefully.

The pre-built integrations use an IConfiguration instance to read their configuration values. Some of these values, such as client secrets, contain sensitive information. Secure this information properly.

Several options can store this information securely:

For other implementations, use a custom configuration provider.

Instrumentation

All integrations emit OpenTelemetry-compatible traces and metrics via System.Diagnostics. This covers address validation calls and access token fetches and cache results. See Instrumentation for setup steps and the full list of activities and metrics. It also includes export examples for popular observability backends.

Edit this page