Novices Plagiarizing Mozart

    postcodesio-client

    0.3.4 • Public • Published

    postcodes.io client

    Abstracts access to the postcodes.io API.

    NPM Version Build Status Coverage Status

    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:

    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

    License

    MIT licensed - see LICENSE file

    Install

    npm i postcodesio-client

    DownloadsWeekly Downloads

    572

    Version

    0.3.4

    License

    MIT

    Unpacked Size

    44.6 kB

    Total Files

    7

    Last publish

    Collaborators

    • billinghamj
    • cuvva-old