postcodes.js v1.0.3

Example: Find data about the postcode "SW1W 0DT" and output the latitude and longitude.

Postcodes.lookup("SW1W 0DT").then(result => {
  // outputs "51.494853 -0.145828"
  console.log(result.latitude, result.longitude);
});

Design

Postcodes.js is designed with efficiency and speed at its heart. Postcode.js is an API wrapper for the Postcodes.io API, which is a free API for finding information and performing other operations on UK postcodes. By default, Postcodes.js uses the public API provided at api.postcodes.io, however, due to Postcodes.io being open source, it's possible to host your own instance and configure Postcodes.js to use that instance. Postcodes.js, by default, uses a cache shared between all of it's instances that caches up to 10,000 results for a maximum of 30 days, greatly improving speed for results already cached and decreasing the amount of API calls needed. It is possible to disable caching all together or provide your own cache to Postcodes.js.

Basic Usage

You can install Postcodes.js through NPM:

$ npm i postcodes.js

You can then include the library in Node like:

const PostcodesJS = require("postcodes.js");
const Postcodes = new PostcodesJS();

You can then perform operations such as postcode data lookup:

Postcodes.lookup("SW1W 0DT").then(result => {
  console.log(result);
});

Example Usages

Use callbacks instead of promises:

const PostcodesJS = require("postcodes.js");
const Postcodes = new PostcodesJS.Callbacks();

Postcodes.lookup("SW1W 0DT", function(error, result) {
  console.log(result);
});

Lookup postcode data:

Postcodes.lookup("SW1W 0DT").then(result => {
  console.log(result);
});

Bulk lookup postcodes:

Postcodes.bulkLookup(["SW1W 0DT", "SW1A 2AA"]).then(result => {
  console.log(result);
});

Lookup postcodes by co-ordinates:

Postcodes.coords({ longitude: -0.145828, latitude: 51.494853 }).then(result => {
  console.log(result);
});

Bulk lookup postcodes by mutliple co-ordinates:

Postcodes.bulkCoords([
  { latitude: 51.494853, longitude: -0.145828 },
  { latitude: 51.503297, longitude: -0.127882 }
]).then(result => {
  console.log(result);
});

Get random postcode:

Postcodes.random().then(result => {
  console.log(result);
});

Validate a postcode is a valid postcode:

Postcodes.validate("WRONG POSTCODE").then(result => {
  // outputs false
  console.log(result);
});

Autocomplete start of a postcode:

Postcodes.autocomplete("SW1A").then(result => {
  console.log(result);
});

Query postcode information:

Postcodes.query("SW1W 0DT").then(result => {
  console.log(result);
});

Get data about a terminated postcode (a postcode that is no longer in use):

Postcodes.terminated("E1W 1UU").then(result => {
  console.log(result);
});

Get data about an outcode:

Postcodes.outcode("SW1W").then(result => {
  console.log(result);
});

Get nearest outcodes from an outcode:

Postcodes.nearestOutcode("SW1W").then(result => {
  console.log(result);
});

Get outcode from co-ordinates:

Postcodes.outcodeFromCoord({ longitude: -0.145828, latitude: 51.494853 }).then(
  result => {
    console.log(result);
  }
);

Use different Postcodes.io host URL:

const Postcodes = new PostcodesJS({
  host: "postcodesio.example.com"
});

Disable caching:

const Postcodes = new PostcodesJS({
  cache: false
});

Provide custom cache:

const LRUCache = require("lru-cache");
const Postcodes = new PostcodesJS({
  cacheInstance: new LRUCache({
    max: 10000,
    maxAge: 90 * 24 * 60 * 60 * 1000
  })
});

Use HTTP (unsecure) connection instead of default HTTPS (secure) connection:

const Postcodes = new PostcodesJS({
  https: false
});

Change hashing algorithm used for hashing queries to be saved in the cache (defaults to "sha256"). Can provide any hashing algorithm name that can be used with crypto.createHash(hashingAlgorithm).

const Postcodes = new PostcodesJS({
  hashingAlgorithm: "md5"
});

Provide a useragent to be used with requests to the API:

const Postcodes = new PostcodesJS({
  useragent: "Custom Useragent"
});

Credit

Author: Tom

License

MIT