zip-codes-api

TypeScript/JavaScript client for the ZIP Codes API — US & Canadian postal data: address validation + ZIP+4, ZIP/postal lookups, ZIP/postal & place autocomplete, radius search, distance, and 14 years of US Census ACS demographics.

Isomorphic (browser + Node 18+), zero runtime dependencies (uses native fetch), fully typed.

npm install zip-codes-api

import { ZipCodesClient } from "zip-codes-api";

// Public demo key works for demo codes (90210, 10001, M5V, ...). For everything else,
// get a free key at https://www.zip-codes.com/api/signup (2,500 credits/day, no card).
const client = new ZipCodesClient({ apiKey: "zc_test_DEMOAPIKEY000000000000" });

Single-target methods return the first result object; batch methods return the array of results. Pass { raw: true } for the full envelope. client.lastMeta holds the most recent response's meta (including credits).

Address validation + ZIP+4

address() validates and standardizes a US street address and appends ZIP+4. result.matches holds the candidate standardizations (more than one if the input is ambiguous) — for checkout, CRM intake, and mailing-list cleanup:

const res = await client.address("200 N Spring St, Los Angeles CA 90012");
const best = res.matches[0];
console.log(best.zip, best.zip4, best.delivery_point);

ZIP / postal code & place autocomplete

suggest() is a typo-tolerant typeahead for ZIP/postal codes and place names (not street addresses) — good for a code or city picker. Suggestions are in result.matches:

const res = await client.suggest("9021", { limit: 8, country: "US" });
for (const m of res.matches) console.log(m.name, m.state);

// Debounced ZIP / place picker (React/Vue/vanilla)
let t: ReturnType<typeof setTimeout>;
input.addEventListener("input", () => {
  clearTimeout(t);
  t = setTimeout(async () => {
    const { matches } = await client.suggest(input.value, { limit: 8 });
    render(matches); // ZIP codes / cities matching what the user typed
  }, 150);
});

ZIP / postal lookups

await client.quickZip("M5V");                 // Canadian FSA → city/province/coords
const z = await client.zip("90210", { include: ["timezone", "acs_demographic"] });
console.log(z.city, z.acs.current.demographic.sex_and_age.median_age.est);

Distance & radius

const d = await client.distance("90210", "10001");
console.log(d.distance.miles, d.bearing);

// Spatial mode: ACS aggregate in result.stats is coverage-weighted by each ZIP's pct_inside.
const r = await client.radius("90210", { max: 10, mode: "spatial", include: "acs_demographic" });
console.log(r.stats.acs.current.demographic.sex_and_age.total_population.est, "people within 10 mi");

Batch (up to 100; paid subscription key)

const rows = await client.zipBatch(["90210", "10001", "M5V"], { include: "timezone" });

Errors

Failures throw typed errors carrying the API's code, status, and requestId:

import { RateLimitError, InsufficientCreditsError, ValidationError } from "zip-codes-api";

try {
  await client.suggest("9021");
} catch (e) {
  if (e instanceof RateLimitError) console.log("retry after", e.retryAfter, "s");
  else if (e instanceof InsufficientCreditsError) { /* top up */ }
  else if (e instanceof ValidationError) console.log(e.code, e.message);
  else throw e;
}

The client retries 429 / 5xx automatically (honoring Retry-After), up to maxRetries (default 2).

Options

new ZipCodesClient({
  apiKey: "zc_live_...",
  baseUrl: "https://api.zip-codes.com", // default
  timeoutMs: 30000,                      // default
  maxRetries: 2,                         // default
  fetch: customFetch,                    // optional (Node < 18 polyfill)
});

Browser note

The API allows cross-origin requests. Don't ship a zc_live_ key in client-side code — front-end usage should call through your own backend, or use a key with per-key origin/IP restrictions configured in the API portal.

Links

• API docs: https://www.zip-codes.com/api/docs
• Get a free key: https://www.zip-codes.com/api/signup
• Python client: https://github.com/ZIP-Codes-API/zip-codes-api-python

License

MIT.