A production-grade engineering reference for building reliable, high-throughput address parsing and geocoding pipelines.
🌐 Live site: www.address-normalization.com
Address data almost never arrives clean. It shows up as OCR output, legacy CSV dumps, web-form submissions, and scraped text — misspelled, inconsistently abbreviated, in mixed scripts, and full of edge cases. Turning that noise into clean, geocoded, deduplicated records at scale is a real engineering discipline, and most of the knowledge is scattered across vendor docs, blog posts, and hard-won production experience.
This site collects that discipline in one place. Every guide is written for practitioners who ship real pipelines — data engineers, GIS analysts, logistics and platform developers, and Python automation builders — with runnable code, explicit edge-case handling, and honest trade-off analysis. No pseudocode, no hand-waving, no theory-only overviews.
Four in-depth topic areas, 50+ guides, and 130k+ words of practitioner-focused reference material:
Decompose raw strings into structured components and normalize them to postal standards. Regex parsing engines, Unicode NFKC normalization, USPS CASS compliance, libpostal integration, and edge cases from PO Boxes and rural routes to international and European address formats.
Architect resilient geocoding that survives provider outages, quota exhaustion, and regional coverage gaps. Async Python clients, circuit-breaker fallback chains, Redis-backed quota tracking, token-bucket rate limiting, and intelligent provider selection benchmarked across Google Maps, HERE, Mapbox, and OpenStreetMap.
Keep high-throughput pipelines fast and clean. Two-tier Redis and Postgres result caches, PostGIS spatial index design (GiST vs BRIN), geohash proximity search, and collapsing duplicate addresses onto a single fuzzy canonical key.
Close the quality loop. Confidence scoring, haversine outlier detection, ground-truth regression corpora, and continuous-integration gates that block a deploy the moment match rates regress — plus scheduled incremental refresh to keep enriched data in sync.
- Code-first — every guide ships runnable Python 3.8+ with type hints, module-level compiled regex, explicit error handling, and vectorized pandas variants.
- Production-minded — circuit breakers, backoff with jitter, dead-letter queues, and idempotency keys are built in from the start, not bolted on.
- Globally applicable — patterns for US, European, Latin American, and Asia-Pacific address formats and scripts.
- Hand-authored diagrams — original inline SVG architecture and data-flow diagrams that adapt to light and dark themes.
- Accessible & fast — WCAG 2 AA, responsive, installable PWA with offline support, and a Lighthouse-tuned performance budget.
- Eleventy (11ty) static site generator with Nunjucks templates and
markdown-it. - Vanilla CSS & JavaScript — no framework, no client-side runtime bloat. Progressive enhancement for copy-to-clipboard, accordions, toggleable checklists, and mobile nav.
- Progressive Web App — Web App Manifest, service worker with a network-first HTML / cache-first asset strategy, and Apple touch metadata.
- Cloudflare Workers static assets for global edge delivery.
# Requirements: Node.js 18+
npm install
# Serve locally with live reload at http://localhost:8080
npm run serve
# Production build to ./_site
npm run build
# Build and deploy to Cloudflare Workers
npm run deploycontent/ Markdown source for every page (one folder per URL)
_includes/ Nunjucks layouts and partials (header, footer, breadcrumbs)
_data/ Global data (asset cache-busting hash)
public/ Static assets — CSS, JS, icons, manifest, service worker
.eleventy.js Eleventy configuration (markdown, collections, filters)
wrangler.jsonc Cloudflare Workers deployment config
Spotted an error, an outdated API detail, or a pattern that breaks on an edge case you've hit in production? Open an issue or a pull request — corrections and battle-tested improvements are welcome.
Built and maintained by address-normalization. If these guides save you time, a ⭐ on the repo helps others find them.