Documentation

Get started in 5 minutes

GridPin is an offline geocoder: a country in a memory-mapped file (most are a single file; some regions add a small companion, POI is separate), forward and reverse lookups in milliseconds. Throughput is entirely query-shape dependent — exact lookups run at ~3,000/s per core and reverse at ~1,800/s, while typo-tolerant fuzzy matching is much slower (tens of ms per query); see the benchmarks. No server, no database import; once the files are on disk, no query leaves your machine.

Install

CLI. Prebuilt self-contained binaries for Linux x86_64 (x86_64-unknown-linux-gnu), macOS Apple Silicon (aarch64-apple-darwin) and Windows x86_64 (x86_64-pc-windows-msvc) are attached to every GitHub release; any other target (Intel macOS, Linux arm64/musl, Windows arm) builds from source:

# macOS (Apple silicon) example; pick your platform archive
$ base=https://github.com/gridpin/gridpin/releases/download/v0.1.0
$ curl -fsSLO "$base/gridpin-aarch64-apple-darwin.tar.gz"
$ curl -fsSLO "$base/gridpin-release-signers"
$ curl -fsSLO https://dl.gridpin.dev/v0.1.0/attestation.json
$ curl -fsSLO https://dl.gridpin.dev/v0.1.0/attestation.json.sig
# unpacking runs its contents sooner or later — authenticate first. The trust root comes
# from the OTHER channel: whoever owns one can swap the archive AND its checksum line.
$ ssh-keygen -Y verify -f gridpin-release-signers -I gridpin-release \
    -n gridpin-g02 -s attestation.json.sig < attestation.json \
    || { echo "signature does not verify — STOP"; exit 1; }
# extract the EXPECTED hash from the attestation you just authenticated, then COMPARE.
# Printing a hash is not a check: something has to fail when it differs.
$ want=$(python3 -c 'import json;print([a["sha256"] for a in json.load(open("attestation.json"))["assets"] if a["name"]=="gridpin-aarch64-apple-darwin.tar.gz"][0])')
$ test "$want" = "$(shasum -a 256 gridpin-aarch64-apple-darwin.tar.gz | cut -d' ' -f1)" \
    || { echo "archive does not match the signed attestation — STOP"; exit 1; }
$ tar xzf gridpin-aarch64-apple-darwin.tar.gz && sudo mv gridpin /usr/local/bin/
$ gridpin --help

# or build from source (stable Rust)
$ cargo build --release --manifest-path gridpin/Cargo.toml

Python. pip install gridpin

DuckDB. Two ways to get gridpin_ext:

-- 1. once the extension is accepted into the community catalog — DuckDB's own
-- catalog signs and verifies it there; that trust root is DuckDB's, not ours:
INSTALL gridpin_ext FROM community;
LOAD gridpin_ext;

# 2. until then: download gridpin_ext-<platform>.zip from the releases page.
# It is loadable code, so authenticate it BEFORE loading — see "Verifying a release"
# in the README; the trust root comes from the other channel, never from the download.
$ ssh-keygen -Y verify -f gridpin-release-signers -I gridpin-release \
    -n gridpin-g02 -s attestation.json.sig < attestation.json \
    || { echo "signature does not verify — STOP"; exit 1; }
$ want=$(python3 -c 'import json;print([a["sha256"] for a in json.load(open("attestation.json"))["assets"] if a["name"]=="gridpin_ext-osx_arm64.zip"][0])')
$ test "$want" = "$(shasum -a 256 gridpin_ext-osx_arm64.zip | cut -d' ' -f1)" \
    || { echo "extension does not match the signed attestation — STOP"; exit 1; }
# The file inside is named gridpin_ext.duckdb_extension — keep that name: DuckDB derives
# the entry symbol from the file's basename, so it must load as gridpin_ext.
$ unzip gridpin_ext-osx_arm64.zip
$ duckdb -unsigned

LOAD '/path/to/gridpin_ext.duckdb_extension';

Forward geocoding

Address in, ranked candidates out. -k sets how many candidates you want.

$ gridpin query france.bin "1 rue de la Paix Paris" -k 3

Reverse geocoding

Coordinates in, nearest known address out — with a precision flag and its distance, so an approximate hit is never dressed up as exact.

$ gridpin reverse france.bin 48.8686 2.3305

Batch mode

JSON Lines in ({"q": "1 rue de la Paix Paris"} per line), JSON Lines out ({"results": […candidates…]} per line, order preserved). This is the fastest path for large jobs.

$ gridpin batch france.bin in.jsonl out.jsonl -k 1

Python

The same engine as a wheel. Exact lookups run at ~3,000/s per core from Python; use geocode_many(), the CLI batch mode, or DuckDB to spread messy input across cores.

$ pip install gridpin

import gridpin

g = gridpin.Geocoder("france.bin")   # mmap, opens instantly

