Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 1,000,000+ packages pre-installed, including @ideal-postcodes/core-browser with all npm packages installed. Try it out:

var coreBrowser = require("@ideal-postcodes/core-browser")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

@ideal-postcodes/core-browser v1.5.0

Browser javascript client for

Ideal Postcodes Javascript Client

JavaScript (browser) client for

CircleCI Cross Browser Testing codecov Dependency Status

npm version npm bundle size Release

@ideal-postcodes/core-browser is the JavaScript browser client for

Our JavaScript client implements a common interface defined at @ideal-postcodes/core-interface.

High level client documentation can be found at core-interface.

In depth client documentation can be found at

Tested against a suite of modern and legacy, mobile and desktop browsers.

@ideal-postcodes/core-browsershould be consumed by a bundler or transpiler (e.g. webpack, parcel, rollup) for minification, module resolution and specific browser support.

core-browser-bundled provides pre-bundled versions of core-browser, which can be immediately dropped into a page.


Example Setup

Webpack Status

Parcel Status

Rollup Status

Polymer Status

Other JavaScript Clients


Configuration & Usage


npm install @ideal-postcodes/core-browser


import { Client } from "@ideal-postcodes/core-browser"

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

HTTP Agent and legacy browser support

core-browser uses the Fetch API under the hood to facilitate HTTP requests.

A configuration object can be passed to the Client constructor as a second argument to override certain attributes on the Request of all subsequent fetch requests. Request configuration is documented here.

If you need to support older browsers, please include a fetch polyfill and transpile this library down to ES3. Alternatively use one of our pre-transpiled outputs at ideal-postcodes/core-browser-bundled.


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


npm test



RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free