TypeScript icon, indicating that this package has built-in type declarations

    3.0.1 • Public • Published

    Ideal Postcodes Javascript Client

    JavaScript (browser) client for api.ideal-postcodes.co.uk

    CI Cross Browser Testing codecov Dependency Status

    npm version npm bundle size Release

    @ideal-postcodes/core-browser is the JavaScript browser client for api.ideal-postcodes.co.uk

    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 core-interface.ideal-postcodes.dev.

    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 lookupPostcode({ client: client, postcode: "SW1A2AA" });

    Catch Errors

    import { errors } from "@ideal-postcodes/core-browser";
    const { IdpcRequestFailedError } = errors;
    try {
      await lookupAddress({ client, 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 lookupPostcode({ client, postcode });

    Method options

    Search for an Address

    Return addresses associated with a given query

    const query = "10 downing street sw1a";
    const addresses = await lookupAddress({ client, 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 lookupUdprn({ client, udprn });

    Method options


    npm test




    npm i @ideal-postcodes/core-browser

    DownloadsWeekly Downloads






    Unpacked Size

    31.8 kB

    Total Files


    Last publish


    • cablanchard
    • mfilip