Reverse geocoding
GET /v1/reverse-geocode answers 'what is here?': a single KNN query over a GiST index returns the nearest PRG address points — number, street, postal code and distance in kilometres. When no address point is within 128 km, the answer falls back to the nearest localities from the index (result: 'locality').
GET /v1/reverse-geocode
lat and lon are required (a blank value is a 400, not 0); limit 1–50, default 5. format=geojson returns a FeatureCollection.
Try it live: /v1/reverse-geocode?lat=52.23&lon=21.01&limit=3
| Name | Required | Description |
|---|---|---|
lat | ✓ | WGS84 latitude. Required — a blank value ('?lat=') is a 400, not 0. |
lon | ✓ | WGS84 longitude. Required — a blank value ('?lon=') is a 400, not 0. |
limit | — | Maximum matches (1–50). |
format | — | 'geojson' answers an RFC 7946 FeatureCollection (every match a Feature) instead of the JSON envelope. |
Example
Warsaw city centre
curl "https://teryt24.pl/v1/reverse-geocode?lat=52.23&lon=21.01&limit=3"Response:
{
"result": "address",
"matches": [
{ "lat": 52.22928405785922, "lon": 21.01027584557396, "number": "45", "streetId": "45207", "streetName": null, "localitySym": "0988796", "localityName": "Warszawa", "postalCode": "00-692", "distanceKm": 0.082 },
{ "lat": 52.230523920557715, "lon": 21.00886365169035, "number": "101B", "streetId": "12400", "streetName": null, "localitySym": "0988796", "localityName": "Warszawa", "postalCode": "00-110", "distanceKm": 0.097 },
{ "lat": 52.22910299200578, "lon": 21.00942056875035, "number": "47", "streetId": "45207", "streetName": null, "localitySym": "0988796", "localityName": "Warszawa", "postalCode": "00-697", "distanceKm": 0.107 }
]
}| Status | Description |
|---|---|
200 | 'address' (PRG points, with street/locality/postal) or 'locality' (Phase 1 fallback) or 'none'. |
400 | Invalid query parameters. |
429 | Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. |
500 | Unexpected server failure (e.g. the database is unreachable). The body is deliberately generic — error detail lives in the server logs, never in the response. |
503 | Address dataset not available (POST /admin/ingest-prg). |
Browse the data
The codes and localities in the response have their own pages:
All /v1 endpoints return JSON, speak CORS and are covered by the openapi.json document. Interactive version of this reference: /en/docs.
Limits: 60 requests/min per IP without a key; an API key (the X-API-Key header) gets its own bucket. Over the limit the endpoints answer HTTP 429 with a Retry-After header. Details: limits & keys · usage policy.
Data: GUS TERYT, PRG address points (GUGiK), GeoNames postal codes — via teryt24.pl with a link to the usage policy. Server-side-only use is exempt.