README.md

Postcodes.io - NodeJS Client/Wrapper

An easy to use postcodes.io wrapper for NodeJS.

▶️ Install

Install the package with npm:

$ npm i node-postcodes.io

📋 Usage

const postcodes = require('node-postcodes.io')

Lookup

http://postcodes.io/docs#Postcode-Lookup

// single
let result = await postcodes.lookup('PO123AA')

// batch
let result = await postcodes.lookup(['PO123AA', 'PO123AB'])

// batch (with filter)
let result = await postcodes.lookup(['PO123AA', 'PO123AB'], {
    filter: 'postcode,longitude,latitude'
})

Geo

http://postcodes.io/docs#Geocode-Postcode

Single

//
let result = await postcodes.geo(51.7923246977375,  0.629834723775309)

// with optional params
let result = await postcodes.geo(51.7923246977375,  0.629834723775309, {
    limit: 10,
    radius: 10,
    wideSearch: false
})

Batch

//
let result = await postcodes.geo([
    {
        "longitude": 0.629834723775309,
        "latitude": 51.7923246977375,
        "radius": 1000,
        "limit": 5
    },{
        "longitude": -2.49690382054704,
        "latitude": 53.5351312861402,
        "radius": 1000,
        "limit": 5
    }
])

// with optional params
let result = await postcodes.geo([
    {
        "longitude": 0.629834723775309,
        "latitude": 51.7923246977375,
        "radius": 1000,
        "limit": 5
    },{
        "longitude": -2.49690382054704,
        "latitude": 53.5351312861402,
        "radius": 1000,
        "limit": 5
    }
], {
    filter: 'postcode,longitude,latitude',
    wideSearch: false
})

Random

http://postcodes.io/docs#Geocode-Postcode

let result = await postcodes.random()

Validate

http://postcodes.io/docs#Postcode-Validation

let result = await postcodes.validate('PO123AA')

Nearest

http://postcodes.io/docs#Nearest-Postcode

let result = await postcodes.nearest('PO123AA')

// with optional params
let result = await postcodes.nearest('PO123AA', {
    radius: 1000,
    limit: 5
})

Autocomplete

http://postcodes.io/docs#Postcode-Autocomplete

let result = await postcodes.autocomplete('PO123AA')

// with optional params
let result = await postcodes.autocomplete('PO123AA', {
    limit: 5
})

Query

http://postcodes.io/docs#Postcode-Query

let result = await postcodes.query('PO123AA')

// with optional params
let result = await postcodes.query('PO123AA', {
    limit: 5
})

Terminated

http://postcodes.io/docs#Terminated

let result = await postcodes.terminated('PO123AA')

Outcodes

http://postcodes.io/docs#Show-Outcode

// lookup
let result = await postcodes.outcodes('PO33')

// nearest
let result = await postcodes.outcodes('PO3', {
    limit: 10,
    radius: 10
})

// nearest (lat, lng)
let result = await postcodes.outcodes(51.7923246977375,  0.629834723775309)

// with optional params
let result = await postcodes.outcodes(51.7923246977375,  0.629834723775309, {
    limit: 10,
    radius: 10
})

Places

http://postcodes.io/docs#Place-Lookup

// lookup
let result = await postcodes.places('osgb4000000074553605')

// query
let result = await postcodes.places('Ryde', {
    limit: 10
})

// random
let result = await postcodes.places()

🔒 Testing

Can see test results @ https://travis-ci.org/lcherone/node-postcodes.io, if you want to run them locally, your need install mocha, then run:

$ npm test

©️ License

The MIT License (MIT). Please see License File for more information.