# AddressZen TypeScript SDK

The AddressZen TypeScript SDK calls the AddressZen address API with typed functions over native fetch. It is [`@addresszen/sdk`](https://www.npmjs.com/package/@addresszen/sdk) on npm and runs in browsers and Node.js 22 or later.

```bash
npm install @addresszen/sdk
```

search.tsts

```ts
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](/docs/data/supported-countries.md) for the full list.

[Address verification](/docs/sdks/typescript/address-verify.md) 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](/docs/sdks/typescript/endpoints/.md).
* **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](/docs/sdks/typescript/endpoints/.md).** 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`](/docs/sdks/typescript/autocomplete.md).
* **[llms.txt](https://docs.addresszen.com/llms.txt).** An index of every page on this site.
* **[OpenAPI spec](https://openapi.addresszen.com/openapi.json).** The API contract the SDK is generated from.
* **[AI Assist](/docs/guides/llms.md).** 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](/docs/sdks/typescript/errors.md).