Nine Parsecs from Milwaukee
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    ideal-postcodespublic

    Ideal-Postcodes.co.uk Node.js Library Build Status

    Ideal Postcodes is a simple JSON API to query UK postcodes and addresses. Find out more at Ideal-Postcodes.co.uk

    Our API is based off Royal Mail's Postcode Address File and is updated daily. Each convenience method incurs a small charge (typically 2p) - free methods are labelled as free and based off open data sources.

    Getting Started

    Install

    $ npm install ideal-postcodes

    Create a Key

    Sign up at Ideal-Postcodes.co.uk and create a key.

    Configure

    Include your api key when requiring the ideal-postcodes module. This will return an client, which can be used to perform various tasks on the API such as looking up a postcode.

    var idealPostcodes = require("ideal-postcodes")("your_key_goes_here")

    Methods

    Each client instance provides a number of convenience methods to allow you to get specific jobs done quickly and easily. These convenience methods are listed below:

    Get all addresses for a postcode (docs)

    Retrieve a complete list of addresses at a given postcode.

    idealPostcodes.lookupPostcode(postcode, callback)
    • postcode (string). The postcode to search.
    • callback (function). Standard callback which accepts 2 arguments: error and addresses

    Use the postcode "ID1 1QD" to test integration for free. The complete list of test postcodes is available in the documentation. Note that this method returns an empty array if no matching postcode is found.

    idealPostcodes.lookupPostcode("ID1 1QD", function (error, addresses) {
        if (error) {
            // Implement some error handling 
        } 
        console.log(addresses); 
    });
     
    // [ { 
    // postcode: 'ID1 1QD', 
    // post_town: 'LONDON', 
    // line_1: 'Kingsley Hall', 
    // line_2: 'Powis Road', 
    // line_3: '',  
    // organisation_name: '', 
    // building_name: 'Kingsley Hall', 
    // udprn: 12345678  
    //  ...and so on... 
    // }, ... 

    Search for an address (docs)

    This will perform a search for addresses which match your search term.

    idealPostcodes.lookupAddress(searchQuery, callback)
    • searchQuery (string | object). The address to search for. If string is passed, the string is used as a search term and default settings are applied (limit 10 results, return first page). If an object is provided, this object requires a query attribute pointing to your search string. It also accepts optional limit and page attributes.
    • callback (function). Standard callback which accepts 2 arguments: error and searchResults

    Use the address "ID1 1QD" to test integration for free. The complete list of test methods is available in the documentation.

    idealPostcodes.lookupAddress("ID1 1QD", function (error, searchResults) {
        if (error) {
            // Implement some error handling 
        } 
        console.log(searchResults); 
    });
     
    // or alternatively 
     
    idealPostcodes.lookupAddress({
        query: "ID1 1QD",   // required 
        limit: 10,   // optional 
        page: 0  // optional 
    }, function (error, searchResults) {
        if (error) {
            // Implement some error handling 
        } 
        console.log(searchResults); 
    });
     
    // { 
    //   "result":{ 
    //     "total":2, 
    //     "limit":10, 
    //     "page":0, 
    //     "hits":[{ 
    //       "dependant_locality" : "", 
    //       "postcode_type" : "L", 
    //       "po_box" : "", 
    //       "post_town" : "LONDON", 
    //       "delivery_point_suffix" : "1A", 
    //       "double_dependant_locality" : "", 
    //       "su_organisation_indicator" : " ", 
    //       "longitude" : -0.127695242183412, 
    //       "department_name" : "", 
    //       "district" : "Westminster", 
     
    //       continued... 

    Get nearby postcode for a given geolocation (docs)

    Retrieve the nearest postcodes for a given geolocation. (Free to use)

    idealPostcodes.queryLocation(location, callback)
    • location (object). Requires a longitude (number) and latitude (number) attribute. Limit (number) and radius (number) are optional.
    • callback (function). Standard callback which accepts 2 arguments: error and locations
    idealPostcodes.queryLocation({
        longitude: -0.20864, // Required 
        latitude: 51.48994, // Required 
        limit: 10  ,  // Optional, limits number of results 
        radius: 100 // Optional, limits search radius 
    }, function (error, locations) {
        if (error) {
            // Implement some error handling 
        } 
        console.log(locations); 
    });
     
    // [{ 
    //  postcode: "W14 9DT", 
    //  northings: 178299, 
    //  eastings: 524466, 
    //  longitude: -0.208644362766368, 
    //  latitude: 51.4899488390558, 
    //  distance: 1.029038833 
    //  }, ... 

    Retrieve an address using UDPRN (docs)

    Retrieve the specific address for a specific UDPRN.

    idealPostcodes.lookupUdprn(udprn, callback)
    • udprn (string). A number which uniquely identifies the address.
    • callback (function). Standard callback which accepts 2 arguments: error and locations

    Note that this method returns null if no matching address is found. Use the test UDPRN "0" to test integration for free.

    idealPostcodes.lookupUdprn(0, function (error, address) {
        if (error) {
            // Implement some error handling 
        } 
        console.log(address); 
    });
     
    // { 
    // "postcode":"ID1 1QD", 
    // "postcode_inward":"IQD", 
    // "postcode_outward":"ID1", 
    // "post_town":"LONDON", 
    // "dependant_locality":"", 
    // "double_dependant_locality":"", 
    // "thoroughfare":"Barons Court Road", 
    // "dependant_thoroughfare":"", 
    // "building_number":"2", 
    // "building_name":"", 
    // "sub_building_name":"", 
    // "po_box":"", 
    // "department_name":"", 
    // "organisation_name":"", 
    // "udprn":25962203, 
    // "postcode_type":"S", 
    // "su_organisation_indicator":"", 
    // "delivery_point_suffix":"1G", 
    // "line_1":"2 Barons Court Road", 
    // "line_2":"", 
    // "line_3":"", 
    // "premise":"2", 
    // "county": "", 
    // "district": "Hammersmith and Fulham", 
    // "ward": "North End", 
    // "longitude":-0.208644362766368, 
    // "latitude":51.4899488390558, 
    // "eastings":524466, 
    // "northings":178299 
    // }    

    Utility Methods

    Listed below are free utility methods, e.g. finding the status of your key.

    Find out if your key is in a usable state (docs)

    Find out if your key is in a usable state. E.g. it has a positive balance, it is currently under your defined usage limits, etc.

    idealPostcodes.keyAvailability(callback)
    • callback (function). Standard callback which accepts 2 arguments: error and key. Key contains a boolean available attribute which indicates whether your key is currently usable.
    idealPostcodes.keyAvailability(function (error, key) {
        if (error) {
            // Implement some error handling 
        } 
        console.log(key.avaialble); // => true   
    });

    Find out private key information (docs)

    This method reveals private information about your key such as the lookup balance, whitelisted URLs, etc. It requires a secret key to be invoked.

    idealPostcodes.keyDetails(callback)
    • callback (function). Standard callback which accepts 2 arguments: error and key.
    idealPostcodes.keyDetails(function (error, key) {
        if (error) {
            // Implement some error handling 
        } 
        console.log(key); 
    });
     
    // { 
    //   "lookups_remaining": 8288, 
    //   "daily_limit": { 
    //       "limit": 1000, 
    //       "consumed": 361 
    //   }, 
    //   "individual_limit": { 
    //       "limit": 15 
    //   }, 
    //   "allowed_urls": [ 
    //       "https://www.foo.com", 
    //       "https://www.bar.co.uk" 
    //   ], 
    //   "notifications": { 
    //       "emails": ["baz@bar.co.uk"], 
    //       "enabled": true 
    //   }, 
    //       "automated_topups": { 
    //       "enabled": true 
    //   } 
    // } 

    If you intend to use this method, you must pass your secret key (which can be found on your account page) along with your API key when instantiating the client. E.g.

    var idealPostcodes = require("ideal-postcodes")("your_key_goes_here", "secret_key_goes_second");

    Error Handling

    Each convenience method adopts the standard javascript error handling method. I.e. Any error is passed as the first argument of the callback. E.g.

    idealPostcodes.lookupPostcode("ID1 1QD", function (error, addresses) {
        if (error) {
            // Handle your errors here 
        } 
    });

    Possible errors to look out for are listed in the documentation.

    Command Line Interface

    This module has been movied to ideal-postcodes-cli

    Documentation

    More documentation can be found here

    License

    MIT

    install

    npm i ideal-postcodes

    Downloadslast 7 days

    221

    version

    1.0.0

    license

    MIT

    repository

    github.com

    last publish

    collaborators

    • avatar