How to Integrate Address APIs in C#: Verification, Autocomplete & Geocoding

Authentication & Reusable Client

Let's start by building a reusable SthanApiClient class that handles authentication and token caching. This class implements IDisposable to properly clean up the underlying HttpClient.

Step 1: Define Response Models

All Sthan.io API responses are wrapped in a standard envelope. Define record types to deserialize them:

using System.Text.Json.Serialization;

// Standard API response envelope
public record SthanApiResponse<T>
{
    [JsonPropertyName("id")]
    public string Id { get; init; } = "";

    [JsonPropertyName("result")]
    public T? Result { get; init; }

    [JsonPropertyName("statusCode")]
    public int StatusCode { get; init; }

    [JsonPropertyName("isError")]
    public bool IsError { get; init; }

    [JsonPropertyName("errors")]
    public List<string> Errors { get; init; } = new();
}

// Auth token response
public record AuthTokenResult
{
    [JsonPropertyName("access_token")]
    public string AccessToken { get; init; } = "";

    [JsonPropertyName("expiration")]
    public DateTime Expiration { get; init; }
}

Step 2: Build the API Client

This client handles token acquisition, caching, and provides typed methods for each endpoint:

using System.Net.Http.Headers;
using System.Text.Json;

public class SthanApiClient : IDisposable
{
    private readonly HttpClient _httpClient;
    private readonly string _profileName;
    private readonly string _profilePassword;
    private string? _accessToken;
    private DateTime _tokenExpiration;

    private static readonly JsonSerializerOptions JsonOptions = new()
    {
        PropertyNameCaseInsensitive = true
    };

    public SthanApiClient(string profileName, string profilePassword)
    {
        _profileName = profileName;
        _profilePassword = profilePassword;
        _httpClient = new HttpClient
        {
            BaseAddress = new Uri("https://api.sthan.io")
        };
    }

    public async Task<string> GetTokenAsync()
    {
        // Return cached token if still valid (with 30s buffer)
        if (_accessToken is not null
            && DateTime.UtcNow < _tokenExpiration.AddSeconds(-30))
        {
            return _accessToken;
        }

        var request = new HttpRequestMessage(HttpMethod.Get, "/Auth/Token");
        request.Headers.Add("profileName", _profileName);
        request.Headers.Add("profilePassword", _profilePassword);

        var response = await _httpClient.SendAsync(request);
        response.EnsureSuccessStatusCode();

        var json = await response.Content.ReadAsStringAsync();
        var result = JsonSerializer.Deserialize<SthanApiResponse<AuthTokenResult>>(
            json, JsonOptions);

        if (result?.IsError == true || result?.Result is null)
        {
            throw new InvalidOperationException(
                $"Auth failed: {string.Join(", ", result?.Errors ?? new())}");
        }

        _accessToken = result.Result.AccessToken;
        _tokenExpiration = result.Result.Expiration;
        return _accessToken;
    }

    public async Task<T?> CallApiAsync<T>(string endpoint)
    {
        var token = await GetTokenAsync();

        var request = new HttpRequestMessage(HttpMethod.Get, endpoint);
        request.Headers.Authorization =
            new AuthenticationHeaderValue("Bearer", token);

        var response = await _httpClient.SendAsync(request);
        response.EnsureSuccessStatusCode();

        var json = await response.Content.ReadAsStringAsync();
        var result = JsonSerializer.Deserialize<SthanApiResponse<T>>(
            json, JsonOptions);

        if (result?.IsError == true)
        {
            throw new InvalidOperationException(
                $"API error: {string.Join(", ", result.Errors)}");
        }

        return result!.Result;
    }

    public void Dispose() => _httpClient.Dispose();
}

Step 3: Quick Test

Verify authentication works with a simple console app:

using var client = new SthanApiClient(
    "YOUR_PROFILE_NAME",
    "YOUR_PROFILE_PASSWORD"
);

