npm

Need private packages and team management tools?Check out npm Orgs. »

@ideal-postcodes/core-browser

1.0.2 • Public • Published

Ideal Postcodes Javascript Client

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

CircleCI codecov Dependency Status npm version npm bundle size

@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

Example Setup

Other JavaScript Clients

Documentation

Configuration & Usage

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.

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

install

npm i @ideal-postcodes/core-browser

Downloadsweekly downloads

35

version

1.0.2

license

MIT

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
Report a vulnerability