Localities API (SIMC)
Every self-standing locality from the SIMC register — from the capital to the smallest wieś, kolonia and osada — with no dedupe: same-named localities all come back; province/county disambiguates. Autocomplete tolerates typos (bigram Dice), and the kind (rm=, kind=urban) and TERC hierarchy filters narrow the results.
Geographic mode (lat+lon) returns localities within radiusKm, nearest first, each with its distance. The /v1/localities/{sym} detail is the full record: hierarchy, postal codes, street count, NSP 2021 population.
GET /v1/localities
Name search (q=), geographic mode (lat+lon), or browse by TERC filters without q. meta.total reports the match count before paging.
Try it live: /v1/localities?q=warsz&limit=3
| Name | Required | Description |
|---|---|---|
q | — | Search query; diacritics- and punctuation-insensitive. Optional in geographic mode (lat+lon given) or when a filter (province/county/municipality/population) is given, required otherwise. |
limit | — | Maximum results per page (1–50). |
mode | — | autocomplete = prefix-first, resolve = exact only, hybrid = combined. Ignored in geographic mode. |
rm | — | Optional rodzaj-miejscowości filter: one 2-digit RM code (01 = wieś, 96 = miasto) or a comma-separated list matching any of them (e.g. '96,95,98' — the urban units: miasto + dzielnica + delegatura). Warszawa's SIMC records carry RM 95 (dzielnica m.st. Warszawy), not 96 — use this list form or kind=urban for the urban units. |
kind | — | Semantic rodzaj preset: kind=urban selects the urban units (RM 96 miasto + 95 dzielnica m.st. Warszawy + 98 delegatura) — the reliable 'cities' filter (Warszawa's SIMC records carry RM 95, so rm=96 alone misses the capital). Mutually exclusive with rm. |
province | — | Optional 2-digit TERC voivodeship code filter (e.g. '14'), as served by /v1/regions. Makes q optional (browse mode: all matching localities in name order). |
county | — | Optional 4-digit TERC code filter (WOJ+POW, e.g. '1465'). Makes q optional (browse mode). |
municipality | — | Optional 6-digit TERC code filter (WOJ+POW+GMI, e.g. '146503'). Makes q optional (browse mode). |
minPopulation | — | Optional inhabitants lower bound (GeoNames data; unknown population is excluded). Makes q optional (browse mode). |
maxPopulation | — | Optional inhabitants upper bound (GeoNames data; unknown population is excluded). Makes q optional (browse mode). |
offset | — | Skip the first N results (0-based, max 10000) to page past the limit. |
aliases | — | Opt-in exonym fallback (aliases=true): when nothing matched by name, consult the GeoNames-derived alias table ('Danzig' finds Gdańsk). |
lat | — | WGS84 latitude (-90..90). Together with lon triggers geographic mode: localities within radiusKm, ordered nearest-first (each with distanceKm). A blank value ('?lat=') is treated as absent — it does not trigger the mode. |
lon | — | WGS84 longitude (-180..180). Must be given together with lat. |
radiusKm | — | Geographic-mode radius in kilometres (default 10, max 100). |
format | — | 'geojson' answers an RFC 7946 FeatureCollection (points in [lon,lat] order, DTO fields as properties, rows without coordinates carry geometry:null) instead of the JSON envelope. |
Example
Name autocomplete
curl "https://teryt24.pl/v1/localities?q=warsz&limit=3"Response (truncated — first rows shown):
{
"localities": [
{ "name": "Warszawa", "province": "POMORSKIE", "county": "bytowski", "municipality": "Lipnica", "id": "0746998", "type": "02", "typeLabel": "kolonia", "normalized": "warszawa", "lat": 53.98224127978727, "lon": 17.4002168965755, "coordSource": "prg", "population": null, "provinceCode": "22", "countyCode": "01", "municipalityCode": "05" },
{ "name": "Warszawa", "province": "MAZOWIECKIE", "county": "Warszawa", "municipality": "Mokotów", "id": "0918130", "type": "95", "typeLabel": "dzielnica m.st. Warszawy", "normalized": "warszawa", "lat": 52.22977, "lon": 21.01178, "coordSource": "geonames", "population": 1702139, "provinceCode": "14", "countyCode": "65", "municipalityCode": "05" }
],
"meta": { "total": 43, "offset": 0, "limit": 3 }
}| Status | Description |
|---|---|
200 | Successful response. |
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. |
503 | Service is warming up. |
GET /v1/localities/{sym}
The locality's full record; cities resolve here too (a city is an RM 96 locality).
Try it live: /v1/localities/0983988
| Name | Required | Description |
|---|---|---|
sym path | ✓ | Locality SYM (7 digits, as returned by /v1/localities). |
Example
The Dzierżoniów record
curl "https://teryt24.pl/v1/localities/0983988"Response:
{
"locality": { "name": "Dzierżoniów", "province": "DOLNOŚLĄSKIE", "county": "dzierżoniowski", "municipality": "Dzierżoniów", "id": "0983988", "type": "96", "typeLabel": "miasto", "normalized": "dzierzoniow", "lat": 50.72749999878521, "lon": 16.651111042500133, "coordSource": "prg", "population": 31866, "populationSource": "nsp2021", "provinceCode": "02", "countyCode": "02", "municipalityCode": "02" },
"postalCodes": [ { "code": "58-200", "city": "Dzierżoniów", "lat": 50.7324, "lon": 16.6477, "scope": "prg" } ],
"streetCount": 193,
"gminaStats": null
}| Status | Description |
|---|---|
200 | Successful response. |
400 | Invalid query parameters. |
404 | Unknown locality SYM. |
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. |
Browse the data
Every locality has an info page with a map, hierarchy and census data:
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.