Ideal Postcodes
All updates

TypeScript SDK

@ideal-postcodes/sdk is our new TypeScript SDK for the Ideal Postcodes API. It supersedes @ideal-postcodes/core-axios and @ideal-postcodes/core-node with one package that runs in browsers and Node.js 22 or later, has no runtime dependencies and covers every current API operation with generated types.

Details

  • Native fetch: Requests use the runtime's own fetch, so there is no Axios or Node-specific client to install or keep up to date
  • No runtime dependencies: Installing the SDK adds nothing else to your dependency tree
  • Tree-shakeable: Each operation is a named export, so bundlers keep only what you import. A client and findAddress come to about 4.4 kB minified and gzipped
  • Every current operation: Postcode lookup, address search, UPRN lookup, address cleanse, email and phone validation, plus key, licensee and configuration management
  • Types from the OpenAPI spec: Every request and response is typed, including Royal Mail PAF fields and each dataset's native record
  • Autocomplete helper: createAutocomplete debounces keystrokes and exposes find and resolve, ready to wire to your own search box. A search superseded by newer typing resolves undefined rather than throwing, so fast typists produce no unhandled rejections
  • Postcode lookup helper: lookupPostcode returns a postcode's addresses and total, the count across all pages. For an unknown postcode it returns the closest matching postcodes instead of throwing
  • Client options: timeoutMs rejects any request that runs too long with a TimeoutError, and headers sends default headers, such as User-Agent, with every request
  • React and Preact: Optional TanStack Query adapters provide query options for every operation
  • Typed errors: HTTP failures throw an ApiError with the status, API error code and message. Pass throwOnError: false to get { data, error } instead
  • Management Key kept out of URLs: Account operations send your Management Key in the Authorization header, so it never appears in request URLs, proxy logs or browser history
  • Agent skill: npx skills add ideal-postcodes/skills gives coding agents setup guides and a reference for each operation

Start with the TypeScript SDK documentation. Moving from core-axios, core-node or core-browser? The migration guide maps each old call to its SDK equivalent.