A browser-based geocoder powered by DuckDB-WASM and Overture Maps address data. No backend required, all 469M+ addresses are queried directly from Parquet files via HTTP range requests.
- Forward Geocoding - search by street, postcode, or address across 39 countries
- Reverse Geocoding - find nearest addresses by clicking the map or entering coordinates
- Country-aware parsing - dedicated address parsers for NL, US, DE, FR, IT, ES, BR, AU, CA, JP with format-specific logic. The JP parser handles native no-space input and kanji/Arabic chome interchangeability
- libpostal street-type synonyms - 27 languages of canonicalizations (e.g.
avenue ↔ ave,strasse ↔ str,via ↔ v) are expanded at query time so "195 clearview avenue" matches stored "195 clearview ave" - Apartment-aware - Overture multi-unit buildings render per-unit rows with a "Unit X" badge, markers grouped by lat/lon so dense buildings stay readable
- Three-tier caching - WASM init, country prefetch, tile LRU for sub-second queries
- Overture release selector - switch between available Overture Maps releases from the navbar
- Interactive map - MapLibre GL with H3 tile overlays and result markers
- Light and dark mode - follows system preference with manual toggle
This is a pnpm monorepo with two packages:
packages/core/ @walkthru-earth/geocoding-core Pure TS library (framework-agnostic)
apps/playground/ playground Svelte 5 UI consuming the core library
@walkthru-earth/geocoding-core contains all geocoding logic: DuckDB-WASM wrapper, address parsing, search algorithms, caching, and type definitions. It can be used with any framework (React, Vue, Next.js, etc.).
playground is the Svelte 5 UI that demonstrates the core library with an interactive map, split-pane layout, and data visualizations.
| Layer | Technology |
|---|---|
| Core library | TypeScript (ESM, framework-agnostic) |
| UI framework | Svelte 5 |
| Build | Vite 8 (Rolldown) |
| Database | DuckDB-WASM (in-browser) |
| Styling | Tailwind CSS 4 + DaisyUI 5 |
| Map | MapLibre GL |
| Geo indexing | H3 (Uber) |
| Data | Overture Maps addresses (Parquet on S3) |
pnpm install
pnpm devOpen http://localhost:5173/geocoding-playground/.
pnpm build # builds core library, then playground
pnpm preview # preview production build- WASM Init (~2-4s) - loads DuckDB + extensions (httpfs, spatial, h3), caches global tile index and manifest
- Country Prefetch (~3-8s) - when a country is selected, loads city/postcode/street indexes into in-memory tables
- Query - parses input using country-specific parser, narrows to relevant H3 tiles, queries Parquet files with filter pushdown
- Tile Cache - fetched tiles are kept in-memory (LRU, 4M address budget) for instant repeat queries
Address data is sourced from Overture Maps and served as optimized Parquet files via Source Cooperative. The release version is selectable from the navbar.
This project is licensed under CC-BY 4.0. Walkthru.Earth.
Overture Maps address data is available under CDLA-Permissive 2.0 or ODbL 1.0 where derived from OpenStreetMap. See Overture Maps Attribution for country-specific requirements.