Skip to Content
teigeodata
Reference

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:

ParameterRequiredWhat
formatjson (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.

ParameterRequiredWhat
qyesThe name to find, such as Pokhara, पोखरा or Pokhara, Kaski.
limitHow many results: 10 by default, at most the server's bound (50).
focuslat,lon: rank places near this point higher (30 points at the point, halving every scale_km).
scale_kmHow far counts as near the focus, in km: 50 by default. Read only with focus.
strict1: 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.

ParameterRequiredWhat
idyesA place ID, such as tgd:np/1xhb.
names1: 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.

ParameterRequiredWhat
idsyesComma-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).

ParameterRequiredWhat
latyesLatitude, WGS84 degrees, -90 to 90.
lonyesLongitude, WGS84 degrees, -180 to 180.
limitHow many results: 10 by default, at most the server's bound (50).
in_country1: 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.

ParameterRequiredWhat
idyesA place ID, such as tgd:np/1xhb.
limitHow many results: 10 by default, at most the server's bound (50).
radius_mOnly 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.

ParameterRequiredWhat
latyesLatitude, WGS84 degrees, -90 to 90.
lonyesLongitude, 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.

ParameterRequiredWhat
idyesA place ID, such as tgd:np/1xhb.
GET /v1/hierarchy?id=tgd:np/1xhb

/v1/children

A place's children, by ID.

ParameterRequiredWhat
idyesA place ID, such as tgd:np/1xhb.
limitHow 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.

ParameterRequiredWhat
idA place ID; or give lat and lon.
latLatitude, with lon, when no id is given.
lonLongitude, with lat.
tThe 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.

ParameterRequiredWhat
latyesLatitude, WGS84 degrees, -90 to 90.
lonyesLongitude, 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.

ParameterRequiredWhat
fromyeslat,lon or a place ID.
toyeslat,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.

ParameterRequiredWhat
codeA postal code, with or without separators, in any case or script's digits; or give lat and lon.
schemeThe scheme, when a country has more than one.
prefix1: complete code as a prefix.
limitHow many results with code: 10 by default.
latLatitude, with lon, when no code is given.
lonLongitude, 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.

ParameterRequiredWhat
idyesA place ID, such as tgd:np/1xhb.
lodThe 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.

ParameterRequiredWhat
latyesLatitude, WGS84 degrees, -90 to 90.
lonyesLongitude, WGS84 degrees, -180 to 180.
radius_mAlso the packs within this many metres.
GET /v1/coverage?lat=25.2048&lon=55.2708&radius_m=10000

Nominatim routes

The parameters and fields of Nominatim that its clients use; what teigeodata cannot fill is left out, never faked. IDs are teigeodata's.

Nominatim's search: a JSON array of Nominatim places.

ParameterRequiredWhat
qFree-form text; or the structured fields below.
amenityStructured search: joined with the other fields, most specific first.
streetStructured search.
cityStructured search.
countyStructured search.
stateStructured search.
countryStructured search.
postalcodeStructured search.
limitHow many results: 10 by default, at most 40.
countrycodesComma-separated ISO 3166-1 alpha-2 codes to keep.
viewboxx1,y1,x2,y2 (longitude first): rank places in the box higher.
bounded1: only places in viewbox.
addressdetails1: add each place's address.
formatjson (the default), jsonv2 (the same) or geojson.
json_callbackRefused: 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"}.

ParameterRequiredWhat
latyesLatitude, WGS84 degrees, -90 to 90.
lonyesLongitude, WGS84 degrees, -180 to 180.
zoomHow 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.
addressdetails0 leaves out address (on by default).
formatjson (the default), jsonv2 (the same) or geojson.
json_callbackRefused: 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.

ParameterRequiredWhat
osm_idsyesComma-separated teigeodata IDs, at most 50; an OSM reference such as N123 is left out as not found.
addressdetails1: add each place's address.
formatjson (the default), jsonv2 (the same) or geojson.
json_callbackRefused: JSONP is not supported.
GET /lookup?osm_ids=tgd:np/1xhb,N123&addressdetails=1

Other routes

RouteWhat
/packsThe packs served: each one's release, components, places and attribution.
/health{"status": "ok", "layers": n} while the server answers.
/mcpThe 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.

CodeStatusMeaning
invalid_argument400A parameter does not parse or has no meaning (a bad ID, a latitude past 90°).
out_of_bounds400A 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_found404The place is not in the packs, or there is no such route.
missing_component501The packs served lack the component that answers this.
unauthenticated401The caller must say who they are: only a deployment that adds keys answers it.
forbidden403The caller may not ask this: only a deployment that adds rules answers it.
rate_limited429Too much, too fast: only a deployment that adds limits answers it.
unavailable503The server cannot answer now (the request took longer than its timeout); asking again later may work.
internal500The server failed; never the client's fault.

On this page