@ideal-postcodes/core-interface

Javascript API interface for api.ideal-postcodes.co.uk

@ideal-postcodes/core-interface is an environment agnostic implementation of the Ideal Postcodes javascript API client interface.

If you are looking for a browser or node.js client, please check out the downstream clients in the links below.

Links

• API Documentation
• NPM Module
• Github Repository
• Browser Client Repository
• Node.js Client
• Typings Repository
• Fixtures Repository

Documentation

Methods

Usage

To install, pick one of the following based on your platform

# For browser client
npm install @ideal-postcodes/core-browser

# For node.js client
npm install @ideal-postcodes/core-node

# For generic interface (you need to supply your own HTTP agent)
npm install @ideal-postcodes/core-interface

Instantiate a client with,

const api_key = "iddqd";

const client = new Client({ api_key });

// Only api_key is required by core-node and core-browser - all others are optional
// The agentless interface requires explicit configuration

Configuration options outlined in the docs

Resource Methods

Resources defined in the API documentation are exposed on the client. Each resource exposes a method (#retrieve, #list, etc) which maps to a resource action.

These methods expose a low level interface to execute HTTP requests and observe HTTP responses. They are ideal if you have a more complex query or usecase where low level access would be useful.

Resource methods return a promise with a HTTP response object type.

Retrieve

Requesting a resource by ID (e.g. a postcode lookup for postcode with ID "SW1A 2AA") maps to the #retrieve method.

The first argument is the resource ID. The second argument is an object which accepts header and query attributes that map to HTTP header and the request querystring.

client.resourceName.retrieve("id", {
  query: {
    api_key: "foo",
    tags: "this,that,those",
    licensee: "sk_99dj3",
  },
  header: {
    "IDPC-Source-IP": "8.8.8.8",
  },
  timeout: 5000,
});

List

Reqesting a resource endpoint (e.g. an address query to /addresses) maps to the #list method.

client.resourceName.list({
  query: {
    api_key: "foo",
    query: "10 downing street"
  },
  header: {
    "IDPC-Source-IP": "8.8.8.8",
  },
  timeout: 5000,
});

The first and only argument is an object which accepts header and query attributes that map to HTTP header and the request querystring.

Custom Actions

Some endpoints are defined as custom actions. E.g. /keys/:key/usage. These can be invoked using the name of the custom action.

E.g. for key usage data extraction

client.keys.usage(api_key, {
  query: {
    tags: "checkout,production"
  },
  header: {
    Authorization: 'IDEALPOSTCODES user_token="foo"',
  },
  timeout: 5000,
});

Available Resources

• Postcodes
• Addresses
• Autocomplete
• UDPRN
• UMPRN
• Keys

Postcodes

Retrieve addresses for a postcode.

client.postcodes.retrieve("SW1A2AA", {
  header: {
    "Authorization": 'IDEALPOSTCODES api_key="iddqd"',
  },
}).then(response => {
  const addresses = response.body.result;
}).catch(error => logger(error));

See Postcode resource API documentation

Addresses

Search for an address.

client.addresses.list({
  query: {
    query: "10 Downing street",
  },
  header: {
    "Authorization": 'IDEALPOSTCODES api_key="iddqd"',
  },
}).then(response => {
  const addresses = response.body.result.hits;
}).catch(error => logger(error));

See addresses resource API documentation

Autocomplete

Autocomplete an address given an address partial.

client.autocomplete.list({
  query: {
    query: "10 Downing stre",
  },
  header: {
    "Authorization": 'IDEALPOSTCODES api_key="iddqd"',
  },
}).then(response => {
  const suggestions = response.body.result.hits;
}).catch(error => logger(error));

See autocomplete resource API documentation

UDPRN

Retrieve an address given a UDPRN

client.udprn.retrieve("12345678", {
  header: {
    "Authorization": 'IDEALPOSTCODES api_key="iddqd"',
  },
}).then(response => {
  const address = response.body.result;
}).catch(error => logger(error));

See UDPRN resource API documentation

UMPRN

Retrieve a multiple residence premise given a UMPRN.

client.umprn.retrieve("87654321", {
  header: {
    "Authorization": 'IDEALPOSTCODES api_key="iddqd"',
  },
}).then(response => {
  const address = response.body.result;
}).catch(error => logger(error));

See UMPRN resource API documentation

Keys

Find out if a key is available.

client.keys.retrieve("iddqd", {})
  .then(response => {
    const { available } = response.body.result;
  }).catch(error => logger(error));

Get private information on key (requires user_token).

client.keys.retrieve("iddqd", {
  header: {
    "Authorization": 'IDEALPOSTCODES user_token="secret-token"',
  },
}).then(response => {
  const key = response.body.result;
}).catch(error => logger(error));

Get key usage data.

client.keys.usage("iddqd", {
  header: {
    "Authorization": 'IDEALPOSTCODES user_token="secret-token"',
  },
}).then(response => {
  const key = response.body.result;
}).catch(error => logger(error));

See Keys resource API documentation

Errors

For more advanced use cases, this library also exports:

• Class implementations for Ideal Postcodes API errors that inherit from Error
• A parser that converts raw error data into an error instance

Usage

Aside from inspecting the HTTP request status code and/or JSON body response codes, you may also test for specific error instances.

Errors that don't inherit from IdealPostcodesError would indicate some kind of error external to the API (e.g. bad network, request timeout).

import { errors } from "@ideal-postcodes/core-interface";
const { IdpcPostcodeNotFoundError } = errors;

// Handle a specific error
if (error instanceof IdpcPostcodeNotFoundError) {
  // You got yourself an invalid API Key
}

// Alternatively use a switch statement
switch (true) {
  case error instanceof IdpcPostcodeNotFoundError:
    // You got yourself an invalid API Key
  default:
    // Default error handling path
}

Error Prototype Chain

All errors inherit from Javascript's Error prototype.

Errors are grouped by HTTP status code classes.

Specific errors may be supplied for the following reasons:

• Convenience: They are frequently tested for (e.g. invalid postcode, postcode not found)
• Deverloper QoL. They are useful for debug purposes during the implementation stages

Prototype Chain

# Parent class inherits from Javascript Error. Returned if no JSON Response body
IdealPostcodesError < Error
|
|- IdpcApiError # Generic Error Class, returned if JSON response body present
   |
   |- IdpcBadRequestError          # 400 Errors
   |- IdpcUnauthorisedError        # 401 Errors
   |- IdpcRequestFailedError       # 402 Errors
   |
   |- IdpcResourceNotFoundError    # 404 Errors
   |  |- IdpcPostcodeNotFoundError
   |  |- IdpcKeyNotFoundError
   |  |- IdpcUdprnNotFoundError
   |  |- IdpcUmprnNotFoundError
   |
   |- IdpcServerError              # 500 Errors

Error Parser

Errors consume a HTTP API response

import { errors } from "@ideal-postcodes/core-interface";
const { parse, IdpcPostcodeNotFoundError } = errors;

const invalidPostcodeUrl = "https://api.ideal-postcodes.co.uk/v1/postcodes/bad_postcode?api_key=iddqd"

const response = await fetch(invalidPostcodeUrl);

// Generate an error object if present, otherwise returns `undefined`
const error = parse(response);

// Handle the error
if (error instanceof IdpcPostcodeNotFoundError) ...

Test

npm test

License

MIT

Changelog

1.1.1 (2019-06-06)

Bug Fixes

• Karma-Typescript: Explicitly exclude typings module (ff40c04)