postcodes.io client

Abstracts access to the postcodes.io API.

var PostcodesIO = require('postcodesio-client');
var postcodes = new PostcodesIO();
 
postcodes.lookup('EC1V 9LB').then(postcode => {
    console.log(postcode);
 
    // {
    //   "postcode": "EC1V 9LB",
    //   "admin_district": "Islington",
    //   "longitude": -0.091247681768113,
    //   "latitude": 51.5278436902703,
    //   "region": "London",
    //   ...
    // }
});

Installation

$ npm install postcodesio-client

Usage

Create an instance of the client, providing options if you wish:

var PostcodesIO = require('postcodesio-client');
 
var postcodes = new PostcodesIO('https://api.postcodes.io', {
    headers: { 'User-Agent': 'MyAwesomeApp/1.0.0' } // default {} - extra headers
});

Make requests using Promises:

postcodes
    .lookup('EC1V 9LB')
    .then(function (postcode) {
        console.log(postcode);
    }, function (error) {
        console.log('oh no, it failed ;_;');
    });

Not found (404) responses from the API are not considered errors. Instead, the output will be null.

postcodes.lookup('F4K3AA').then(postcode => {
    console.log(postcode);
    // null
});

Only Promises (Promises/A+) are supported - callbacks are not. The following two sections specify exactly how you can apply Promises to the reference below.

Promises

postcodes
    .method(parameters...)
    .then(function (outputs...) {
 
    }, function (error) {
 
    });

method - the method you want to call
parameters - any arguments specific to that method (see Methods)
error - instance of Error
outputs - any outputs for that method (see Methods)

Both parameters and outputs can mean zero, one, or many arguments. These are specified for each method.

Methods

Lookup

Get lots of data for a postcode or outcode.

postcodes.lookup(code)

Parameters:

code - string - the postcode or outcode to retrieve

Outputs:

data - Postcode or Outcode - the resulting postcode/outcode data

This may also be called explicitly as postcodes.lookupPostcode(postcode) or postcodes.lookupOutcode(outcode).

Near Coordinate

Find postcodes closest to a coordinate.

postcodes.near(latitude, longitude)

This may also be called explicitly as postcodes.nearCoordinate(latitude, longitude, options).

Parameters:

latitude - number - the latitude of the coordinate
longitude - number - the longitude of the coordinate
options - object - optional, only available with an explicit call

Outputs:

postcodes - array of Postcode - the nearby postcodes

Near Postcode

Find the postcodes closest to another postcode.

Warning: results may include the original postcode.

postcodes.near(postcode)

This may also be called explicitly as postcodes.nearPostcode(postcode).

Parameters:

postcode - string - the postcode to search around

Outputs:

postcodes - array of Postcode - the nearby postcodes

Reverse Geocode

Find the single closest postcode to a coordinate.

postcodes.reverseGeocode(latitude, longitude)

Parameters:

latitude - number - the latitude of the coordinate
longitude - number - the longitude of the coordinate

Outputs:

postcode - Postcode - the nearby postcode

Validate

Validates that the postcode exists. (Means it is in the official Royal Mail Postcode Address File).

postcodes.validate(postcode)

Parameters:

postcode - string - the postcode to retrieve

Outputs:

exists - boolean - indicates existence of postcode

Random

Retrieve a random postcode. Not really sure why you'd want to do this, but here it is...

postcodes.random()

Outputs:

postcode - Postcode - a random postcode

Types

Postcode

Example:

{
    "postcode": "EC1V 9LB",
    "quality": 1,
    "eastings": 532506,
    "northings": 182719,
    "country": "England",
    "nhs_ha": "London",
    "admin_county": null,
    "admin_district": "Islington",
    "admin_ward": "Bunhill",
    "longitude": -0.091247681768113,
    "latitude": 51.5278436902703,
    "parliamentary_constituency": "Islington South and Finsbury",
    "european_electoral_region": "London",
    "primary_care_trust": "Islington",
    "region": "London",
    "parish": null,
    "lsoa": "Islington 023A",
    "msoa": "Islington 023",
    "nuts": null,
    "incode": "9LB",
    "outcode": "EC1V",
    "ccg": "NHS Islington"
}

Outcode

Example:

{
    "outcode": "EC1V",
    "longitude": -0.0981811622126924,
    "latitude": 51.5266761246198,
    "northings": 182576,
    "eastings": 532028,
    "admin_district": [
        "Hackney",
        "Islington"
    ],
    "parish": [
        "Hackney, unparished area",
        "Islington, unparished area"
    ],
    "admin_county": [],
    "admin_ward": [
        "Bunhill",
        "Hoxton West",
        "Clerkenwell",
        "Hoxton East & Shoreditch",
        "St Peter's"
    ],
    "country": [
        "England"
    ]
}

Testing

Install the development dependencies first:

$ npm install

Then run the tests:

$ npm test

Support

Please open an issue on this repository.

Authors

James Billingham james@jamesbillingham.com

License

MIT licensed - see LICENSE file