How to Add Address Autocomplete in Next.js (App Router)

What the API returns

The API wraps every response in a standard envelope. The address suggestions live in the Result field, which for autocomplete is a plain array of strings:

{
  "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"
  ],
  "ClientSessionId": null,
  "StatusCode": 200,
  "IsError": false,
  "Errors": []
}

Each suggestion includes the full street, the 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) on the way in, and returns clean, standardized output. In the Route Handler you read body.Result and return it as JSON.

Get your API key

1. Sign up at sthan.io and subscribe to the free Address Autocomplete tier
2. Open your dashboard and create an API key
3. Copy the key - it looks like sthan_live_xxxxxxxxxxxxxxxx

You get the key immediately, with no approval queue. An API key is the simplest way to authenticate: you send it as a Bearer token on every request and there is no separate login step. (If you prefer a short-lived token, there is a JWT flow covered later.)

Configure the environment

Store the key in .env.local as a plain, server-only variable:

# .env.local
STHAN_API_KEY=sthan_live_xxxxxxxxxxxxxxxx

Add a Route Handler

A Route Handler runs only on the server. This one sends the API key as a Bearer token, URL-encodes the query, and returns the Result array:

// app/api/address/autocomplete/route.js
import { NextResponse } from "next/server";

const API_BASE = "https://api.sthan.io";

export async function GET(request) {
  const query = (request.nextUrl.searchParams.get("query") || "").trim();
  if (query.length < 3) {
    return NextResponse.json([]);
  }

  const res = await fetch(
    `${API_BASE}/AutoComplete/USA/Address/${encodeURIComponent(query)}`,
    {
      headers: { Authorization: `Bearer ${process.env.STHAN_API_KEY}` },
      cache: "no-store",
    }
  );

  if (!res.ok) {
    return NextResponse.json([], { status: 502 });
  }

  const body = await res.json();
  // The envelope wraps the data — suggestions are in Result
  return NextResponse.json(body.Result ?? []);
}

The whole integration is this one request. cache: "no-store" keeps every keystroke fresh rather than serving a cached result.

Why the proxy matters

The browser should call your Route Handler, and the handler calls sthan.io. There are two reasons for this. First, the API does not enable CORS for browser requests, so a direct call from a client component would be blocked. Second, and more important, putting your API key in client-side code - or in a NEXT_PUBLIC_ variable - would expose it to anyone who opens the network tab. The Route Handler keeps the key on the server.

Your client component now has a clean URL to call: /api/address/autocomplete?query=123 main st returns a JSON array of addresses, and the API key never leaves the server.

Wire up the client component

The last piece is a debounced client component that calls your Route Handler. Debouncing matters: without it, "123 main st" fires eleven requests, one per keystroke. With a 250ms debounce, it fires one request after the user pauses:

"use client";
import { useState, useRef } from "react";

export default function AddressInput() {
  const [items, setItems] = useState([]);
  const timer = useRef();

  function onChange(e) {
    const query = e.target.value.trim();
    clearTimeout(timer.current);

    if (query.length < 3) {
      setItems([]);
      return;
    }

    // Wait 250ms after the last keystroke before calling the server
    timer.current = setTimeout(async () => {
      const res = await fetch(
        `/api/address/autocomplete?query=${encodeURIComponent(query)}`);
      setItems(await res.json());
    }, 250);
  }

  return (
    <div>
      <input
        type="text"
        autoComplete="off"
        placeholder="Start typing your address..."
        onChange={onChange}
      />
      <ul>
        {items.map((a, i) => (
          <li key={i}>{a}</li>
        ))}
      </ul>
    </div>
  );
}

The browser only ever talks to /api/address/autocomplete on your own domain. No key, no CORS, no third-party script. From here you can style the list, add keyboard navigation, and fill the form fields when a user clicks a suggestion.

Alternative: JWT authentication

An API key is the simplest option and is all most apps need. If your security policy prefers short-lived credentials, the platform also supports a 2-step JWT flow. You call GET /Auth/Token once with your profileName and profilePassword headers, receive a token valid for up to 60 minutes, then send that token as the Bearer value on subsequent calls. Cache it in a module-level variable in your server code:

let cached = { token: null, expires: 0 };

export async function getToken() {
  if (cached.token && Date.now() < cached.expires - 30_000) {
    return cached.token;
  }

  const res = await fetch("https://api.sthan.io/Auth/Token", {
    headers: {
      profileName: process.env.STHAN_PROFILE_NAME,
      profilePassword: process.env.STHAN_PROFILE_PASSWORD,
    },
    cache: "no-store",
  });
  const body = await res.json();

  cached.token = body.Result.access_token;
  cached.expires = new Date(body.Result.expiration).getTime();
  return cached.token;
}

You would then build the Authorization header in the Route Handler from getToken() instead of a static key. Everything else - the endpoint, the envelope, the parsing - stays the same.

Handle errors

Two status codes are worth handling explicitly so a hiccup never crashes your form:

• 401 - The key or token was rejected. Check the value and, on the JWT flow, refresh and retry once.
• 429 - Rate limit reached. Back off and return what the user has typed so far rather than throwing.

if (res.status === 429) {
  // Rate limited — degrade gracefully, don't crash the form
  return NextResponse.json([]);
}

Returning an empty list on failure means a momentary hiccup shows no suggestions rather than a broken page. The user can still type the address by hand.

What's next: confirm the address is deliverable

Autocomplete gets the user to a clean, well-formed address fast. It does not, on its own, confirm that mail or a package will actually arrive there - a suggestion can be correctly formatted yet point at a unit that no longer accepts delivery.

The natural next step is to run the chosen address through the Address Verification API at the moment the user submits the form. It returns a Delivery Point Validation (DPV) result and a deliverable status, standardizes the address to standard postal format, and appends ZIP+4 and county. Call it from a Route Handler or a Server Action - the same pattern you already built:

const res = await fetch(
  `https://api.sthan.io/v2/address-verification/usa/speculative/${encodeURIComponent(selected)}`,
  { headers: { Authorization: `Bearer ${process.env.STHAN_API_KEY}` }, cache: "no-store" });
const { Result } = await res.json();
// Read Result.deliverableStatus and Result.dpvConfirmation

Address Verification has its own free tier of 100 requests/month, with paid plans from $12/month. Pairing autocomplete (volume, real-time, as the user types) with verification (one confirming call at submit) keeps your costs low and your delivery data clean. For the front-end framework comparison, see Address Autocomplete in React, Vue & Angular.