twindual/postcodes.io

UK Postcode API serving up Open Data

Postcodes.io

Query for UK postcodes and geolocations over HTTP. Postcodes.io uses the Office for National Statistics Postcode Directory.

Documentation can be found at postcodes.io

Requirements

Please make sure you have the following available:

• Node.js v6.x (Instructions)
• Postgres (9.5 or greater)
• PostGIS extension (Instructions)

We also have an end-to-end guide to install Postcodes.io on a fresh virtual machine in the wiki.

Install & Download Data & Run

Download and install

$ git clone https://github.com/ideal-postcodes/postcodes.io.git

$ cd postcodes.io/ && npm install

Configure Postgres and Seed Database

Postcodes.io is packaged with a script to setup and download the ONS Postcode Directory. To run this, navigate into the repository directory and run:

$ npm run setup

This script will prompt you for Postgres superuser credentials. This privilege is required to create a new user, database, extensions and then to load the data. For the security conscious, you can find out how this works by reading our installation notes and the script itself. Other install methods are available but require a bit of extra work.

You can change the Postgres username/password yourself but you will need to update 'config/config.js' with the relevant credentials.

The import process takes around 10 minutes to complete.

Run it

node server.js // Default environment is development

Docker

This repository builds both the application and database services as docker containers.

Application

The Postcodes.io application is packaged as a Docker container identified on the Docker Hub as idealpostcodes/postcodes.io.

Example usage:

docker run -d -p 8000 idealpostcodes/postcodes.io

Configuration available via Environment Variables:

• POSTGRES_USER
• POSTGRES_PASSWORD
• POSTGRES_DATABASE
• POSTGRES_HOST
• POSTGRES_PORT
• PORT (HTTP Port to run on)
• MAPBOX_PUBLIC_KEY

Database

idealpostcodes/postcodes.io.db points to a PostgreSQL & PostGIS base image and preloads the latest pg_dump in the build process. Upon starting a container for the first time, PostGIS will be enabled and the pg_dump will take around a minute to restore.

Example usage:

docker run -p 5432 -e POSTGRES_USER=postcodesio -e POSTGRES_DB=postcodesiodb -e POSTGRES_PASSWORD=password idealpostcodes/postcodes.io.db

As this contains the official postgres base image, the available configuration environment variables are documented here: https://hub.docker.com/_/postgres/

Testing

$ npm run setup_test_db # create test database

$ npm test

External Libraries

1. Java Library by Deepak Sunanda Prabhakar

2. PHP Libraries

   • postcodes-io-bundle by the people at Box UK. Read the Blog post
     
   • postcodes-io laravel package by Aditya Menon
     
   • Postcodes Laravel 5+ package by Codescheme
     
   • PHP Class for Postcodes.io by Ryan
     

3. Ruby Library by James Ruston

4. Node.JS Library by billinghamj

5. Python Library by Gokhan Karadas

6. C# Library by Mark Embling

7. R Library by Eryk Walczak. Read the blog post.

8. Hack Library HackPostcodes by Matt Barber

9. Wolfram Language Library Postcode by Arnoud Buzing

10. Google Sheets Addon by Ed Patrick

License

MIT