Postcodes.io

<h1 align="center"> <img src="https://img.ideal-postcodes.co.uk/Postcodes.io%20Logo@3x.png" alt="Postcodes.io"> </h1>

UK postcode & geolocation API, serving up open data

Query for UK postcodes and geolocations over HTTP.

Postcodes.io regularly ingests and serves the ONS Postcode Directory and Ordnance Survey Open Names datasets.

Features

• Postcode lookup, resolve administrative and location data for postcodes and outward codes
• Postcode search & autocomplete
• Reverse geocode postcodes
• Nearest postcode search
• Terminated postcode search
• Outward code lookup
• Bulk postcode lookup and reverse geocoding

Usage

• Public API
• API Documentation
• 3rd Party API Clients
• Public API Service Status
• Self Hosting: Docker containers
  • Docker Hub Container Image: Postcodes.io Application
  • Docker Hub Container Image: Postcodes.io Database

Quick Start

Start querying UK postcode data immediately on your local machine with Docker

docker-compose up

<p align="center"> <img src="https://img.ideal-postcodes.co.uk/postcodesio-docker-compose-demo.gif" alt="Docker Compose Demo"> </p>

Testing

# Run entire test suite
make test

# Launch test application container and services, and run tests from container
make test-up
make test-shell
$api-container> npm test

# Fast iteration: create DB once, then run tests without rebuilding
npm run test:create   # Run once
npm run mocha         # Reuse existing DB (sets NO_RELOAD_DB=true)

# Execute command in test container
make test-exec npm run mocha

License

MIT