var token = await client.GetTokenAsync();
Console.WriteLine($"Token acquired, expires: {token[..20]}...");

Address Verification

The Address Verification API validates, corrects, and standardizes US addresses to USPS format. It returns detailed component data including deliverability status.

Endpoint

GET /AddressVerification/Usa/Single/{address}

Response Model

public record VerificationResult
{
    [JsonPropertyName("inputAddress")]
    public string InputAddress { get; init; } = "";

    [JsonPropertyName("streetAddress")]
    public string StreetAddress { get; init; } = "";

    [JsonPropertyName("city")]
    public string City { get; init; } = "";

    [JsonPropertyName("state")]
    public string State { get; init; } = "";

    [JsonPropertyName("zipCode")]
    public string ZipCode { get; init; } = "";

    [JsonPropertyName("zip4")]
    public string Zip4 { get; init; } = "";

    [JsonPropertyName("county")]
    public string County { get; init; } = "";

    [JsonPropertyName("dpvConfirmation")]
    public string DpvConfirmation { get; init; } = "";

    [JsonPropertyName("isValid")]
    public bool IsValid { get; init; }
}

C# Implementation

var address = "1600 pennsylvania ave nw washington dc";
var encoded = Uri.EscapeDataString(address);
var result = await client.CallApiAsync<VerificationResult>(
    $"/AddressVerification/Usa/Single/{encoded}");

if (result is not null)
{
    Console.WriteLine($"Valid: {result.IsValid}");
    Console.WriteLine($"Street: {result.StreetAddress}");
    Console.WriteLine($"City: {result.City}");
    Console.WriteLine($"State: {result.State}");
    Console.WriteLine($"ZIP: {result.ZipCode}-{result.Zip4}");
    Console.WriteLine($"County: {result.County}");
    Console.WriteLine($"DPV: {result.DpvConfirmation}");
}

Example Response

{
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "result": {
        "inputAddress": "1600 pennsylvania ave nw washington dc",
        "streetAddress": "1600 PENNSYLVANIA AVE NW",
        "city": "WASHINGTON",
        "state": "DC",
        "zipCode": "20500",
        "zip4": "0005",
        "county": "DISTRICT OF COLUMBIA",
        "dpvConfirmation": "Y",
        "isValid": true
    },
    "statusCode": 200,
    "isError": false,
    "errors": []
}

Forward Geocoding

The Forward Geocoding API converts a US street address into geographic coordinates (latitude and longitude).

Endpoint

GET /Geocoding/USA/Forward/{address}

Response Model

public record GeocodingResult
{
    [JsonPropertyName("latitude")]
    public double Latitude { get; init; }

    [JsonPropertyName("longitude")]
    public double Longitude { get; init; }

    [JsonPropertyName("formattedAddress")]
    public string FormattedAddress { get; init; } = "";

    [JsonPropertyName("accuracy")]
    public string Accuracy { get; init; } = "";
}

C# Implementation

var address = "1600 Amphitheatre Pkwy Mountain View CA 94043";
var encoded = Uri.EscapeDataString(address);
var geo = await client.CallApiAsync<GeocodingResult>(
    $"/Geocoding/USA/Forward/{encoded}");

if (geo is not null)
{
    Console.WriteLine($"Address: {geo.FormattedAddress}");
    Console.WriteLine($"Lat: {geo.Latitude}");
    Console.WriteLine($"Lon: {geo.Longitude}");
    Console.WriteLine($"Accuracy: {geo.Accuracy}");
}

Example Response

{
    "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "result": {
        "latitude": 37.4224764,
        "longitude": -122.0842499,
        "formattedAddress": "1600 AMPHITHEATRE PKWY, MOUNTAIN VIEW, CA 94043",
        "accuracy": "Rooftop"
    },
    "statusCode": 200,
    "isError": false,
    "errors": []
}

Error Handling & Best Practices

1. Never new Up HttpClient Directly

