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

!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

- 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

$3

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

#### Install

``bash
npm install @ideal-postcodes/core-node
`

#### Instantiate

`javascript
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

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

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

#### Catch Errors

`javascript
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.

`javascript
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.

`javascript
const tunnel = require("tunnel");

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

---

$3

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

`javascript
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

`javascript
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

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

const udprn = 23747771;

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

Method options

Test

`bash
npm test
``

Licence

MIT