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

Authentication & Reusable API Client

Let's build a reusable SthanApiClient class that handles authentication, token caching, and API requests using Java's built-in java.net.http.HttpClient.

Step 1: Get a JWT Token

Call GET https://api.sthan.io/Auth/Token with your profileName and profilePassword as request headers:

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

public class SthanAuth {

    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(10))
                .build();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.sthan.io/Auth/Token"))
                .header("profileName", "YOUR_PROFILE_NAME")
                .header("profilePassword", "YOUR_PROFILE_PASSWORD")
                .GET()
                .build();

        HttpResponse<String> response = client.send(
                request, HttpResponse.BodyHandlers.ofString());

        System.out.println("Status: " + response.statusCode());

        ObjectMapper mapper = new ObjectMapper();
        JsonNode json = mapper.readTree(response.body());

        // Extract the token from the wrapped response
        String token = json.get("result")
                           .get("access_token").asText();

        System.out.println("Token: " + token);
    }
}

The response follows the standard Sthan.io envelope format:

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "result": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "expiration": "2026-03-07T18:30:00Z"
    },
    "statusCode": 200,
    "isError": false,
    "errors": []
}

Step 2: Build a Reusable Client with Token Caching

For production use, create a class that caches the JWT token and refreshes it automatically:

import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.time.Instant;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

public class SthanApiClient {

    private static final String BASE_URL = "https://api.sthan.io";
    private final HttpClient httpClient;
    private final ObjectMapper objectMapper;
    private final String profileName;
    private final String profilePassword;

    private String cachedToken;
    private Instant tokenExpiry;

    public SthanApiClient(String profileName, String profilePassword) {
        this.profileName = profileName;
        this.profilePassword = profilePassword;
        this.objectMapper = new ObjectMapper();
        this.httpClient = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(10))
                .build();
    }

    /**
     * Get a valid JWT token, refreshing if expired.
     */
    public synchronized String getToken() throws Exception {
        if (cachedToken != null && tokenExpiry != null
                && Instant.now().isBefore(tokenExpiry.minusSeconds(30))) {
            return cachedToken;
        }

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + "/Auth/Token"))
                .header("profileName", profileName)
                .header("profilePassword", profilePassword)
                .GET()
                .build();

        HttpResponse<String> response = httpClient.send(
                request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new RuntimeException(
                "Authentication failed: HTTP " + response.statusCode());
        }

        JsonNode json = objectMapper.readTree(response.body());
        JsonNode result = json.get("result");
        cachedToken = result.get("access_token").asText();
        String expiration = result.get("expiration").asText();
        tokenExpiry = Instant.parse(expiration);

        return cachedToken;
    }

    /**
     * Make an authenticated GET request to a Sthan.io endpoint.
     */
    public JsonNode get(String path) throws Exception {
        String token = getToken();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + path))
                .header("Authorization", "Bearer " + token)
                .timeout(Duration.ofSeconds(30))
                .GET()
                .build();

        HttpResponse<String> response = httpClient.send(
                request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new RuntimeException(
                "API request failed: HTTP " + response.statusCode()
                + " - " + response.body());
        }

        return objectMapper.readTree(response.body());
    }

    /**
     * URL-encode a string for use in API paths.
     */
    public static String encode(String value) {
        return URLEncoder.encode(value, StandardCharsets.UTF_8);
    }
}

Address Verification

The Address Verification API validates and standardizes a full US address. Call GET /AddressVerification/Usa/Single/{address} to verify deliverability and get the standardized USPS format.

import com.fasterxml.jackson.databind.JsonNode;

public class VerificationExample {

    public static void main(String[] args) throws Exception {
        SthanApiClient client = new SthanApiClient(
                "YOUR_PROFILE_NAME", "YOUR_PROFILE_PASSWORD");

        String address = "1600 Pennsylvania Ave NW, Washington DC 20500";
        String path = "/AddressVerification/Usa/Single/"
                     + SthanApiClient.encode(address);

        JsonNode response = client.get(path);

        JsonNode result = response.get("result");
        if (result != null) {
            System.out.println("Verified Address:");
            System.out.println("  Street: "
                + result.path("addressLine1").asText());
            System.out.println("  City: "
                + result.path("city").asText());
            System.out.println("  State: "
                + result.path("state").asText());
            System.out.println("  ZIP: "
                + result.path("zipCode").asText());
            System.out.println("  ZIP+4: "
                + result.path("plus4Code").asText());
            System.out.println("  Deliverable: "
                + result.path("isDeliverable").asBoolean());
        }

        // Check for errors
        if (response.get("isError").asBoolean()) {
            JsonNode errors = response.get("errors");
            for (JsonNode error : errors) {
                System.err.println("Error: " + error.asText());
            }
        }
    }
}

Example response:

{
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "result": {
        "addressLine1": "1600 PENNSYLVANIA AVE NW",
        "city": "WASHINGTON",
        "state": "DC",
        "zipCode": "20500",
        "plus4Code": "0005",
        "isDeliverable": true,
        "dpvMatchCode": "Y",
        "isResidential": false
    },
    "statusCode": 200,
    "isError": false,
    "errors": []
}

Forward Geocoding

The Forward Geocoding API converts a US address into latitude/longitude coordinates. Call GET /Geocoding/USA/Forward/{address}.

import com.fasterxml.jackson.databind.JsonNode;

