Skip to main content

Ideal Postcodes TypeScript SDK

@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.

npm install @ideal-postcodes/sdk
search.tsts
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.
  • 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.
  • 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. 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.
  • Build with AI. 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.