postcode-geo-uk

Deterministic UK postcode validation + attribution for lead-list address hygiene. Pure local computation from a bundled static file: no live APIs, no scraping, no keys, no network calls at runtime. Same input → same output, byte for byte.

What it does

Input: an array of UK postcode strings (any casing/spacing). Output per postcode, in input order:

• status — ok (valid format and present in the bundled ONS snapshot), invalid (does not match the Royal Mail postcode format), or unknown (valid format but not found in the bundled snapshot — reported honestly, never guessed).
• canonical — corrected format: uppercase, single space before the 3-character inward code (e.g. sw1a1aa → SW1A 1AA).
• country, local_authority, region — from the bundled ONS data.
• latitude / longitude — postcode centroid from the bundled ONS data.
• duplicate_of — set when the same canonical postcode appeared earlier in the batch (dedupe rollup for hygiene use).

What it does NOT do

• Does NOT do address matching, UPRN lookup, or street-level data.
• Does NOT validate that a postcode corresponds to any specific business or person.
• Does NOT fetch anything at runtime — unknown means "not in this snapshot", not "does not exist" (terminated, very new, or non-GB postcodes can be unknown).
• Does NOT cover Crown Dependencies (Guernsey/Jersey/Isle of Man) — they report unknown.
• Northern Ireland postcodes are absent from the bundled snapshot and report unknown (see data note below).

Quickstart

$cd /home/hermes/venture/postcode-geo-uk && node main.js --fixtures

Expected: 36/36 passed, exit 0, and dataset items: 36 emitted.

Process your own list:

$node main.js input.json   # input.json: { "postcodes": ["SW1A 1AA", ...] }

Data & licence

Bundle: data/postcodes.csv.gz (1,797,567 live UK postcodes; country, centroid, local authority, region) + data/names.json (dictionary for LA/region names).

Source: ONS National Statistics Postcode Lookup (UK) via data.gov.uk, OGL v3.0 snapshot (accessed 12 Sep 2026). The GOV.UK PDUK sample page linked in the build brief now 404s; the ONS NSPL on data.gov.uk is the current free OGL v3 route for the same postcode→geography data, so this build uses it instead. No Ordnance Survey premium (ODbL/paid) data is used.

Licensing notes: the underlying postcode list carries Royal Mail and Ordnance Survey Intellectual Property Rights in the source publication; the publication itself is released under OGL v3.0. This bundle redistributes only the OGL-published derivation (postcode → geography), not Royal Mail address records.

Contains public sector information licensed under the Open Government Licence v3.

Layout

• main.js — CLI entry (--fixtures, --selftest, or <input.json>)
• engine.js — grammar + lookup + batch/dedupe
• bundle.js — loads the gzipped bundle once per process
• input_schema.json / output_schema.json — Apify-style schemas (lowercase property names)
• fixtures/cases.json — 36 hand-checked cases: valid, badly-formatted/invalid, valid-format-but-unknown

Limits

• Snapshot staleness: bundled data is a point-in-time copy; newly issued postcodes will report unknown.
• Centroids are ONS best-fit; not survey-grade.