How to Parse US Addresses in Node.js / Express

What the API returns

Every response is wrapped in a standard envelope. For parsing, the Result field is a single object whose properties are the address components. This is a real response for 1600 Pennsylvania Ave NW Apt 4B:

{
  "Id": "2737f8f3-af83-4ba1-b9c3-e29d2ba9e03b",
  "Result": {
    "inputAddress": "1600 Pennsylvania Ave NW Apt 4B Washington DC 20500",
    "addressLine1": "1600 PENNSYLVANIA AVE NW",
    "addressLine2": null,
    "addressNumber": "1600",
    "streetPreDir": "",
    "streetName": "PENNSYLVANIA",
    "streetPostType": "AVE",
    "streetPostDir": "NW",
    "unitType": "apt",
    "unitNumber": "4b",
    "city": "WASHINGTON",
    "stateCode": "DC",
    "zipCode": "20500",
    "zip4": null,
    "county": null,
    "matchMode": "Speculative",
    "matchTier": "Near",
    "confidence": 0.7,
    "matchCode": {
      "houseNumber": "Matched",
      "street": "Matched",
      "unit": "Matched",
      "city": "Matched",
      "state": "Matched",
      "zipCode": "Matched",
      "zip4": "NotApplicable"
    },
    "footnotes": ["recovered: standardized via correction, not an exact match"]
  },
  "ClientSessionId": null,
  "StatusCode": 200,
  "IsError": false,
  "Errors": []
}

The fields you'll use most often are covered in the component map below. Note that some fields are empty or null when they don't apply - there's no leading directional here, so streetPreDir is an empty string, and the parser didn't append a zip4 or county, so those are null.

Get your API key

1. Sign up at sthan.io and subscribe to the free Address Parser 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 project

Keep your key out of source control by reading it from the environment. A .env file loaded with dotenv works well in development:

npm install dotenv        # optional, for local .env loading
# express is only needed for the route example later:
npm install express

# .env  (add it to .gitignore)
STHAN_API_KEY=sthan_live_xxxxxxxxxxxxxxxx

import "dotenv/config"; // or: require("dotenv").config();

const STHAN_BASE_URL = "https://api.sthan.io";
const STHAN_API_KEY = process.env.STHAN_API_KEY;
if (!STHAN_API_KEY) throw new Error("STHAN_API_KEY is not set");

Build the parser client

On Node.js 18+, fetch is built in - no dependency needed. The client URL-encodes the address, sends the key as a Bearer token, unwraps the envelope, and returns the Result object:

class ParserError extends Error {}

async function parseAddress(address, mode = "speculative") {
  const encoded = encodeURIComponent(address.trim());
  const url = `${STHAN_BASE_URL}/v2/address-parser/usa/${encoded}?match=${mode}`;

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${STHAN_API_KEY}` },
  });
  if (!res.ok) throw new ParserError(`HTTP ${res.status}`);

  const envelope = await res.json();
  if (envelope.IsError) {
    throw new ParserError((envelope.Errors || []).join(", "));
  }
  return envelope.Result; // PascalCase envelope key -> camelCase fields inside
}

That's the whole integration. One call:

const result = await parseAddress(
  "1600 pennsylvania ave nw apt 4b washington dc 20500"
);

console.log(result.addressNumber);  // 1600
console.log(result.streetName);     // PENNSYLVANIA
console.log(result.streetPostType); // AVE
console.log(result.unitType, result.unitNumber);          // apt 4b
console.log(result.city, result.stateCode, result.zipCode); // WASHINGTON DC 20500

Choose a match mode

The match parameter controls how much typo tolerance the parser applies while standardizing components. The same call supports four modes, from strictest to loosest:

If you omit match, the endpoint defaults to speculative for the widest recovery. Whichever mode you pick, the location-defining parts of the address - the primary number, ordinal, directional, state, and the street's core name - are never substituted. A looser mode only widens tolerance for misspellings of the same street.

Map the components to your fields

Each component comes back as its own field, so mapping them to database columns is a direct copy. The fields you'll use most:

A few more components cover edge cases: streetPreType, streetPreMod, streetPreSep, and streetPostMod capture pre/post modifiers in unusual street names (for example "Avenue of the Americas"). They're empty for ordinary addresses. Pair the parse with matchCode - a per-component breakdown (Matched / Corrected / Inferred / Unmatched / NotApplicable) - so you can tell which fields were trusted as-is versus corrected. Here is an Express route that parses the posted address and returns column-ready fields:

import express from "express";

const app = express();
app.use(express.json());

app.post("/parse-address", async (req, res) => {
  const raw = (req.body.address || "").trim();
  if (!raw) return res.status(400).json({ error: "address is required" });

  try {
    const result = await parseAddress(raw);
    res.json({
      addressNumber: result.addressNumber,
      streetPreDir: result.streetPreDir,
      streetName: result.streetName,
      streetType: result.streetPostType,
      streetPostDir: result.streetPostDir,
      unitType: result.unitType,
      unitNumber: result.unitNumber,
      city: result.city,
      state: result.stateCode,
      zipCode: result.zipCode,
      zip4: result.zip4,
    });
  } catch (err) {
    res.status(502).json({ error: "parse failed" });
  }
});

app.listen(3000);

The browser only ever talks to /parse-address on your own domain. The API key stays on the server, and the front end gets back one field per component.

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:

async function getToken() {
  const res = await fetch(`${STHAN_BASE_URL}/Auth/Token`, {
    headers: {
      profileName: process.env.STHAN_PROFILE_NAME,
      profilePassword: process.env.STHAN_PROFILE_PASSWORD,
    },
  });
  if (!res.ok) throw new Error(`Auth HTTP ${res.status}`);
  const envelope = await res.json();
  return envelope.Result.access_token;
}

// Use the token as the Bearer value instead of the static key.
// Cache it and refresh shortly before the 60-minute expiry.

Everything else - the endpoint, the envelope, the parsing - stays exactly the same.

Handle errors

Two status codes are worth handling explicitly so a hiccup never stalls a batch job:

• 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 retry rather than dropping the row.

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function parseWithRetry(address, mode = "speculative", retries = 2) {
  for (let attempt = 0; attempt <= retries; attempt++) {
    const encoded = encodeURIComponent(address.trim());
    const res = await fetch(
      `${STHAN_BASE_URL}/v2/address-parser/usa/${encoded}?match=${mode}`,
      { headers: { Authorization: `Bearer ${STHAN_API_KEY}` } }
    );

    if (res.status === 429 && attempt < retries) {
      await sleep(2 ** attempt * 1000); // 1s, then 2s
      continue;
    }
    if (!res.ok) throw new Error(`HTTP ${res.status}`);

    const envelope = await res.json();
    return envelope.Result;
  }
}

The exponential back-off (1s, then 2s) is enough for transient limits. For a large backfill, add a small delay between rows and a circuit breaker so one bad minute doesn't stall the whole queue.

What's next: confirm the parsed address is deliverable

Parsing gives you clean, structured components fast. It does not, on its own, confirm that mail or a package will actually arrive - a well-formed address can still point at a unit that no longer accepts delivery. When deliverability matters, run the address through the Address Verification API, which returns a deliverability status and appends ZIP+4 and county. It's the same envelope and the same fetch pattern - one GET against /v2/address-verification/usa/{address}. The Node.js walkthrough is here: Verify US Addresses in Node.js.

If you want users to enter a clean address in the first place, Address Autocomplete suggests complete addresses as they type. Pairing autocomplete (as users type) with parsing (to structure what you store) keeps your address data clean end to end.