UK postcode & geolocation API, serving up open data

Query for UK postcodes and geolocations over HTTP.

Postcodes.io serves the ONS Postcode Directory, Ordnance Survey Open Names and Scottish Postcode Directory datasets. The API runs against a pre-built PostgreSQL/PostGIS database that is published as a pg_dump from an upstream pipeline — this repository contains the HTTP service only.

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

Testing

# Run the entire test suite end-to-end (build images, seed DB, run mocha):
make test

# Interactive test container:
make test-up
make test-shell
$api-container> ./bin/load_test_seed   # rebuild the seeded DB
$api-container> npm test               # mocha against the seeded DB

# Run a command in the running test container:
make test-exec npm test

License

MIT