gridpin/gridpin

A country in a file — offline forward and reverse geocoding.
## Quick start
console
$ pip install gridpin gridpin-mcp
$ gridpin-fetch fr # France sheet, 365 MB, checked against the signed release; prints its path
python
import gridpin
from gridpinmcp import sheets
g = gridpin.Geocoder(str(sheets.download("fr"))) # no-op once the sheet is downloaded
g.geocode("1 rue de la Paix, Paris", 1)
No install: try it in Colab
— the Serbia sheet, forward, reverse and batch geocoding in five minutes.
Countries: us de fr it es nl br rs (gridpin-fetch --list). For AI agents there is an
MCP server — claude mcp add gridpin -- uvx gridpin-mcp, details in mcp/README.md.
Everything after the download runs offline.
If GridPin is useful to you, a star on GitHub helps other people find it.
GridPin is an offline geocoder: a country in a data file, memory-mapped and ready in milliseconds, with no server, no database import, and no network. It resolves addresses to coordinates (forward) and coordinates to the nearest indexed address (reverse — approximate: streets are indexed by centroid, so each result carries its distancem). On a single arm64 laptop core, measured on the France sheet: exact address lookups run at ~3,000/s, reverse geocoding at ~1,800/s, and typo-tolerant fuzzy matching much slower — tens of milliseconds per query, so batch it across cores when you feed it messy input. The engine and every query run fully offline — not a byte of what you geocode leaves your machine; the only network step is you downloading a sheet yourself, and a downloaded sheet carries no query data. Because you compute results locally from openly licensed data, you may store them forever, which hosted geocoding APIs typically forbid. If you have considered self-hosting Nominatim (a beefy server, days of import) or an on-prem geocoder license, the alternative here is: download one file, open it on any laptop.
## Install
CLI — prebuilt binaries for Linux x8664 (x8664-unknown-linux-gnu),
macOS Apple Silicon (aarch64-apple-darwin) and Windows x8664
(x8664-pc-windows-msvc) are attached to every
GitHub release; other targets
(Intel macOS, Linux arm64/musl, Windows arm) build from source:
console
$ base=https://github.com/gridpin/gridpin/releases/download/v0.5.0
$ curl -fsSLO "$base/gridpin-aarch64-apple-darwin.tar.gz"
$ curl -fsSLO "$base/gridpin-release-signers"
$ curl -fsSLO https://dl.gridpin.dev/v0.5.0/attestation.json
$ curl -fsSLO https://dl.gridpin.dev/v0.5.0/attestation.json.sig
# the trust root comes from the OTHER channel — see "Verifying a release" for why
$ ssh-keygen -Y verify -f gridpin-release-signers -I gridpin-release \
-n gridpin-g02 -s attestation.json.sig .zip from the releases page: it is built for DuckDB 1.5.5 only. It is a loadable
extension, so authenticate it before you load it — same three lines as the CLI archive above,
with gridpinext- .zip as the asset name:
console
$ ssh-keygen -Y verify -f gridpin-release-signers -I gridpin-release \
-n gridpin-g02 -s attestation.json.sig coordinates, top 3 candidates
$ gridpin query france.bin "1 rue de la Paix Paris" -k 3
# reverse: coordinates -> nearest indexed address (approximate; each hit carries distancem)