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

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

High level client documentation can be found at 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.

Links

• Configuration & Usage
• Quickstart
• Client Documentation
• In Depth Client Documentation
• npm Module
• GitHub Repository

Other JavaScript Clients

• Browser Client Repository
• Bundled Browser Client Repository
• Axios-backed Client Repository

Documentation

Configuration & Usage

• Install
• Instantiate and Use client
• Catch Errors
• Configure Agent
  • Proxy HTTP Requests

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

import { lookupPostcode } from "@ideal-postcodes/core-node";

const addresses = await lookupPostcode({ client, postcode: "SW1A2AA" });

Catch Errors

import { lookupAddress, errors } from "@ideal-postcodes/core-node";

try {
  await lookupAddress({ client, query: "10 downing street" });
} catch (error) {
  if (error instanceof errors.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.

• 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

import { lookupPostcode } from "@ideal-postcodes/core-node";

const postcode = "id11qd";

const addresses = await lookupPostcode({ client, postcode });

Method options

Search for an Address

Return addresses associated with a given query

import { lookupAddress } from "@ideal-postcodes/core-node";

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

import { lookupUdprn } from "@ideal-postcodes/core-node";

const udprn = 23747771;

const address = await lookupUdprn({ client, udprn });

Method options

Test

npm test

Licence

MIT