How to Add Address Autocomplete to a Python App

What the API returns

The API wraps every response in an envelope. The address suggestions are in the Result field:

{
  "Id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
  "Result": [
    "123 Main St APT 1, Andover, MA 01810-3816",
    "123 Main St APT 1, Delhi, NY 13753-1257",
    "123 Main St STE 1, Caldwell, ID 83605-5476",
    "123 Main St STE 1, Corinth, NY 12822-1010",
    "123 Main St STE 1, Delhi, NY 13753-1258"
  ],
  "StatusCode": 200,
  "IsError": false,
  "Errors": []
}

Each address includes the full street, unit designation (APT, STE, UNIT), city, state code, and zip+4. The API handles abbreviations (St, Ave, Blvd) and directional prefixes (N, S, E, W).

Get your API credentials

1. Sign up at sthan.io
2. Go to the API Keys page
3. Copy your Profile Name and Profile Password

You get credentials immediately - no approval queue.

Install requests

pip install requests

Get an auth token

The API uses JWT authentication. First call gets a token, then you use it for autocomplete requests.

import os
import requests

PROFILE_NAME = os.environ.get("STHAN_PROFILE_NAME", "YOUR_PROFILE_NAME")
PROFILE_PASSWORD = os.environ.get("STHAN_PROFILE_PASSWORD", "YOUR_PROFILE_PASSWORD")
BASE_URL = "https://api.sthan.io"

def get_token():
    response = requests.get(
        f"{BASE_URL}/Auth/Token",
        headers={
            "profileName": PROFILE_NAME,
            "profilePassword": PROFILE_PASSWORD,
        },
    )
    response.raise_for_status()
    data = response.json()
    result = data["Result"]
    return result["access_token"], result["expiration"]

token, expiration = get_token()
print(f"Token expires: {expiration}")

The token lasts 15 minutes. The production client below caches and refreshes it automatically.

Call the autocomplete endpoint

from urllib.parse import quote

def autocomplete(query, token):
    response = requests.get(
        f"{BASE_URL}/AutoComplete/USA/Address/{quote(query)}",
        headers={"Authorization": f"Bearer {token}"},
    )
    response.raise_for_status()
    return response.json()["Result"]

results = autocomplete("123 main st", token)
for address in results:
    print(address)

The output matches the JSON shown above - the same five addresses, standardized from the abbreviated input.

Production-ready client with token caching

In production, you don't want to fetch a new token on every request. Here's a client that caches the token and refreshes it automatically:

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


class SthanClient:
    def __init__(self, profile_name=None, profile_password=None):
        self.profile_name = profile_name or os.environ["STHAN_PROFILE_NAME"]
        self.profile_password = profile_password or os.environ["STHAN_PROFILE_PASSWORD"]
        self.base_url = "https://api.sthan.io"
        self._token = None
        self._expiration = None

    def _get_token(self):
        if self._token and self._expiration:
            if datetime.now(timezone.utc) < self._expiration:
                return self._token

        response = requests.get(
            f"{self.base_url}/Auth/Token",
            headers={
                "profileName": self.profile_name,
                "profilePassword": self.profile_password,
            },
        )
        response.raise_for_status()
        data = response.json()["Result"]
        self._token = data["access_token"]
        self._expiration = datetime.fromisoformat(
            data["expiration"].replace("Z", "+00:00")
        )
        return self._token

    def autocomplete(self, query, min_length=3):
        """Fetch address suggestions for a partial query."""
        if len(query.strip()) < min_length:
            return []

        token = self._get_token()
        response = requests.get(
            f"{self.base_url}/AutoComplete/USA/Address/{quote(query)}",
            headers={"Authorization": f"Bearer {token}"},
        )
        response.raise_for_status()
        return response.json()["Result"]


# Usage
client = SthanClient()

results = client.autocomplete("123 main st")
for address in results:
    print(address)

This client:

• Caches the JWT and reuses it across requests
• Refreshes automatically when the token expires
• Enforces a minimum query length (3 characters) to avoid wasting API calls
• Reads credentials from environment variables by default
• Works with any Python web framework

Add it to a Flask app

Here's a minimal Flask endpoint that your frontend can call:

from flask import Flask, request, jsonify

app = Flask(__name__)
client = SthanClient()  # reads from STHAN_PROFILE_NAME / STHAN_PROFILE_PASSWORD env vars


@app.route("/api/autocomplete")
def autocomplete_endpoint():
    query = request.args.get("q", "")
    if len(query) < 3:
        return jsonify([])
    results = client.autocomplete(query)
    return jsonify(results)


if __name__ == "__main__":
    app.run(port=3000)

Your frontend calls /api/autocomplete?q=123 main st and gets back a JSON array of addresses. Credentials stay on the server - never exposed to the browser.

The same pattern works with Django (views.py), FastAPI (@app.get), or any other Python web framework.

Handle errors

Two error codes to handle:

• 401 - Token expired. Refresh and retry.
• 429 - Rate limit hit. Back off and show what the user has typed so far.

def autocomplete_with_retry(client, query):
    try:
        return client.autocomplete(query)
    except requests.HTTPError as e:
        if e.response.status_code == 401:
            # Force token refresh and retry once
            client._token = None
            return client.autocomplete(query)
        elif e.response.status_code == 429:
            # Rate limited — return empty, don't crash
            return []
        raise

What's next

Address autocomplete is step 1 of a complete address pipeline. The same credentials unlock these endpoints:

• Address Parser - Split "123 Main St, Andover, MA 01810" into street, city, state, zip fields
• Address Verification - Check if an address is real and deliverable
• Forward Geocoding - Convert an address to latitude/longitude
• Reverse Geocoding - Convert coordinates to an address
• IP Geolocation - Get location data from an IP address

For a complete Python guide covering all endpoints with async examples, see Integrate Address APIs in Python.