Skip to content
DuckDB community extension

gridpin_ext

Offline geocoding from a single country file — forward and reverse, no server, no network

01 / SETUP

Install and load

Run these commands in a Haybarn SQL session. The extension is available from the community repository.

Haybarn 2.0.0 · SQL
INSTALL gridpin_ext FROM community;
LOAD gridpin_ext FROM community;

Using upstream DuckDB? Follow the maintainer’s installation instructions.

02 / QUERY

Usage example

Country data files are free downloads: https://gridpin.dev

SQL
-- Country data files are free downloads: https://gridpin.dev
-- (the United States, Canada, Germany, France, Italy, Spain, Mexico, the Netherlands, Brazil and Serbia today; one file per country.)

-- Point the extension at a downloaded sheet. One sheet is loaded at a time.
SELECT gridpin_load('./france.bin');

-- Forward geocoding: an address string in, a JSON object out.
SELECT gridpin_geocode('10 rue de rivoli paris');

-- Reverse geocoding: coordinates in, the nearest address out.
SELECT gridpin_reverse(48.8686, 2.3305);

-- It is an ordinary scalar function, so a whole table geocodes in one query.
SELECT id,
       json_extract(gridpin_geocode(address), '$.lat') AS lat,
       json_extract(gridpin_geocode(address), '$.lon') AS lon
FROM customers;

Provided by gridpin. Not yet verified on Haybarn 2.0.0.

Sample data & setup

About this extension

GridPin resolves addresses to coordinates and back entirely offline: one memory-mapped file per country, millisecond lookups on a single core, and typo tolerance built into the index. There is no server to run, no database to import, no API key and no per-request fee — the addresses you geocode never leave the machine.

Every function carries a description and parameter names, so SQL assistants and AI agents can discover them through duckdb_functions().

Project overview from the community descriptor.

Documentation and resources

Project and build details
Repository
gridpin/duckdb-gridpin
License
Apache-2.0
Maintainers
gridpin-reserve
Written in
Rust
Build source
e9b748f9a9ae
Build definition
Community descriptor