Skip to main content

API Typings

API Typings


We maintain an npm package that contains TypeScript typings for the Ideal Postcodes API (

It defines:

  • The basic JSON objects returned by our APIs (e.g. addresses Address, autocomplete suggestions AddressSuggestion, API key status KeyStatus)
  • The overall shape of JSON responses returned by the API (e.g. postcode lookups PostcodesResponse, address autocomplete queries AddressSuggestionResponse, address search queries AddressQueryResponse)

Typings are exported to index.d.ts when published to npm. The typings in this repository are defined in lib/index.ts.


Install package

npm install --save-dev @ideal-postcodes/api-typings

Import interfaces and other definitions

// Import Address type
import { Address } from "@ideal-postcodes/api-typings";

let address: Address;

Benefits of Typings

Code Completion

Typings allow IDEs to provide a richer, more productive environment to develop integrations. This includes providing code completions and suggestions.


Type Checking

Compile time checks that your library or application appropriately consumes objects and data types returned by our APIs and client libraries

Type Checking

Inline Documentation

Our typings also bear documentation which can be rendered in your IDE as you work.


Non-TypeScript Projects

Your integration does not have to be exclusively TypeScript driven to benefit from this typings repository. Some IDEs (e.g. Visual Studio Code, Sublime Text, Atom) use TypeScript typings to provide inline code completion and documentation for plain JavaScript files. It is also possible to develop a partial, robust TypeScript integration against our services and subsequently incorporate it in a larger JavaScript project. TypeScript compiles down to plain JavaScript which can conform to ES3 and later. That output can be exported to other JavaScript projects.