HTTP API
Every route of tgd serve with its parameters, generated from the server's route table.
Every route answers GET with query parameters. A native route (/v1/…) answers {"results": [...], "attribution": "..."}, or {"result": ..., "attribution": "..."} for one value; each place has the fields of a place, because both servers map a place in one place. The Nominatim routes answer Nominatim's own format. How to run the server, with examples that ran: HTTP server.
Every native place route also takes:
| Parameter | Required | What |
|---|---|---|
format | json (the default) or geojson: a FeatureCollection (RFC 7946) of the places. |
Native routes
/v1/search
Places matching a name in any script or spelling, best first, each with its score. "Name, Parent" ranks places under a parent of that name first.
| Parameter | Required | What |
|---|---|---|
q | yes | The name to find, such as Pokhara, पोखरा or Pokhara, Kaski. |
limit | How many results: 10 by default, at most the server's bound (50). | |
focus | lat,lon: rank places near this point higher (30 points at the point, halving every scale_km). | |
scale_km | How far counts as near the focus, in km: 50 by default. Read only with focus. | |
strict | 1: rank by how well the name matched before anything else. |
GET /v1/search?q=Pokhara&limit=3&strict=1
GET /v1/search?q=Pokhara&focus=28.2,83.9&scale_km=20/v1/get
One place by its ID; a retired ID answers its survivor.
| Parameter | Required | What |
|---|---|---|
id | yes | A place ID, such as tgd:np/1xhb. |
names | 1: add every name of the place, with its language and origin. |
GET /v1/get?id=tgd:np/1xhb&names=1/v1/lookup
Places by ID, in the order asked; IDs not found are left out.
| Parameter | Required | What |
|---|---|---|
ids | yes | Comma-separated place IDs, at most the server's limit bound. |
GET /v1/lookup?ids=tgd:np/1xhb,tgd:np/1wmc/v1/reverse
The places nearest a point, nearest first, each with meters, bearing (degrees clockwise from north) and inside (its outline holds the point).
| Parameter | Required | What |
|---|---|---|
lat | yes | Latitude, WGS84 degrees, -90 to 90. |
lon | yes | Longitude, WGS84 degrees, -180 to 180. |
limit | How many results: 10 by default, at most the server's bound (50). | |
in_country | 1: only places in the country that holds the point. |
GET /v1/reverse?lat=28.21&lon=83.99&limit=3&in_country=1/v1/near
The places nearest a place, nearest first, the place itself left out.
| Parameter | Required | What |
|---|---|---|
id | yes | A place ID, such as tgd:np/1xhb. |
limit | How many results: 10 by default, at most the server's bound (50). | |
radius_m | Only places within this many metres (at most 1,000,000). |
GET /v1/near?id=tgd:np/1xhb&limit=5&radius_m=5000/v1/admin
The admin units holding a point: the country first, then each finer level.
| Parameter | Required | What |
|---|---|---|
lat | yes | Latitude, WGS84 degrees, -90 to 90. |
lon | yes | Longitude, WGS84 degrees, -180 to 180. |
GET /v1/admin?lat=27.7172&lon=85.324/v1/hierarchy
A place's ancestors: its parent first, up to the country.
| Parameter | Required | What |
|---|---|---|
id | yes | A place ID, such as tgd:np/1xhb. |
GET /v1/hierarchy?id=tgd:np/1xhb/v1/children
A place's children, by ID.
| Parameter | Required | What |
|---|---|---|
id | yes | A place ID, such as tgd:np/1xhb. |
limit | How many results: 10 by default, at most the server's bound (50). |
GET /v1/children?id=tgd:np/1wmc&limit=20/v1/tz
The timezone of a place or a point, with its UTC offset, abbreviation and daylight-saving flag at an instant.
| Parameter | Required | What |
|---|---|---|
id | A place ID; or give lat and lon. | |
lat | Latitude, with lon, when no id is given. | |
lon | Longitude, with lat. | |
t | The instant, in Unix seconds: now by default. |
GET /v1/tz?id=tgd:np/1xhb&t=1767225600
GET /v1/tz?lat=27.7172&lon=85.324/v1/elevation
The terrain height at a point in metres above EGM2008, with the grid's source and spacing. One value, under result.
| Parameter | Required | What |
|---|---|---|
lat | yes | Latitude, WGS84 degrees, -90 to 90. |
lon | yes | Longitude, WGS84 degrees, -180 to 180. |
GET /v1/elevation?lat=27.9881&lon=86.925/v1/distance
The great-circle distance in metres and the initial bearing between two points or places. One value, under result.
| Parameter | Required | What |
|---|---|---|
from | yes | lat,lon or a place ID. |
to | yes | lat,lon or a place ID. |
GET /v1/distance?from=27.7172,85.324&to=tgd:np/1xhb/v1/postal
The places a postal code names, codes starting with a prefix, or the codes at a point.
| Parameter | Required | What |
|---|---|---|
code | A postal code, with or without separators, in any case or script's digits; or give lat and lon. | |
scheme | The scheme, when a country has more than one. | |
prefix | 1: complete code as a prefix. | |
limit | How many results with code: 10 by default. | |
lat | Latitude, with lon, when no code is given. | |
lon | Longitude, with lat. |
GET /v1/postal?code=44600&prefix=1&limit=5&scheme=np
GET /v1/postal?lat=27.7172&lon=85.324/v1/boundary
An admin unit's outline as a GeoJSON Feature, in any format.
| Parameter | Required | What |
|---|---|---|
id | yes | A place ID, such as tgd:np/1xhb. |
lod | The level of detail, 0 (finest, the default) to 6 (coarsest). |
GET /v1/boundary?id=tgd:np/1wmc&lod=3/v1/coverage
The catalog's packs that cover a point, with their sizes: what to install for it. A server over a store only.
| Parameter | Required | What |
|---|---|---|
lat | yes | Latitude, WGS84 degrees, -90 to 90. |
lon | yes | Longitude, WGS84 degrees, -180 to 180. |
radius_m | Also the packs within this many metres. |
GET /v1/coverage?lat=25.2048&lon=55.2708&radius_m=10000Nominatim routes
The parameters and fields of Nominatim that its clients use; what teigeodata cannot fill is left out, never faked. IDs are teigeodata's.
/search
Nominatim's search: a JSON array of Nominatim places.
| Parameter | Required | What |
|---|---|---|
q | Free-form text; or the structured fields below. | |
amenity | Structured search: joined with the other fields, most specific first. | |
street | Structured search. | |
city | Structured search. | |
county | Structured search. | |
state | Structured search. | |
country | Structured search. | |
postalcode | Structured search. | |
limit | How many results: 10 by default, at most 40. | |
countrycodes | Comma-separated ISO 3166-1 alpha-2 codes to keep. | |
viewbox | x1,y1,x2,y2 (longitude first): rank places in the box higher. | |
bounded | 1: only places in viewbox. | |
addressdetails | 1: add each place's address. | |
format | json (the default), jsonv2 (the same) or geojson. | |
json_callback | Refused: JSONP is not supported; call with CORS. |
GET /search?q=Pokhara&limit=3&countrycodes=np&viewbox=83.8,28.1,84.1,28.3&bounded=1&addressdetails=1&format=jsonv2
GET /search?city=Pokhara&country=Nepal/reverse
Nominatim's reverse: the place at a point at a zoom's depth, or {"error": "Unable to geocode"}.
| Parameter | Required | What |
|---|---|---|
lat | yes | Latitude, WGS84 degrees, -90 to 90. |
lon | yes | Longitude, WGS84 degrees, -180 to 180. |
zoom | How deep: 3 a country, 5 to 7 a first-level unit, 8 and 9 the next, 10 to 18 the nearest place within reach; 18 by default. | |
addressdetails | 0 leaves out address (on by default). | |
format | json (the default), jsonv2 (the same) or geojson. | |
json_callback | Refused: JSONP is not supported. |
GET /reverse?lat=28.21&lon=83.99&zoom=10&addressdetails=0&format=geojson/lookup
Nominatim's lookup: places by ID, as a JSON array.
| Parameter | Required | What |
|---|---|---|
osm_ids | yes | Comma-separated teigeodata IDs, at most 50; an OSM reference such as N123 is left out as not found. |
addressdetails | 1: add each place's address. | |
format | json (the default), jsonv2 (the same) or geojson. | |
json_callback | Refused: JSONP is not supported. |
GET /lookup?osm_ids=tgd:np/1xhb,N123&addressdetails=1Other routes
| Route | What |
|---|---|
/packs | The packs served: each one's release, components, places and attribution. |
/health | {"status": "ok", "layers": n} while the server answers. |
/mcp | The MCP server, over Streamable HTTP. |
Errors
A failure answers {"error": {"code": "...", "message": "..."}} with the code's HTTP status; a Nominatim route puts the status in code. Codes are stable: one may be added, none changes its meaning.
| Code | Status | Meaning |
|---|---|---|
invalid_argument | 400 | A parameter does not parse or has no meaning (a bad ID, a latitude past 90°). |
out_of_bounds | 400 | A parameter is past a server bound: too long a text, too large a limit, too far a radius. A query string that is too long answers 414. |
not_found | 404 | The place is not in the packs, or there is no such route. |
missing_component | 501 | The packs served lack the component that answers this. |
unauthenticated | 401 | The caller must say who they are: only a deployment that adds keys answers it. |
forbidden | 403 | The caller may not ask this: only a deployment that adds rules answers it. |
rate_limited | 429 | Too much, too fast: only a deployment that adds limits answers it. |
unavailable | 503 | The server cannot answer now (the request took longer than its timeout); asking again later may work. |
internal | 500 | The server failed; never the client's fault. |