---
title: "Deploy Postcodes.io"
description: "Self hosted postcodes.io using the official Docker containers"
category: "Other"
url: https://railway.com/deploy/postcodesio
---

# Deploy Postcodes.io

Self hosted postcodes.io using the official Docker containers

**[Deploy Postcodes.io on Railway](https://railway.com/template/postcodesio)**

- **Creator:** djf1982's Projects
- **Category:** Other
- **Total deploys:** 2

## Template content

### postcodes-db https://postcodes.io/img/house.png

- **Image:** idealpostcodes/postcodes.io.db:latest

### postcodes-api https://postcodes.io/img/house.png

- **Image:** idealpostcodes/postcodes.io:latest
- **Health check:** /ping
- **Public domain:** Yes

## Documentation

# Deploy and Host Postcodes.io on Railway

Postcodes.io is a free, open-source HTTP API for UK postcode and geolocation lookups, maintained by Ideal Postcodes. It returns latitude, longitude, electoral wards, parliamentary constituencies, NHS regions, census areas, and dozens of other fields for every UK postcode, drawing from the ONS Postcode Directory (ONSPD) dataset.

## About Hosting Postcodes.io

This template deploys two services: a PostgreSQL + PostGIS database preloaded with the full ONSPD dataset, and the Node.js HTTP API that queries it. The database image restores its preloaded dump on first boot — expect 60–90 seconds before the API starts returning real data. The dataset is persisted on a Railway volume so subsequent deploys skip the restore. The API service is exposed on a public domain; the database stays on Railway's private network. ONSPD is updated quarterly by the ONS, and the upstream Docker image is rebuilt whenever a new release lands.

## Common Use Cases

- Postcode autocomplete and validation in web forms or checkout flows
- Reverse geocoding — turning latitude/longitude pairs back into nearby postcodes
- Enriching customer records with administrative geographies (council ward, parliamentary constituency, NHS region) for analytics or segmentation

## Dependencies for Postcodes.io Hosting

- PostgreSQL with the PostGIS extension (bundled into the database image)
- A persistent Railway volume to hold the loaded postcode dataset (~600 MB)

### Deployment Dependencies

- [Postcodes.io documentation](https://postcodes.io/docs)
- [Postcodes.io self-hosting guide](https://postcodes.io/docs/self-host)
- [Postcodes.io GitHub repository](https://github.com/ideal-postcodes/postcodes.io)
- [Database image on Docker Hub](https://hub.docker.com/r/idealpostcodes/postcodes.io.db)
- [API image on Docker Hub](https://hub.docker.com/r/idealpostcodes/postcodes.io)

### Implementation Details

Once deployed, query the API at your public Railway domain:

\`\`\`bash
# Lookup a single postcode
curl https://your-app.up.railway.app/postcodes/SW1A1AA

# Bulk lookup
curl -X POST https://your-app.up.railway.app/postcodes \
  -H "Content-Type: application/json" \
  -d '{"postcodes":["SW1A1AA","M11AE","EH11YZ"]}'

# Reverse geocode by coordinates
curl "https://your-app.up.railway.app/postcodes?lon=-0.127758&lat=51.507351"
\`\`\`

A browser UI for ad-hoc lookups is served at the root of the public domain.

## Why Deploy Postcodes.io on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Postcodes.io on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

## Similar templates

- [Rocky Linux](https://railway.com/deploy/rocky-linux) — Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀
- [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — A Self-Hosted & Modern Roleplaying Platform
- [Letta Code Remote](https://railway.com/deploy/letta-code-remote) — Run a Letta Code agent 24/7. No inbound ports, just deploy.

Open this page in a browser: https://railway.com/deploy/postcodesio