Skip to main content

AddressZen TypeScript SDK

The AddressZen TypeScript SDK calls the AddressZen address API with typed functions over native fetch. It is @addresszen/sdk on npm and runs in browsers and Node.js 22 or later.

npm install @addresszen/sdk
search.tsts
import { createZenClient, findAddress } from "@addresszen/sdk";

const client = createZenClient({ apiKey: "ak_test" });
const { data } = await findAddress({
  client,
  query: { query: "123 Main St", context: "USA" },
});
console.log(data.result.hits);

Pass the client to each operation. Each client holds its own configuration. Autocomplete and framework adapters use separate imports.

Which countries does it cover?​

Address search covers the US and the other countries enabled on your key. Each search runs in one country, set with context to a three-letter ISO 3166-1 code such as USA, CAN or JPN. Without context, the search uses your account's default country. Results for the US and its territories come from USPS ZIP+4. Other countries come from the country datasets on your key, such as Statistics Canada's National Address Register for Canada and the Universal Postal Union's address file for Japan. See supported countries for the full list.

Address verification covers US addresses only.

Why use the SDK?​

  • Native fetch. Runs in browsers and Node.js 22 or later with no runtime dependencies.
  • Generated from the OpenAPI spec. Every request and response schema is a TypeScript type, including the address model and each dataset's native fields.
  • Every public operation. Each API operation is one function with its own reference page.
  • Small. A client and findAddress come to 4.4 kB minified and gzipped. ESM bundlers drop the operations you do not import.

What is there for coding agents?​

  • Agent skill. npx skills add addresszen/skills installs the azn-js-sdk skill: setup, autocomplete, filters, errors, framework guides and a reference for each operation.
  • Endpoints. Every operation, grouped by resource, with its parameters, response type and a tested example.
  • Markdown pages. Add .md to any page URL for plain markdown, such as /docs/sdks/typescript/autocomplete.md.
  • llms.txt. An index of every page on this site.
  • OpenAPI spec. The API contract the SDK is generated from.
  • AI Assist. Every asset for AI agents.

How do I authenticate?​

Set apiKey on the client. Private account operations also need a Management Key, set as userToken. Never put a Management Key in browser code. HTTP errors throw an ApiError with the HTTP status and the API error code and message. See error handling.