UK address lookup APIs are convenient but they come with a cost - literally. Most services charge per query. If you're processing high volumes or just want predictable costs, those fees add up fast.
If you already hold a Royal Mail PAF licence - or can get one - you have access to the full dataset of ~40 million UK delivery points. You just need something to serve it. That's what this project does. No magic, no nonsense.
What it is
paf-monorepo is a self-hosted UK postcode and address lookup API built on Royal Mail PAF data. It's a Node.js monorepo with two packages:
-
@paf/builder- processes your Royal Mail PAF CSV files into compact binary files -
@paf/api- a Fastify REST API that loads those binary files into memory and serves fast postcode lookups
There is no database. No Redis. No Postgres. Nothing to query at runtime except memory. Yes, really.
The zero-database approach
The interesting bit is trading RAM for speed. At startup, the builder output - a set of compact binary files - is loaded entirely into memory. Postcode lookups then use a binary search on sorted postcode keys. O(log m) if you care about that sort of thing.
The result is sub-millisecond lookup times with no query overhead, no connection pooling, no cache warming. The dataset is static between Royal Mail quarterly releases, so hitting a database on every request would just be adding moving parts for no reason.
The trade-off is RAM. The sample dataset runs at around 350MB. The full 40 million record PAF needs around 9GB, with 12GB recommended for headroom. For a long-running service on modern cloud infrastructure that's entirely manageable - and the cost is fixed regardless of query volume. Unlike those per-query bills.
Who it's for
This is a good fit if you:
- Already hold a Royal Mail PAF licence, or are evaluating whether to get one
- Need UK address lookup or postcode autocomplete in your own application
- Want to replace a commercial address lookup API in an e-commerce checkout, CRM, or logistics system
- Want to run UK address validation on your own infrastructure without a meter running
It is not a fit if you don't hold and can't obtain a Royal Mail PAF licence. The project serves PAF data - it doesn't include any. Royal Mail are quite clear on that point.
What the API does
Three endpoints cover the main use cases:
-
GET /lookup/address?postcode=SW1A2AA- returns all delivery points for a postcode -
GET /lookup/postcode?q=SW1A- postcode autocomplete for partial input -
GET /lookup/street?q=38+Flora&town=PLYMOUTH- optional street search by thoroughfare prefix and building number
Health, liveness, and readiness endpoints are included for container deployment. Because it's not the 90s and things need to stay up.
Getting started
MIT licensed, fully open source, includes a complete OpenAPI spec, Docker example, and operational runbooks. Royal Mail provide a free sample dataset so you can kick the tyres before committing to a full PAF licence.
Is it perfect? No. But it's a solid jumping off point if you want to implement a lower cost address lookup solution without starting from scratch. Take it, break it, improve it.
Top comments (0)