public class GeocodingExample {

    public static void main(String[] args) throws Exception {
        SthanApiClient client = new SthanApiClient(
                "YOUR_PROFILE_NAME", "YOUR_PROFILE_PASSWORD");

        String address = "1600 Amphitheatre Parkway, Mountain View, CA 94043";
        String path = "/Geocoding/USA/Forward/"
                     + SthanApiClient.encode(address);

        JsonNode response = client.get(path);

        JsonNode result = response.get("result");
        if (result != null) {
            double latitude = result.path("latitude").asDouble();
            double longitude = result.path("longitude").asDouble();

            System.out.println("Geocoding Result:");
            System.out.println("  Latitude:  " + latitude);
            System.out.println("  Longitude: " + longitude);
            System.out.println("  Formatted: "
                + result.path("formattedAddress").asText());
        }
    }
}

Example response:

{
    "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "result": {
        "latitude": 37.4220656,
        "longitude": -122.0862784,
        "formattedAddress": "1600 AMPHITHEATRE PKWY, MOUNTAIN VIEW, CA 94043"
    },
    "statusCode": 200,
    "isError": false,
    "errors": []
}

Error Handling & Best Practices

Custom Exception Class

Create a dedicated exception for API errors:

public class SthanApiException extends RuntimeException {

    private final int statusCode;
    private final String responseBody;

    public SthanApiException(int statusCode, String responseBody) {
        super("Sthan API error: HTTP " + statusCode);
        this.statusCode = statusCode;
        this.responseBody = responseBody;
    }

    public int getStatusCode() { return statusCode; }
    public String getResponseBody() { return responseBody; }
}

Retry Logic with Exponential Backoff

Implement retry logic for transient failures (network errors, 429 rate limiting, 5xx server errors):

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class RetryHelper {

    private static final int MAX_RETRIES = 3;
    private static final long BASE_DELAY_MS = 1000;

    /**
     * Execute an HTTP request with exponential backoff retry.
     */
    public static HttpResponse<String> executeWithRetry(
            HttpClient client, HttpRequest request) throws Exception {

        Exception lastException = null;

        for (int attempt = 0; attempt <= MAX_RETRIES; attempt++) {
            try {
                HttpResponse<String> response = client.send(
                        request, HttpResponse.BodyHandlers.ofString());

                int status = response.statusCode();

                // Success or client error (don't retry 4xx except 429)
                if (status < 500 && status != 429) {
                    return response;
                }

                // Rate limited or server error -- retry
                if (attempt < MAX_RETRIES) {
                    long delay = BASE_DELAY_MS * (long) Math.pow(2, attempt);
                    // Add jitter to prevent thundering herd
                    delay += (long) (Math.random() * delay * 0.1);
                    Thread.sleep(delay);
                }

            } catch (java.io.IOException e) {
                lastException = e;
                if (attempt < MAX_RETRIES) {
                    long delay = BASE_DELAY_MS * (long) Math.pow(2, attempt);
                    Thread.sleep(delay);
                }
            }
        }

        throw new RuntimeException(
            "Request failed after " + MAX_RETRIES + " retries",
            lastException);
    }
}

URL Encoding

Always URL-encode address strings before including them in the request path. Characters like #, &, and spaces must be encoded:

import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

// Always encode addresses in the URL path
String address = "123 Main St #4B, Springfield, IL";
String encoded = URLEncoder.encode(address, StandardCharsets.UTF_8);
String path = "/AddressVerification/Usa/Single/" + encoded;

Production Best Practices

• Connection pooling: java.net.http.HttpClient manages a connection pool internally. Create one instance and reuse it across your application.
• Timeouts: Always set both connectTimeout (on the client) and timeout (on individual requests). Use 10s for connect and 30s for read.
• Thread safety: HttpClient and ObjectMapper are thread-safe. Use synchronized or AtomicReference for token caching.
• Token refresh: Cache the JWT token and refresh it 30 seconds before expiry. Never request a new token for every API call.
• Rate limiting: Respect API rate limits. If you receive HTTP 429, back off and retry with exponential delay. Use a Semaphore to limit concurrent requests.
• Logging: Log request/response details at DEBUG level and errors at ERROR level. Never log the full JWT token or credentials in production.
• Batch processing: For bulk address processing, use HttpClient.sendAsync() with CompletableFuture to make concurrent requests, controlled by a semaphore.

import com.fasterxml.jackson.databind.JsonNode;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.Semaphore;
import java.util.stream.Collectors;

public class BatchProcessor {

    // Batch processing with controlled concurrency
    public List<JsonNode> verifyBatch(
        SthanApiClient client,
        List<String> addresses,
        int maxConcurrency) throws Exception {

    Semaphore semaphore = new Semaphore(maxConcurrency);

    List<CompletableFuture<JsonNode>> futures = addresses.stream()
            .map(address -> CompletableFuture.supplyAsync(() -> {
                try {
                    semaphore.acquire();
                    try {
                        return client.get(
                            "/AddressVerification/Usa/Single/"
                            + SthanApiClient.encode(address));
                    } finally {
                        semaphore.release();
                    }
                } catch (Exception e) {
                    throw new RuntimeException(e);
                }
            }))
            .collect(Collectors.toList());

    return futures.stream()
            .map(CompletableFuture::join)
            .collect(Collectors.toList());
    }
}