Nitrogen Poisonous Monoxide
    Have ideas to improve npm?Join in the discussion! »

    @ideal-postcodes/core-node
    TypeScript icon, indicating that this package has built-in type declarations

    2.1.0 • Public • Published

    Ideal Postcodes Node.js

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

    codecov Dependency Status npm version install size Release CI

    @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

    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

    Install

    npm i @ideal-postcodes/core-node

    DownloadsWeekly Downloads

    1,330

    Version

    2.1.0

    License

    MIT

    Unpacked Size

    25.9 kB

    Total Files

    13

    Last publish

    Collaborators

    • avatar