Miejscowości w API (SIMC)
Każda samodzielna miejscowość z rejestru SIMC — od stolicy po najmniejszą wieś, kolonię i osadę — bez deduplikacji: miejscowości o tej samej nazwie wracają wszystkie, do rozróżnienia służą województwo/powiat. Autouzupełnianie toleruje literówki (bigram Dice), a filtry rodzaju (rm=, kind=urban) i hierarchii TERC zawężają wyniki.
Tryb geograficzny (lat+lon) zwraca miejscowości w promieniu radiusKm, najpierw najbliższe, każda z odległością. Karta /v1/localities/{sym} to pełny rekord: hierarchia, kody pocztowe, liczba ulic, ludność z NSP 2021.
GET /v1/localities
Wyszukiwanie po nazwie (q=), tryb geograficzny (lat+lon) albo przeglądanie po filtrach TERC bez q. meta.total podaje liczbę trafień przed stronicowaniem.
Sprawdź na żywo: /v1/localities?q=warsz&limit=3
| Nazwa | Wymagany | Opis |
|---|---|---|
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. |
Przykład
Autouzupełnianie po nazwie
curl "https://teryt24.pl/v1/localities?q=warsz&limit=3"Odpowiedź (skrócona — pokazano pierwsze wiersze):
{
"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 | Opis |
|---|---|
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}
Pełny rekord miejscowości; miasta też rozwiązują się tutaj (miasto to miejscowość RM 96).
Sprawdź na żywo: /v1/localities/0983988
| Nazwa | Wymagany | Opis |
|---|---|---|
sym path | ✓ | Locality SYM (7 digits, as returned by /v1/localities). |
Przykład
Karta Dzierżoniowa
curl "https://teryt24.pl/v1/localities/0983988"Odpowiedź:
{
"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 | Opis |
|---|---|
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. |
Przeglądaj dane
Każda miejscowość ma stronę informacyjną z mapą, hierarchią i danymi NSP:
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.