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

Authentication

The first step is obtaining a JWT token from the Sthan.io Auth endpoint. This token is then used as a Bearer token for all subsequent API requests. Below is a complete, reusable SthanClient class that handles authentication and token management.

Step 1: Get a JWT Token

Send a GET request to /Auth/Token with your credentials in the headers:

import requests
from urllib.parse import quote

# Step 1: Authenticate and get a JWT token
AUTH_URL = "https://api.sthan.io/Auth/Token"

headers = {
    "profileName": "YOUR_PROFILE_NAME",
    "profilePassword": "YOUR_PROFILE_PASSWORD"
}

response = requests.get(AUTH_URL, headers=headers)
response.raise_for_status()

data = response.json()
access_token = data["result"]["access_token"]
expiration = data["result"]["expiration"]

print(f"Token obtained, expires: {expiration}")

The response follows the standard Sthan.io envelope format:

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "result": {
        "access_token": "eyJhbGciOiJIUzI1NiIs...",
        "expiration": "2026-03-08T09:00:00Z"
    },
    "statusCode": 200,
    "isError": false,
    "errors": []
}

Step 2: Build a Reusable SthanClient Class

Wrap authentication and API calls in a reusable class. This client handles token acquisition, caching, and provides methods for each address API endpoint.

import requests
from urllib.parse import quote
from datetime import datetime, timezone


class SthanClient:
    """Reusable client for Sthan.io address APIs."""

    BASE_URL = "https://api.sthan.io"

    def __init__(self, profile_name: str, profile_password: str):
        self.profile_name = profile_name
        self.profile_password = profile_password
        self._token: str | None = None
        self._token_expiry: datetime | None = None
        self.session = requests.Session()
        self.session.headers.update({"Content-Type": "application/json"})

    def _get_token(self) -> str:
        """Get a valid JWT token, refreshing if expired."""
        now = datetime.now(timezone.utc)
        if self._token and self._token_expiry and now < self._token_expiry:
            return self._token

        response = self.session.get(
            f"{self.BASE_URL}/Auth/Token",
            headers={
                "profileName": self.profile_name,
                "profilePassword": self.profile_password,
            },
            timeout=10,
        )
        response.raise_for_status()

        data = response.json()
        self._token = data["result"]["access_token"]
        # Parse expiration and subtract 60s buffer
        self._token_expiry = datetime.fromisoformat(
            data["result"]["expiration"].replace("Z", "+00:00")
        )
        return self._token

    def _auth_headers(self) -> dict:
        """Return headers with a valid Bearer token."""
        token = self._get_token()
        return {"Authorization": f"Bearer {token}"}

    def autocomplete(self, text: str) -> dict:
        """Search for address suggestions as the user types."""
        url = f"{self.BASE_URL}/AutoComplete/USA/Address/{quote(text)}"
        resp = self.session.get(url, headers=self._auth_headers(), timeout=10)
        resp.raise_for_status()
        return resp.json()

    def verify_address(self, address: str) -> dict:
        """Verify and standardize a US address."""
        url = f"{self.BASE_URL}/AddressVerification/Usa/Single/{quote(address)}"
        resp = self.session.get(url, headers=self._auth_headers(), timeout=15)
        resp.raise_for_status()
        return resp.json()

    def parse_address(self, address: str) -> dict:
        """Parse an address string into structured components."""
        url = f"{self.BASE_URL}/AddressParser/USA/Single/{quote(address)}"
        resp = self.session.get(url, headers=self._auth_headers(), timeout=15)
        resp.raise_for_status()
        return resp.json()

    def geocode(self, address: str) -> dict:
        """Forward geocode an address to latitude/longitude."""
        url = f"{self.BASE_URL}/Geocoding/USA/Forward/{quote(address)}"
        resp = self.session.get(url, headers=self._auth_headers(), timeout=15)
        resp.raise_for_status()
        return resp.json()


# Usage
client = SthanClient("YOUR_PROFILE_NAME", "YOUR_PROFILE_PASSWORD")

Address Verification

The Address Verification API validates and standardizes US addresses against authoritative postal data. It corrects formatting errors, fills in missing components (ZIP+4, county), and confirms deliverability. This is essential for e-commerce checkout, shipping, and mailing workflows.

Endpoint

GET /AddressVerification/Usa/Single/{address}

Python Example

# Verify and standardize a US address
result = client.verify_address("1600 pennsylvania ave nw washington dc")

if not result["isError"]:
    verified = result["result"]
    print(f"Street:  {verified['addressLine1']}")
    print(f"City:    {verified['city']}")
    print(f"State:   {verified['state']}")
    print(f"ZIP:     {verified['zipCode']}")
    print(f"ZIP+4:   {verified['plus4']}")
    print(f"County:  {verified['county']}")
else:
    print("Verification failed:", result["errors"])

Sample Response

