Hierarchia administracyjna (TERC)
Trzy endpointy o wspólnej odpowiedzi: lista województw (/v1/regions), powiaty jednego województwa (/v1/regions/{code}/counties — włącznie z miastami na prawach powiatu) i gminy (/v1/regions/{code}/municipalities, opcjonalnie zawężone powiatem). Kody TERC łączą się wprost z filtrami /v1/localities — kaskada selectów adresowych buduje się z tej pary.
GET /v1/regions
16 województw z kodami TERC i NUTS.
Sprawdź na żywo: /v1/regions
Przykład
Lista województw
curl "https://teryt24.pl/v1/regions"Odpowiedź (skrócona — pokazano pierwsze wiersze):
{
"regions": [
{ "code": "02", "name": "DOLNOŚLĄSKIE", "kind": "województwo", "nuts": ["PL51"] },
{ "code": "04", "name": "KUJAWSKO-POMORSKIE", "kind": "województwo", "nuts": ["PL61"] },
{ "code": "06", "name": "LUBELSKIE", "kind": "województwo", "nuts": ["PL81"] }
]
}| Status | Opis |
|---|---|
200 | Successful response. |
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. |
503 | Service is warming up. |
GET /v1/regions/{code}/counties
Miasta na prawach powiatu są w tej samej liście (kind: powiat).
Sprawdź na żywo: /v1/regions/14/counties
| Nazwa | Wymagany | Opis |
|---|---|---|
code path | ✓ | TERC code: 2 digits for a voivodeship (e.g. '14'). |
Przykład
Powiaty Mazowieckiego (14)
curl "https://teryt24.pl/v1/regions/14/counties"Odpowiedź (skrócona — pokazano pierwsze wiersze):
{
"counties": [
{ "code": "1401", "name": "białobrzeski", "kind": "powiat", "nuts": [] },
{ "code": "1402", "name": "ciechanowski", "kind": "powiat", "nuts": [] },
{ "code": "1403", "name": "garwoliński", "kind": "powiat", "nuts": [] }
]
}| Status | Opis |
|---|---|
200 | Successful response. |
400 | Invalid query parameters. |
404 | Unknown voivodeship code. |
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. |
503 | Service is warming up. |
GET /v1/regions/{code}/municipalities
Parametr county przyjmuje 2-cyfrowy kod powiatu (część WOJ+POW, np. „65” dla Warszawy).
Sprawdź na żywo: /v1/regions/14/municipalities?county=65
| Nazwa | Wymagany | Opis |
|---|---|---|
code path | ✓ | TERC code: 2 digits for a voivodeship (e.g. '14'). |
county | — | Optional 2-digit TERC powiat code to narrow to one county. |
Przykład
Gminy powiatu Warszawa
curl "https://teryt24.pl/v1/regions/14/municipalities?county=65"Odpowiedź (skrócona — pokazano pierwsze wiersze):
{
"municipalities": [
{ "code": "146501", "name": "Warszawa", "kind": "gmina miejska, miasto stołeczne", "nuts": [] },
{ "code": "146502", "name": "Bemowo", "kind": "dzielnica", "nuts": [] },
{ "code": "146503", "name": "Białołęka", "kind": "dzielnica", "nuts": [] }
]
}| Status | Opis |
|---|---|
200 | Successful response. |
400 | Invalid query parameters. |
404 | Unknown voivodeship or county code. |
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. |
503 | Service is warming up. |
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.