Administrative hierarchy (TERC)
Three endpoints with one shared shape: the voivodeship list (/v1/regions), a voivodeship's counties (/v1/regions/{code}/counties — miasta na prawach powiatu included) and its municipalities (/v1/regions/{code}/municipalities, optionally narrowed by county). The TERC codes plug straight into the /v1/localities filters — a cascading address select is built from that pair.
GET /v1/regions
The 16 voivodeships with TERC and NUTS codes.
Try it live: /v1/regions
Example
The voivodeship list
curl "https://teryt24.pl/v1/regions"Response (truncated — first rows shown):
{
"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 | Description |
|---|---|
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
Cities with the rights of a powiat sit in the same list (kind: powiat).
Try it live: /v1/regions/14/counties
| Name | Required | Description |
|---|---|---|
code path | ✓ | TERC code: 2 digits for a voivodeship (e.g. '14'). |
Example
Mazowieckie's counties (14)
curl "https://teryt24.pl/v1/regions/14/counties"Response (truncated — first rows shown):
{
"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 | Description |
|---|---|
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
The county parameter takes the 2-digit powiat code (the WOJ+POW tail, e.g. '65' for Warszawa).
Try it live: /v1/regions/14/municipalities?county=65
| Name | Required | Description |
|---|---|---|
code path | ✓ | TERC code: 2 digits for a voivodeship (e.g. '14'). |
county | — | Optional 2-digit TERC powiat code to narrow to one county. |
Example
Municipalities of the Warszawa county
curl "https://teryt24.pl/v1/regions/14/municipalities?county=65"Response (truncated — first rows shown):
{
"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 | Description |
|---|---|
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. |
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.