As of June 2019, we've released a modern, revamped Node.js client at @ideal-postcodes/core-node. Documentation for the legacy client ideal-postcodes can be found here.

Ideal Postcodes Node.js

Node.js client for

CircleCI Coverage Status Dependency Status npm version install size

@ideal-postcodes/core-node is the node.js client for

Our javascript clients implement a common interface which is implemented at @ideal-postcodes/core-interface. In depth client documentation can be found at

@ideal-postcodes/core-node is tested against all maintained, stable releases. Specifically, our CI test suite targets the following versions:

  • Node.js 12
  • Node.js 10
  • Node.js 8


Other Javascript Clients


Configuration & Usage


npm install @ideal-postcodes/core-node


const { Client } = require("@ideal-postcodes/core-node");

// or, if applicable,
import { Client } from "@ideal-postcodes/core-node"

const client = new Client({ api_key: "iddqd" });

Configuration options


const addresses = await client.lookupPostcode({ postcode: "SW1A2AA" });

Catch Errors

const { IdpcRequestFailedError } = Client.errors;

try {
  await client.lookupAddress({ query: "10 downing street" });
} catch (error) {
  if (error instanceof IdpcRequestFailedError) {
    // IdpcRequestFailedError indicates a 402 response code 
    // Possibly the key balance has been depleted


The client exposes a number of simple methods to get at the most common tasks when interacting with the API. Below is a (incomplete) list of commonly used methods.

For a complete list of client methods, including low level resource methods, please see the core-interface documentation

Lookup a Postcode

Return addresses associated with a given postcode

const postcode = "id11qd";

const addresses = await client.lookupPostcode({ postcode });

Method options

Search for an Address

Return addresses associated with a given query

const query = "10 downing street sw1a";

const addresses = await client.lookupAddress({ query });

Method options

Search for an Address by UDPRN

Return address for a given udprn

Invalid UDPRN will return null

const udprn = 23747771;

const address = await client.lookupUdprn({ udprn });

Method options


@ideal-postcodes/core-node is tested on:

  • Node 8
  • Node 10
  • Node 12
npm test