# GridPin

> Offline forward and reverse geocoder: one memory-mapped file ("sheet") per country, a Rust engine with a Python package, a CLI, a DuckDB extension and an MCP server for AI agents. Built from Overture Maps open data, Apache-2.0. No server, no API key, no rate limit; geocoding queries never leave the machine.

Countries: United States (us), Canada (ca), Germany (de, without Bavaria), France (fr), Italy (it), Spain (es), Australia (au), Mexico (mx), Netherlands (nl), Brazil (br), Serbia (rs).

Fastest path:

- Python: `pip install gridpin gridpin-mcp`, then `gridpin-fetch fr` downloads the France sheet and verifies it against the signed release; `gridpin.Geocoder(path).geocode("1 rue de la Paix, Paris", 1)`.
- AI agents (MCP): `uvx gridpin-mcp`; tools `list_countries`, `download_sheet`, `geocode`, `reverse`, `batch`, `extract_addresses`.
- DuckDB 1.5.6+ (older DuckDB versions install an older build): `INSTALL gridpin_ext FROM community; LOAD gridpin_ext; SELECT gridpin_load('france.bin'); SELECT gridpin_geocode(address) FROM t;`
- Live demo, nothing to install: https://gridpin.streamlit.app (runs on Streamlit's server; installed locally, queries never leave the machine).
- CLI: `gridpin query france.bin "1 rue de la Paix Paris" -k 3`, `gridpin reverse france.bin 48.8686 2.3305`, `gridpin batch france.bin in.jsonl out.jsonl` (a `.csv` or `.tsv` comes back with `gp_*` columns), `gridpin same usa.bin "<a>" "<b>"` (are two strings the same address?).
- Local server: `gridpin serve usa.bin` answers `/v1/geocode` and Nominatim-compatible `/search`, `/reverse`, `/status` on 127.0.0.1:8080.
- The sheet as a table (0.9.0+): `gridpin list` (a street, a postcode, a circle, a box, a polygon), `gridpin export`, `gridpin sample --n 1000 --seed 7`, `gridpin stats`; CSV, JSONL, GeoJSON, GPX, the sheet's licence first. Your own files: `gridpin nearest`, `gridpin join`, `--aliases`; `batch --columns` for addresses already split into fields; the server also answers `/maps/api/geocode/json` in Google's format.
- pandas: `pip install "gridpin[pandas]"`, `gridpin.sheets.fetch("us")`, `gridpin.geocode_df(...)` (adds the same `gp_*` columns as the CSV path).

Every result carries `precision` (house, interp, street, city, ...), `confidence` and `weak` (true when the answer needs a check before use: city level, low confidence or a fuzzy street); reverse results carry `distance_m` and are approximate. One sheet holds one country: pick the sheet by the address's country.

## Docs

