UK Postcode lookup API. Wrapper for API uses Royal Mail's Postcode Address File (PAF).

npm install ideal-postcodes
5 downloads in the last month

Ideal Postcodes Node.js API Wrapper

Get a full list of addresses for any given UK postcode using the API. We use the most accurate addressing database in the UK, Royal Mail's Postcode Address File.

Getting Started

Implementation can be finished in minutes. Simply install, apply your key and you can start performing UK address lookups.


npm install ideal-postcodes

Get an API Key

Get a key at Try out the service with the test postcode 'ID1 1QD'


Include your api key when requiring the ideal-postcodes module, will return an instance that you can use to make lookups.

var api_key = "your key goes here"
var idealPostcodes = require('ideal-postcodes')(api_key)


Perform lookups by calling #lookupPostode. Test using the postcode "ID1 1QD".

If no addresses are found, the method will return an empty array.

idealPostcodes.lookupPostcode("ID1 1QD", function (error, result) {
    if (error) throw error; // Implement some error handling

// => Will output an array of addresses
//  {
//    "result": [
//      {
//        "postcode": "ID1 1QD",
//        "post_town": "LONDON",
//        "line_1": "Kingsley Hall",
//        "line_2": "Powis Road",
//        "line_3": ""
//      }
//    ],
//    "code": 2000,
//    "message": "Success"
//  }


PAF is licensed from the Royal Mail and is, unfortunately, not free to use. Ideal Postcodes aims to be simple to use and fairly priced to use for web and mobile developers.

We charge 2p per external lookup.


More documentation can be found here



npm loves you