# Ideal Postcodes TypeScript SDK

[`@ideal-postcodes/sdk`](https://www.npmjs.com/package/@ideal-postcodes/sdk) calls the Ideal Postcodes UK address API from TypeScript, with a typed function for each operation over native `fetch`. It runs in browsers and Node.js 22 or later.

Use the `ak_test` key for limited testing. It is capped at 5 requests per day. A new account comes with a free test balance for fuller testing.

```bash
npm install @ideal-postcodes/sdk
```

search.tsts

```ts
import { createIdpcClient, findAddress } from "@ideal-postcodes/sdk";

const client = createIdpcClient({ apiKey: "ak_test" });
const { data } = await findAddress({
  client,
  query: { query: "9 Malyons Road" },
});
console.log(data.result.hits);
```

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

## Data sources

UK addresses come from Royal Mail's Postcode Address File (PAF) and Ordnance Survey AddressBase, depending on the datasets on your key. Each address carries a `dataset` field naming its source, such as `paf` or `abp`.

## Benefits

* **Native fetch.** Runs in browsers and Node.js 22 or later with no runtime dependencies. It supersedes `@ideal-postcodes/core-interface` and its Axios client, `@ideal-postcodes/core-axios`. See [migrating from the core clients](/docs/sdks/typescript/migrate-from-core.md).
* **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 current API operation.** Each one is a 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.

## Coding agents

* **Agent skill.** `npx skills add ideal-postcodes/skills` installs the `ideal-postcodes-js-sdk` skill: setup, autocomplete, 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.ideal-postcodes.co.uk/llms.txt).** An index of every page on this site.
* **[OpenAPI spec](https://openapi.ideal-postcodes.co.uk/openapi.json).** The API contract the SDK is generated from.
* **[Build with AI](/docs/guides/llms.md).** Every asset for AI agents.

## Authentication

Set `apiKey` on the client. Private account operations also need a Management Key, set as `userToken`. Never put a Management Key in browser code.

## Errors

HTTP errors throw an `ApiError` with the HTTP `status` and the API error `code` and `message`. See [error handling](/docs/sdks/typescript/errors.md).