gridpin

API changelog and the /v1 policy

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.

Run it yourself Server, Docker Python

What you have

A running server: the page at / lists what it answers. The full description is openapi.json.

Steps

1. Start a server and ask it what it answers:

terminalCLI
$ gridpin serve usa.bin --port 8080
terminalCLI
$ curl -s http://127.0.0.1:8080/
GridPin 0.8.0 — offline geocoder, sheet usa.bin (us).

GET  /v1/geocode?q=...&k=1[&near=lat,lon]   {"results": [...]}
POST /v1/geocode  {"queries": [...], "k": 1}   {"results": [[...], ...]}  (a query: text or {"street", "housenumber", "city", "region", "postcode"})
GET  /v1/reverse?lat=...&lon=...&k=1
GET  /v1/suggest?q=...&k=8   streets that start as the typed text, for an address field
GET  /ui   a page: drop a CSV, get it back geocoded
POST /v1/extract  {"text": "...", "verify": false}   addresses found in a free text
(every path takes with=h3,geohash,placekey,codes,street_point,links,provenance: an `extras` object per answer)
GET  /search?q=...&format=jsonv2|json|geojson&limit=10&addressdetails=1   Nominatim-compatible
GET  /reverse?lat=...&lon=...&format=jsonv2                              Nominatim-compatible
GET  /status?format=json
GET  /maps/api/geocode/json?address=...|latlng=lat,lng                   Google-compatible
GET  /health

Documentation: https://gridpin.dev/geocoding-server

What you get

ReleaseDatePaths
0.7.0November 2, 2026/v1/geocode (GET and POST), /v1/reverse, /health, /; Nominatim /search, /reverse, /status (also with .php)
0.7.1, 0.8.0November 3 and 6, 2026no change of paths
0.9.0 new in 0.9.0November 12, 2026/v1/suggest, /v1/extract, /v1/exists, /v1/explain, /ui, Google-compatible /maps/api/geocode/json; with= on every path; the OpenAPI description

Dates are those of the release tags in the public repository.

Why it works

Within 0.x the paths under /v1 only grow: a new path, a new optional parameter or a new field in an answer is not a breaking change, so read answers by field name and ignore fields you do not know. A removed path or a renamed field would mean a new major version, and the old path would answer until then. No dates of support are promised.

Limits

  • The Nominatim and Google paths follow those services' shapes as far as GridPin implements them; parameters it does not read are ignored, not refused.
  • The / page and /health are for people and probes, not a contract: their text can change in any release.
  • The policy covers the HTTP server; the command line, the Python module and the file format have their own notes in the release notes.

All its keys: command reference. The functions: local server, OpenAPI description.

More