@ideal-postcodes/core-browser

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

@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. 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.

This library is transpiled to modern ES6 and modules. It should be consumed by a bundler or transpiler (e.g. webpack, parcel, rollup) for minification, module resolution and specific browser support.

To support legacy browsers, you will also need to include fetch polyfill and ES3 transpilation.

Links

• Configuration & Usage
• Quickstart
• Client Documentation
• Core JS API Client Documentation
• npm Module
• GitHub Repository

Example Setup

• Webpack
• Parcel
• Rollup

Other JavaScript Clients

• Node.js Client Repository
• Bundled Browser Client Repository

Documentation

Configuration & Usage

• Install
• Instantiate and Use client
• Catch Errors

Install

npm install @ideal-postcodes/core-browser

Instantiate

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

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

Configuration options

Use

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.

---

Quickstart

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.

• Lookup a Postcode
• Search for an Address
• Search for an Address by UDPRN

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

Test

npm test

Licence

MIT