{
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "result": {
        "addressLine1": "1600 Pennsylvania Ave NW",
        "city": "Washington",
        "state": "DC",
        "zipCode": "20500",
        "plus4": "0005",
        "county": "District of Columbia",
        "deliveryPoint": "99",
        "carrierRoute": "C000",
        "congressionalDistrict": "98",
        "isValid": true
    },
    "statusCode": 200,
    "isError": false,
    "errors": []
}

Forward Geocoding

The Forward Geocoding API converts a US address string into geographic coordinates (latitude and longitude). Use this for mapping, distance calculations, delivery zone assignment, and location-based services.

Endpoint

GET /Geocoding/USA/Forward/{address}

Python Example

# Forward geocode an address to lat/lon coordinates
result = client.geocode("1600 Pennsylvania Ave NW, Washington, DC 20500")

if not result["isError"]:
    geo = result["result"]
    print(f"Latitude:  {geo['latitude']}")
    print(f"Longitude: {geo['longitude']}")
    print(f"Accuracy:  {geo.get('accuracy', 'N/A')}")
else:
    print("Geocoding failed:", result["errors"])

Sample Response

{
    "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "result": {
        "latitude": 38.8977,
        "longitude": -77.0365,
        "accuracy": "Rooftop"
    },
    "statusCode": 200,
    "isError": false,
    "errors": []
}

Error Handling & Best Practices

1. Retry Logic with Exponential Backoff

Handle transient failures (network errors, 429 rate limit, 500 server errors) with automatic retries and exponential backoff:

import time
import requests
from urllib.parse import quote


def request_with_retry(
    session: requests.Session,
    url: str,
    headers: dict,
    max_retries: int = 3,
    base_delay: float = 1.0,
) -> requests.Response:
    """Make an HTTP GET request with exponential backoff retry."""
    for attempt in range(max_retries + 1):
        try:
            response = session.get(url, headers=headers, timeout=15)

            # Success or client error (not retryable)
            if response.status_code < 500 and response.status_code != 429:
                response.raise_for_status()
                return response

            # Rate limited -- wait and retry
            if response.status_code == 429:
                retry_after = int(response.headers.get("Retry-After", base_delay))
                print(f"Rate limited. Waiting {retry_after}s...")
                time.sleep(retry_after)
                continue

            # Server error -- retry with backoff
            if attempt < max_retries:
                delay = base_delay * (2 ** attempt)
                print(f"Server error {response.status_code}. Retrying in {delay}s...")
                time.sleep(delay)

        except requests.exceptions.ConnectionError:
            if attempt < max_retries:
                delay = base_delay * (2 ** attempt)
                print(f"Connection error. Retrying in {delay}s...")
                time.sleep(delay)
            else:
                raise

    raise Exception(f"Failed after {max_retries} retries")

2. URL Encoding Addresses

Addresses with special characters (#, &, spaces) must be URL-encoded before including them in the API path. Use urllib.parse.quote():

from urllib.parse import quote

# Correctly encode addresses with special characters
address = "123 Main St #4B, New York, NY"
encoded = quote(address)
# Result: "123%20Main%20St%20%234B%2C%20New%20York%2C%20NY"

url = f"https://api.sthan.io/AddressVerification/Usa/Single/{encoded}"

3. Token Refresh Pattern

JWT tokens expire after a set period. The SthanClient class shown above handles this automatically by checking the expiration field before each request. If your token has expired, simply re-authenticate:

# The SthanClient._get_token() method handles this automatically.
# If you're managing tokens manually:
from datetime import datetime, timezone, timedelta

def is_token_valid(expiry_str: str) -> bool:
    """Check if a JWT token is still valid (with 60s buffer)."""
    expiry = datetime.fromisoformat(expiry_str.replace("Z", "+00:00"))
    now = datetime.now(timezone.utc)
    # Refresh 60 seconds before actual expiry
    return now < expiry - timedelta(seconds=60)

4. Secure Credential Storage

Never hardcode API credentials in your source code. Use environment variables:

import os

# Load credentials from environment variables
profile_name = os.environ.get("STHAN_PROFILE_NAME")
profile_password = os.environ.get("STHAN_PROFILE_PASSWORD")

if not profile_name or not profile_password:
    raise ValueError("Missing STHAN_PROFILE_NAME or STHAN_PROFILE_PASSWORD env vars")

client = SthanClient(profile_name, profile_password)

# Set environment variables before running your script
export STHAN_PROFILE_NAME="your-profile-name"
export STHAN_PROFILE_PASSWORD="your-profile-password"
python your_script.py

5. Production Tips

• Connection pooling: Always use requests.Session() to reuse TCP connections. Creating a new connection per request adds 50-100ms of overhead.
• Timeouts: Set explicit timeouts (10-15s) on every request to avoid hanging indefinitely. The SthanClient above uses timeout=10 for auth and timeout=15 for API calls.
• Logging: Log API errors with the request URL (without credentials) and status code for debugging. Use Python's built-in logging module.
• Rate limiting: Check your plan's rate limits and implement client-side throttling to stay within bounds.
• Caching: Cache verification results for addresses you've already validated. Use functools.lru_cache or Redis for production caching.