Skip to content
Node.js client for api.ideal-postcodes.co.uk
TypeScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
lib
test
.gitignore
CHANGELOG.md
LICENSE
README.md
package-lock.json
package.json
tsconfig.json
tslint.json

README.md

Ideal Postcodes Node.js

Node.js client for api.ideal-postcodes.co.uk

CircleCI Coverage Status Dependency Status npm version install size

@ideal-postcodes/core-node is the Node.js 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.

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

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

Links

Other JavaScript Clients

Documentation

Configuration & Usage

Install

npm install @ideal-postcodes/core-node

Instantiate

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

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
  }
}

Configure HTTP Agent

core-node uses got as its underlying HTTP client. The Ideal Postcodes API client can also be optionally configured with a got options object which is fed to got on every request.

Be aware this options object will overwrite any existing got HTTP request parameters.

const client = new Client({ api_key: "iddqd" }, {
  cache: new Map, // Instantiate a cache: https://github.com/sindresorhus/got#cache-1
  hooks: {        // Hook into HTTP responses: https://github.com/sindresorhus/got#hooksafterresponse
    afterResponse: response => {
      modify(response);
      log(response);
      return response;
    }
  },
});
Proxy HTTP Requests

You can proxy requests by configuring the underlying got HTTP client.

const tunnel = require("tunnel");

const client = new Client(config, {
  agent: tunnel.httpOverHttp({
    proxy: {
      host: "localhost"
    }
  })
});

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

You can’t perform that action at this time.