@stevegoossens/postcodes.io

Client for the postcodes.io API from ideal-postcodes/postcodes.io GitHub repo.

Features:

• supports the full REST API by a matching OpenAPI specification
  • REST API documentation rendered by ReDoc
  • typed schemas for request and response
  • example requests and responses
  • includes undocumented properties
• package with types - supports use in TypeScript or JavaScript
• class method names match documented API Methods

Table of Contents

• View REST API docs
• Install from NPM repo
• Usage
  • Instantiate class
    • Alternate: instantiate class to use different API server
  • Postcodes
    • Bulk Postcode Lookup
    • Bulk Reverse Geocoding
    • Nearest Postcode
    • Postcode Autocomplete
    • Postcode Lookup
    • Postcode Query
    • Postcode Validation
    • Random Postcode
    • Reverse Geocoding
    • Reverse Geocoding (Legacy)
    • Scottish Postcode Lookup
    • Terminated Postcode Lookup
  • Outcodes
    • Nearest Outcode
    • Outcode Reverse Geocoding
  • Places
    • Place Query
    • Place Lookup
    • Random Place
• Development
  • Install
  • View api.postcodes.io REST API docs
  • Validate OpenAPI
  • Generate code from OpenAPI
  • Test generated and source code
  • Build

View REST API docs

It is a good idea to view the REST API documentation to understand the structure and property types. The result property from the API response body is what is returned by the client methods.

You can view the REST API docs online at:

https://stevegoossens.github.io/docs/postcodes.io/

Alternatively, you can view them locally:

yarn docs

This will output a local URL that you can open in a browser to view the documentation.

The original REST API documentation is at https://api.postcodes.io/docs, but as at the time of writing it is slightly incomplete (a few properties are unmentioned or misnamed) and is harder to read than the ReDoc layout.

Install from NPM repo

yarn add @stevegoossens/postcodes.io

Usage

The package has one default export, the class PostcodesIO. You can instantiate it without parameters to use the default settings (e.g. use the normal https://api.postcodes.io server)

Instantiate class

import PostcodesIO from '@stevegoossens/postcodes.io'
const postcodesIO = new PostcodesIO()

const PostcodesIO = require('@stevegoossens/postcodes.io')
const postcodesIO = new PostcodesIO()

Alternate: instantiate class to use different API server

const postcodesIO = new PostcodesIO({
  basePath: 'http://localhost:8000'
})

Postcodes

Bulk Postcode Lookup

const postcodes = ['BD6 3PS', 'NE32 5YQ']
const postcodeDataList =
    await postcodesIO.bulkPostcodeLookup(postcodes)

Bulk Reverse Geocoding

const geolocations = [
  {
    longitude: 0.629834723775309,
    latitude: 51.7923246977375,
  },
  {
    longitude: -2.49690382054704,
    latitude: 53.5351312861402,
    radius: 1000,
    limit: 5,
  },
]
const postcodeDataReverseGeocodingResultList =
    await postcodesIO.bulkReverseGeocoding(geolocations)

Nearest Postcode

const postcode = 'BH21 7AT'
const postcodeDataReverseGeocodingList =
    await postcodesIO.nearestPostcode(postcode)

Postcode Autocomplete

const postcode = 'TA11 7Y'
const postcodes =
    await postcodesIO.postcodeAutocomplete(postcode)

Postcode Lookup

const postcode = 'AB15 6DH'
const postcodeData =
    await postcodesIO.postcodeLookup(postcode)

Postcode Query

const query = 'KT3'
const postcodeDataList =
    await postcodesIO.postcodeQuery(query)

Postcode Validation

const postcode = 'CW6 0EF'
const postcodeIsValid =
    await postcodesIO.postcodeValidation(postcode)

Random Postcode

const postcodeData =
    await postcodesIO.randomPostcode()

Reverse Geocoding

const lon = -1.492787
const lat = 54.961017
const postcodeDataList =
    await postcodesIO.reverseGeocoding(
      lon,
      lat
    )

Reverse Geocoding (Legacy)

const longitude = -3.924229
const latitude = 51.923369
const postcodeDataList =
    await postcodesIO.reverseGeocodingLegacy(
      longitude,
      latitude
    )

Scottish Postcode Lookup

const postcode = 'EH22 3NX'
const scottishPostcodeData =
    await postcodesIO.scottishPostcodeLookup(postcode)

Terminated Postcode Lookup

const postcode = 'E1W 1UU'
const terminatedPostcodeData =
    await postcodesIO.terminatedPostcodeLookup(postcode)

Outcodes

Nearest Outcode

const outcode = 'W1A'
const outcodeDataList =
    await postcodesIO.nearestOutcode(outcode)

Outward Code Lookup

const outcode = 'B1'
const outcodeData =
    await postcodesIO.outwardCodeLookup(outcode)

Outcode Reverse Geocoding

const lon = -2.302836
const lat = 53.455654
const outcodeDataList =
    await postcodesIO.outcodeReverseGeocoding(lon, lat)

Places

Place Query

const query = 'adl'
const placesDataList =
    await postcodesIO.placeQuery(query)

Place Lookup

const code = 'osgb4000000074564391'
const placesData =
    await postcodesIO.placeLookup(code)

Random Place

const placesData =
    await postcodesIO.randomPlace()

Development

To develop this package, clone/fork this repo.

Install

Download all NPM dependencies

yarn

View api.postcodes.io REST API docs

You can view a complete documentation of the api.postcodes.io REST API, rendered with ReDoc, locally in a browser. This is useful if you need to update the openapi.yaml file, as the documentation should automatically reload in the browser (or you can refresh the browser page to load the updated OpenAPI spec file).

yarn docs

Validate OpenAPI

The syntax and example data can be validated with OpenAPI linting.

yarn openapi:lint

Generate code from OpenAPI

Generate TypeScript code from OpenAPI spec (of api.postcodes.io)

yarn generate

Test generated and source code

This will run unit tests and test the code against linting rules via posttest script.

yarn test

Build

Transpile to dist/

yarn build