# forward: query, k candidates
hits = g.geocode("1 rue de la Paix Paris", 1)

# reverse: lat, lon, k candidates
addr = g.reverse(48.8686, 2.3305, 1)

# exact lookups ~3,000/s per core

Results are plain objects with the same fields as the JSON response format below.

DuckDB extension

Geocode whole tables without leaving SQL. Load the extension, point it at a sheet, and call scalar functions in your queries.

LOAD gridpin_ext;
SELECT gridpin_load('france.bin');

-- forward: one JSON result per row
SELECT gridpin_geocode(address) FROM orders;

-- reverse: nearest address per coordinate pair
SELECT gridpin_reverse(lat, lon) FROM pings;

Both functions return the standard JSON response as a string; unpack fields with DuckDB's json_extract or the ->> operator.

Switching sheets. One index per session. Loading the same sheet again is a no-op; loading a different sheet is a hard error — it never silently replaces the loaded index. Switch explicitly with gridpin_reset(), which must be its own statement, then load the new sheet:

SELECT gridpin_load('france.bin');  -- index loaded
SELECT gridpin_load('italy.bin');   -- ERROR: 'italy.bin' while 'france.bin' is loaded; run gridpin_reset()
SELECT gridpin_reset();             -- index unloaded
SELECT gridpin_load('italy.bin');   -- index loaded

Response format

Every interface — CLI, Python, DuckDB — returns the same result shape. One object per candidate, best match first.

{
  "lat": 48.8686,
  "lon": 2.3305,
  "precision": "house",
  "score": 412.0,          // illustrative values
  "confidence": 0.84,
  "street": "Rue de la Paix",
  "housenumber": "5",
  "commune": "Paris 2e Arrondissement",
  "postcode": "75002",
  "flags": ["street_exact", "commune_prefix", "house_rep"]
}

Empty results: the CLI prints nothing (exit 0), Python returns an empty list, DuckDB's gridpin_geocode/gridpin_reverse return the string '{}'.

POI layer

Addresses are the core index. Places — "pharmacie gare de Lyon" — live in an opt-in, separate file, currently for France: 231 MB of Overture places.

How the cascade works

The POI layer never sits inside the address index — it is a second file, and the engine runs the cascade for you when you pass it:

# CLI
$ gridpin query france.bin "pharmacie gare de Lyon" --poi fr_poi.bin -k 1

# Python
g = gridpin.Geocoder("france.bin", poi="fr_poi.bin")

-- DuckDB
SELECT gridpin_load_poi('fr_poi.bin');  -- after gridpin_load(...)

Cascade rules (built in): 1) the address index answers first; 2) the POI file is consulted only when the address result is empty, city-level or low-confidence; 3) an exact address match is never overridden. POI answers carry a "poi_layer" flag. Without --poi the engine behaves exactly as before — the layer is strictly opt-in.

Honest numbers. On a name-plus-city POI pilot with Wikidata coordinates as truth (France), GridPin with the POI layer resolves 49% of queries within 500 m (62% within 2 km). Photon resolves 71% within 500 m on the same set — it is stronger on POIs today. The layer is young and opt-in: address lookup is the core product, POI is an adjacent capability we are still building out.

Building sheets yourself

The prep/ pipeline that produces sheets is public: plain DuckDB SQL from raw source data to the finished file. You can build a working sheet for any supported country end-to-end. Official sheets differ in one part: the curated per-country rules section is private, so a self-built sheet runs on the engine's built-in defaults.

Try it on Monaco

Monaco is the smallest end-to-end example: it builds a sheet from a raw OSM extract. The same target runs in CI as a public smoke test with 23 live-query checks.

$ make mc      # build the Monaco sheet from an OSM extract
$ make smoke   # build Monaco + run the 23 live-query checks CI runs

Full countries

The same pipeline builds any country in the atlas, but plan for it: a full-country build takes hours and tens of gigabytes of temporary disk for the source data and intermediate tables. That is exactly the work the subscription buys you out of — fresh, tested sheets arrive monthly; the free tier is static, with no update schedule.

Getting the files

Everything published today is free and needs no key, no account and no sign-up. Data files are served as individual objects — there is no directory listing, so each link points straight at a file: france.bin, italy.bin, netherlands.bin, serbia.bin, fr_poi.bin. The engine binaries, the checksums and the signed provenance attestation are on the GitHub releases page.

Every sheet carries its provenance inside the file: gridpin meta france.bin prints the source, its license, the source release and the attribution you need when you redistribute. The release additionally ships verify_release.py, which checks the owner’s signature over the whole set — see Verifying a release.

A published sheet is a static build: it does not change under you, and no refresh schedule is promised. Automated delivery of regularly rebuilt sheets is planned for paid plans, which are not open yet.

Frequently asked questions