Odwrócone geokodowanie
GET /v1/reverse-geocode odpowiada na pytanie „co tu jest?”: pojedyncze zapytanie KNN po indeksie GiST zwraca najbliższe punkty adresowe PRG — numer, ulica, kod pocztowy i odległość w kilometrach. Gdy w promieniu 128 km nie ma punktu adresowego, odpowiedź przechodzi na najbliższe miejscowości z indeksu (result: „locality”).
GET /v1/reverse-geocode
lat i lon są wymagane (pusta wartość to 400, nie 0); limit 1–50, domyślnie 5. format=geojson zwraca FeatureCollection.
Sprawdź na żywo: /v1/reverse-geocode?lat=52.23&lon=21.01&limit=3
| Nazwa | Wymagany | Opis |
|---|---|---|
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. |
Przykład
Śródmieście Warszawy
curl "https://teryt24.pl/v1/reverse-geocode?lat=52.23&lon=21.01&limit=3"Odpowiedź:
{
"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 | Opis |
|---|---|
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). |
Przeglądaj dane
Kody i miejscowości z odpowiedzi mają swoje strony:
Wszystkie endpointy /v1 zwracają JSON, obsługują CORS i są objęte dokumentem openapi.json. Interaktywna wersja tej referencji: /docs.
Limity: 60 zapytań/min na IP bez klucza; klucz API (nagłówek X-API-Key) dostaje własny kubełek. Po przekroczeniu endpointy odpowiadają HTTP 429 z nagłówkiem Retry-After. Szczegóły: limity i klucze · zasady użycia.
Dane: GUS TERYT, punkty adresowe PRG (GUGiK), kody pocztowe GeoNames — przez teryt24.pl z linkiem do zasad użycia. Użycie wyłącznie po stronie serwera jest zwolnione.