- [README](https://raw.githubusercontent.com/gridpin/gridpin/main/README.md): install, quick start, CLI, Python, DuckDB, verifying a release, licensing
- [MCP server and sheet downloads](https://raw.githubusercontent.com/gridpin/gridpin/main/mcp/README.md): agent setup, tools, `gridpin-fetch`
- [Documentation page](https://gridpin.dev/docs): grouped by task — geocoding, the answer, your data, running a server, integrations, publishing, data and plans
- [Command reference](https://gridpin.dev/cli): every gridpin command with its arguments and flags, from the program's own help
- [Benchmark](https://raw.githubusercontent.com/gridpin/gridpin/main/docs-public/BENCHMARK.md): how quality is measured against Nominatim and Photon, with the numbers

## Guides

- [All guides and countries](https://gridpin.dev/guides): index of the pages below
- [Offline geocoding in Python](https://gridpin.dev/offline-geocoding-python): Address to coordinates and back, from a local file per country. No server, no API key, no rate limit.
- [Geocode a CSV without an API key](https://gridpin.dev/geocode-csv): A spreadsheet of addresses in, latitude and longitude out, on your own machine. No sign-up, no quota, no per-row bill.
- [Geocode addresses inside DuckDB](https://gridpin.dev/duckdb-geocoding): Install the extension from the DuckDB community repository, load a country file and geocode a whole table in SQL. No service to call, no keys.
- [Offline reverse geocoding to street level](https://gridpin.dev/reverse-geocoding): Coordinates in, the nearest address out: street, house number, municipality and how far it is. Offline, from one file per country.
- [Offline geocoding in GeoPandas](https://gridpin.dev/geopandas-geocoding): geopandas.tools.geocode takes any geopy-style geocoder. Give it GridPin and the addresses are geocoded on your machine: no API key, no rate limit, no request leaves it.
- [Offline geocoding in R](https://gridpin.dev/r-geocoding): The R package gridpin (from R-universe) geocodes a vector or data frame of addresses on your machine; the duckdb package with the GridPin extension does the same in one SQL query. No API key, no service, and no address leaves your computer.
- [Geocoding for AI agents, with no API key](https://gridpin.dev/mcp-geocoding): gridpin-mcp is an MCP server: your agent gets geocode, reverse and batch tools that run on your machine. Nothing to sign up for.
- [An alternative to self-hosting Nominatim](https://gridpin.dev/nominatim-alternative): Nominatim, Photon and Pelias are servers with a database import. GridPin is a file per country that a library opens in milliseconds. Both have their place.
- [A local geocoding server](https://gridpin.dev/geocoding-server): One command turns a country file into an HTTP geocoder on your machine: its own JSON API and the Nominatim paths that existing clients already call. No database, no import, and no address leaves the machine.
- [Migrate from google geocoding](https://gridpin.dev/migrate-from-google-geocoding): Move off the Google Geocoding API with one base URL
- [Cut geocoding bill](https://gridpin.dev/cut-geocoding-bill): What geocoding costs and what to move to a local file first
- [Lightweight geocoder](https://gridpin.dev/lightweight-geocoder): Self-host a geocoder for one country without Java, Elasticsearch or an import
- [Fleet tracking geocoding](https://gridpin.dev/fleet-tracking-geocoding): Reverse geocoding for Traccar and other trackers on your own machine
- [Spark geocoding](https://gridpin.dev/spark-geocoding): Geocode a Spark or Databricks column offline with an iterator pandas UDF
- [LLM versus geocoder](https://gridpin.dev/llm-vs-geocoder): What published studies measured when language models geocode, and how to give a model a geocoder as a tool
- [Keep your geocoding results](https://gridpin.dev/store-geocoding-results): Google allows 30 days of cached coordinates; Mapbox and Esri charge 6 to 8 times more to store them; a geocoder on your own disk leaves the result yours
- [Geocoding without sending addresses anywhere](https://gridpin.dev/geocoding-privacy): What leaves the machine when GridPin geocodes (nothing) and how to check it yourself with lsof and tcpdump
- [Geocode patient addresses on your own machine](https://gridpin.dev/geocoding-patient-addresses): Health research without a business associate agreement: masked or aggregated output, compared with DeGAUSS
- [Geocoding you can cite and repeat](https://gridpin.dev/geocoding-for-research): Cite the sheet by its SHA-256, keep a receipt of the run and repeat the step years later
- [Geocoding incident addresses](https://gridpin.dev/geocoding-crime-analysis): Blocks and crossings of police records, the match rate against Ratcliffe's 85%, publication by cell or with masking
- [Countries](https://gridpin.dev/countries): Every country GridPin covers, with file size, number of addresses and data source
- [Addresses on a BI map](https://gridpin.dev/bi-geocoding): Geocode the address column once for Power BI, Tableau or Metabase; filter weak rows by match level
- [Photo places to the street](https://gridpin.dev/immich-reverse-geocoding): Reverse geocode photo GPS for Immich, PhotoPrism or Nextcloud on your own server
- [Field service jobs](https://gridpin.dev/field-service-geocoding): Check that an address exists before the trip, then split the jobs into areas
- [Home address to attendance zone](https://gridpin.dev/school-enrollment-geocoding): Geocode student addresses offline and join them to your zone polygons
- [Service addresses in a billing system](https://gridpin.dev/utility-billing-addresses): Find service addresses that do not exist and fields that were replaced
- [Requests and permits on one address list](https://gridpin.dev/311-permits-geocoding): A sheet cut to the city; reverse geocode request points, check permit addresses
- [Dispatch addresses without a link](https://gridpin.dev/fire-ems-geocoding): A local server on a cut of the sheet that keeps answering without the internet
- [An address for every charger](https://gridpin.dev/ev-charging-geocoding): Reverse geocode charger points and print them in the layout of the country's post
- [Store addresses that agree](https://gridpin.dev/store-listings-addresses): Check each store listing and print one form; tell whether two lines name one house
- [Patients to trial sites, privately](https://gridpin.dev/clinical-trial-sites): Distances from patients to sites on your own machine; share counts by cell
- [Offline geocoding in Docker](https://gridpin.dev/docker-geocoding): One image per country, with the address file inside and checked when the image was built. It serves the same HTTP API as gridpin serve and never connects out.
- [A geocoder built on Overture Maps data](https://gridpin.dev/overture-geocoder): Overture Maps publishes addresses from national registries. GridPin turns each country into one file you can query offline.
- [How it works: one memory-mapped file per country](https://gridpin.dev/how-it-works): A Rust engine reads one file per country straight from disk. Nothing is loaded into a database, so it starts in milliseconds and runs on a laptop.
- [Geocode US addresses offline](https://gridpin.dev/geocoding-usa): One 1.45 GB file for the 50 states and DC, read locally; point addresses in 35 states, Census address ranges elsewhere. No server, no API key, and the addresses you geocode never leave your machine.
- [Geocode Canadian addresses offline](https://gridpin.dev/geocoding-canada): One 183 MB file for all provinces and territories, read locally; answers carry the Canadian postal code. No server, no API key, and the addresses you geocode never leave your machine.
- [Geocode Australian addresses offline](https://gridpin.dev/geocoding-australia): One 130 MB file for all states and territories, read locally. No server, no API key, and the addresses you geocode never leave your machine.
- [Geocode Mexican addresses offline](https://gridpin.dev/geocoding-mexico): One 156 MB file for all 32 states, read locally; answers carry the Mexican postal code where the source has one. Address layer surveyed 2009–2010.
- [Geocode Brazil addresses offline](https://gridpin.dev/geocoding-brazil): One file for all of Brazil, read locally. No server, no API key, and the addresses you geocode never leave your machine.
- [Geocode France addresses offline](https://gridpin.dev/geocoding-france): One file for all of France, read locally. No server, no API key, and the addresses you geocode never leave your machine.
- [Geocode Germany addresses offline](https://gridpin.dev/geocoding-germany): One file for all of Germany, read locally. No server, no API key, and the addresses you geocode never leave your machine.
- [Geocode Italy addresses offline](https://gridpin.dev/geocoding-italy): One file for all of Italy, read locally. No server, no API key, and the addresses you geocode never leave your machine.
- [Geocode Netherlands addresses offline](https://gridpin.dev/geocoding-netherlands): One file for all of Netherlands, read locally. No server, no API key, and the addresses you geocode never leave your machine.
- [Geocode Serbia addresses offline](https://gridpin.dev/geocoding-serbia): One file for all of Serbia, read locally. No server, no API key, and the addresses you geocode never leave your machine.
- [Geocode Spain addresses offline](https://gridpin.dev/geocoding-spain): One file for all of Spain, read locally. No server, no API key, and the addresses you geocode never leave your machine.
- [Free and Pro, feature by feature](https://gridpin.dev/free-vs-pro): what the free engine and sheets do and what the Pro subscription adds
- [gridpin-pro: the Pro tools](https://gridpin.dev/pro): dedupe, compare, an action per row (ACCEPT / CONFIRM / UNMATCHED), audit page, US census layer, sheet-diff between releases
- [Find duplicate addresses in a customer list](https://gridpin.dev/find-duplicate-addresses): One customer typed the street in full, another abbreviated it, a third got the ZIP code wrong. To a spreadsheet they are three addresses; to the post they are one house.
- [Audit an address database before migration](https://gridpin.dev/audit-address-database): Before a billing or CRM migration someone asks how good the addresses are. One command answers with a page you can attach to the ticket, and no address leaves your machine.
- [Find the weak rows and review them by hand](https://gridpin.dev/weak-rows-review): Most rows of an address list geocode to the house. The few that do not should reach a person, not a report, and that person should see why the answer is in doubt.
- [What changed between two address files](https://gridpin.dev/what-changed-in-addresses): Each month a new export of the same customers or service points arrives. The question is not which lines differ as text, but which ones now point somewhere else.
- [What GridPin checks, and what it does not](https://gridpin.dev/what-we-check-and-what-we-dont): An address can exist on a map and still not receive mail. Before you put an address check in front of a form or a billing run, know which question it answers.
- [Where GridPin works and where it does not](https://gridpin.dev/country-coverage-honest): A geocoder that answers everywhere is guessing somewhere. Here is where the country files are thin, and how an answer from such a place reads.
- [Pull addresses out of emails and tickets](https://gridpin.dev/extract-addresses-from-text): Customers write the address in the middle of a sentence. To route a ticket or check a delivery you need that address as a point, and the ticket text should not go to a cloud service to get it.
- [Your own place names: HQ, depot 3, store 117](https://gridpin.dev/your-own-places-sheet): People write “deliver to depot 3”, not an address. Two ways to make those names answer: a table of aliases for a handful of names, and a sheet of your own places for hundreds.
- [Nearest warehouse and delivery zones](https://gridpin.dev/nearest-warehouse-delivery-zones): Each order should go out from the closest depot, and each van should get a fair share of stops. Both questions start from the same geocoded list.
- [Test addresses for your integration tests](https://gridpin.dev/test-addresses-sample): Tests of a checkout form or an address import need addresses that exist, and the same ones each time. Made-up addresses test the wrong path; production data should not be in a test fixture.
- [Read the sheet directly: list, export, slice](https://gridpin.dev/list-export-slice-sheet): Sometimes the question is not where an address is, but which addresses there are: every house on a street, every address in a postcode, a small file for one town.
- [Address autocomplete on your own server](https://gridpin.dev/address-autocomplete-self-hosted): Hosted address autocomplete is billed by session or by keystroke and sees every address your customers type. A local server can answer the same field from the country file.
- [Geocode a CSV in the browser, no terminal](https://gridpin.dev/geocode-csv-in-the-browser): The person with the spreadsheet should not need a terminal. The local server has a page for exactly that: drop a CSV, pick the address column, download the result.
- [Google Places API changed: what a store owner does](https://gridpin.dev/google-places-api-change): A plugin stopped showing your stores on a map, or a developer says the key has to move to a new API. If what you need is your addresses as points, that part does not need Google at all.
- [Structured postal addresses for ISO 20022 payments](https://gridpin.dev/iso20022-postal-address): Payment messages are moving to structured addresses: street, building number, postcode and town in their own elements, not one free line. Most address lists hold the free line.
- [Clean a customer address list in an afternoon](https://gridpin.dev/clean-customer-addresses): A customer list collects years of typing. The fix is not to read every row, but to let the address data sort the rows and to spend people only on the ones it cannot decide.
- [Print addresses the way the post lays them out](https://gridpin.dev/address-list-for-mailing): A label needs the street line and the postcode line in the order the post reads them, spelled the way the address data spells them. A line that cannot be confirmed should not reach a label at all.
- [Hit 429 on public Nominatim? Use your own server](https://gridpin.dev/nominatim-429-rate-limit): Your script sleeps a second between addresses and still gets 429 Too Many Requests or a block. The public server is shared and says so; the fix is a server of your own, not a longer sleep.
- [Seven clients, one line each](https://gridpin.dev/seven-libraries-one-line): Whatever the language of the program that needs an address, the request is the same: a GET to /search with the address in q. Here is that line seven times.
- [API changelog and the /v1 policy](https://gridpin.dev/api-changelog-and-versioning): Code that calls the local server should survive an update of the server. Here is what each release added, and the rule we follow for the paths under /v1.
- [Fully offline, in Kubernetes, with metrics](https://gridpin.dev/offline-helm-metrics): A cluster without internet access still needs addresses as points. Each image carries its country file and checks nothing outside; the Pro server adds who called, how often and how fast.
- [Self-hosted travel planners: point TREK at your geocoder](https://gridpin.dev/travel-planner-self-hosted): A self-hosted trip planner still sends every address you look up to a public geocoder. TREK has a setting to send those calls to a server of your own instead.
- [Sulu CMS with a local geocoder](https://gridpin.dev/cms-helpdesk-geocoding): Content editors place offices, events and stores by typing an address into a location field. In Sulu that lookup goes to the endpoint in one line of configuration.
- [Offline geocoding in Node.js](https://gridpin.dev/node-geocoding): A Node.js service that geocodes addresses usually calls an API for each one. The npm package reads a country file in the same process instead.
- [Geocode inside SQLite and Datasette](https://gridpin.dev/sqlite-datasette-geocoding): When the addresses are already in a SQLite file, geocoding them should be a query, not an export, a script and an import.
- [Addresses for Home Assistant automations](https://gridpin.dev/home-assistant-addresses): Automations that say where someone is need an address, and the usual way to get one sends every position of every phone to a cloud geocoder. A server on your network answers instead.
- [Geocode a polars column and check the match rate](https://gridpin.dev/polars-geocoding): A column of addresses in polars, and two questions: where is each one, and how much of the column can be trusted. Both are answered on your machine, with no API key and no request per row.

## Guides by topic

- [Geocoding guides for Python](https://gridpin.dev/guides-where-python): Address to point and back inside a Python script, a notebook or a data frame.
- [Geocoding guides for R, Spark and BI tools](https://gridpin.dev/guides-where-data-platforms): Coordinates as columns of the data your analysts already use.
- [Guides to a local geocoding server](https://gridpin.dev/guides-where-server): One process or one container per country that answers HTTP, offline.
- [Guides: geocode addresses](https://gridpin.dev/guides-task-geocode): A list or a column of addresses in, points out.
- [Guides: reverse geocoding](https://gridpin.dev/guides-task-reverse): A GPS point in, the nearest address and its distance out.
- [Guides: your own places, nearest and zones](https://gridpin.dev/guides-task-own-places-zones): Your depots, sites and zones beside the address data of a country.
- [Guides: move off a paid geocoding API](https://gridpin.dev/guides-task-migrate-off-api): What changes when the geocoder is a file on your disk instead of a bill.
- [Guides: run your own geocoder](https://gridpin.dev/guides-task-self-host): A geocoder on your own machine, cluster or network, with no link to the outside.
- [Guides: privacy and research](https://gridpin.dev/guides-task-privacy-research): Where the addresses go, what to publish, how to cite a run.
- [Guides: how it works and where it stops](https://gridpin.dev/guides-task-limits): What a file-based geocoder does well, what it does not, and why.
- [Geocoding guides for the public sector](https://gridpin.dev/guides-who-public-sector): City services, schools, police and emergency calls.
- [Geocoding guides for research](https://gridpin.dev/guides-who-research): Runs you can repeat, cite and publish without the addresses.
- [Geocoding guides for the command line](https://gridpin.dev/guides-where-command-line): One program and a country file: geocode a CSV from the terminal or from a scheduled job.
- [Guides: clean, deduplicate and compare addresses](https://gridpin.dev/guides-task-clean-audit): Find what does not exist, what is written twice and what has changed.
- [Geocoding guides for retail and e-commerce](https://gridpin.dev/guides-who-retail-ecommerce): Customer lists, store listings and checkout forms.
- [Geocoding guides for logistics and field work](https://gridpin.dev/guides-who-logistics-field): Depots, rounds, vehicles and the address of the next job.
- [Geocoding guides for health care](https://gridpin.dev/guides-who-health): Patient and site addresses that must stay on your machine.
- [Geocoding guides for utilities](https://gridpin.dev/guides-who-utilities): Service addresses, meters, chargers and the bills that go with them.
- [Geocoding guides for websites and help desks](https://gridpin.dev/guides-who-web-helpdesk): Address fields, contact forms and tickets that carry an address.
- [Geocoding guides for JavaScript and Node.js](https://gridpin.dev/guides-where-javascript): The same answers from Node.js and from a page in the browser.
- [Geocoding for self-hosted apps](https://gridpin.dev/guides-where-self-hosted-apps): Point an app you run yourself at a geocoder that runs beside it.
- [Geocoding guides for SQL](https://gridpin.dev/guides-where-sql): Geocode the rows of a table where the table already lives.

## Optional

- [Sheet format](https://raw.githubusercontent.com/gridpin/gridpin/main/docs-public/FORMAT.md): binary layout of a sheet
- [Data freshness](https://gridpin.dev/freshness): Overture release behind each sheet
- [Attributions](https://raw.githubusercontent.com/gridpin/gridpin/main/ATTRIBUTIONS.md): data licenses
- [Source](https://github.com/gridpin/gridpin)