In ASP.NET Core, always use IHttpClientFactory. Creating HttpClient instances directly can lead to socket exhaustion under load because each instance manages its own connection pool. The factory manages HttpMessageHandler lifetimes and reuses connections efficiently.

// BAD - socket exhaustion risk
using var client = new HttpClient();

// GOOD - uses IHttpClientFactory (ASP.NET Core)
builder.Services.AddHttpClient<SthanAddressService>(client =>
{
    client.BaseAddress = new Uri("https://api.sthan.io");
});

// ACCEPTABLE - single static instance (console apps)
private static readonly HttpClient SharedClient = new()
{
    BaseAddress = new Uri("https://api.sthan.io")
};

2. URL-Encode All Address Inputs

Addresses can contain characters that break URLs (#, &, /, spaces). Always use Uri.EscapeDataString():

// BAD - "123 Main St #4" breaks the URL
var url = $"/AddressParser/USA/Single/{address}";

// GOOD - properly encoded
var url = $"/AddressParser/USA/Single/{Uri.EscapeDataString(address)}";

3. Token Caching with Thread Safety

In a multi-threaded web server, multiple requests might try to refresh the token simultaneously. Use SemaphoreSlim for thread-safe token refresh (as shown in the ASP.NET Core service above):

private readonly SemaphoreSlim _tokenLock = new(1, 1);

private async Task RefreshTokenAsync(CancellationToken ct)
{
    await _tokenLock.WaitAsync(ct);
    try
    {
        // Double-check pattern: another thread may have
        // refreshed while we waited for the lock
        if (IsTokenValid()) return;

        // ... refresh token ...
    }
    finally
    {
        _tokenLock.Release();
    }
}

4. Cancellation Token Support

Always accept and pass CancellationToken through your async call chain. This allows ASP.NET Core to cancel in-flight requests when the client disconnects:

public async Task<VerificationResult?> VerifyAddressAsync(
    string address, CancellationToken ct = default)
{
    // ct is passed to HttpClient.SendAsync, which will throw
    // OperationCanceledException if the request is cancelled
    var response = await _httpClient.SendAsync(request, ct);
    // ...
}

5. Retry Policies with Polly (Optional)

For production resilience, consider adding Polly retry and circuit breaker policies via Microsoft.Extensions.Http.Polly:

// Install: dotnet add package Microsoft.Extensions.Http.Polly

builder.Services.AddHttpClient<SthanAddressService>(client =>
{
    client.BaseAddress = new Uri("https://api.sthan.io");
})
.AddTransientHttpErrorPolicy(p =>
    p.WaitAndRetryAsync(3, attempt =>
        TimeSpan.FromSeconds(Math.Pow(2, attempt))))
.AddTransientHttpErrorPolicy(p =>
    p.CircuitBreakerAsync(5, TimeSpan.FromSeconds(30)));

6. Logging

Add structured logging to track API call performance and errors. Use ILogger<T> injected via DI:

using System.Diagnostics;

public class SthanAddressService
{
    private readonly ILogger<SthanAddressService> _logger;

    public SthanAddressService(
        HttpClient httpClient,
        IOptions<SthanApiSettings> settings,
        ILogger<SthanAddressService> logger)
    {
        _logger = logger;
        // ...
    }

    public async Task<VerificationResult?> VerifyAddressAsync(
        string address, CancellationToken ct = default)
    {
        var sw = Stopwatch.StartNew();
        try
        {
            var result = await GetAsync<VerificationResult>(
                $"/AddressVerification/Usa/Single/{Uri.EscapeDataString(address)}", ct);
            _logger.LogInformation(
                "Address verified in {ElapsedMs}ms: {IsValid}",
                sw.ElapsedMilliseconds, result?.IsValid);
            return result;
        }
        catch (Exception ex)
        {
            _logger.LogError(ex,
                "Address verification failed after {ElapsedMs}ms",
                sw.ElapsedMilliseconds);
            throw;
        }
    }
}

Share This Article