Polskie dane adresowe w jednym REST API
Miasta, miejscowości, ulice, kody pocztowe i walidacja adresów — prosto z rejestrów GUS TERYT, ULIC i PRG. Jedno zapytanie HTTP, odpowiedź w JSON, gotowe do podpięcia w formularzach i mapach.
Klucz jest opcjonalny — API działa bez niego. Daje integracji własny limit zamiast współdzielonego 60/min na IP.
Rozmiary w pasku to liczby wierszy w rejestrach. Strona to jeden obiekt, a wiersz nie zawsze: w ULIC wiersz oznacza jedną parę miejscowość–ulica, w PNA — jedną parę kod–miejscowość.
Stan rejestrów: SIMC 12.06.2026 · TERC 12.06.2026 · ULIC 04.11.2026 · PNA 04.11.2026 · /v1/datasets
Przeglądaj dane
Każda miejscowość, ulica, kod pocztowy i województwo mają swoją stronę — od stolicy po najmniejszą wieś. Zacznij od jednego z pięciu wejść:
Przeglądaj według województwa
Przykładowe strony
Co znajduje się w API
Wszystkie endpointy zwracają JSON, obsługują CORS i są objęte wspólną dokumentacją OpenAPI.
Autouzupełnianie miejscowości
Każda samodzielna miejscowość — od stolicy po najmniejszą wieś — z dopasowaniem tolerującym literówki (bigram Dice), koordynatami WGS84 i trybami autocomplete / resolve / hybrid. Rodzaj zawęża prostym kind=urban (jednostki miejskie) albo listą rm=96,95,98; opcjonalna warstwa egzonimów (aliases=true) dokłada nazwy z GeoNames.
/v1/localities?q=warsz&limit=5
dokumentacja →
Walidacja adresów — trzy tryby
Rejestr PRG (≈ 8,6 mln punktów adresowych). Polami — sym + number, ulica opcjonalnie. Wg nazwy — locality, zawężane kodem postalCode, gdy nazwa jest niejednoznaczna. Albo jednym ciągiem — address: odpowiedź donosi pars w query, a przy nieznanym numerze sugeruje sąsiednie.
/v1/geocode?address=Warszawa,%20ul.%20Anilinowa%202
dokumentacja →
Walidacja adresu z oceną pewności
Rejestr PRG (≈ 8,6 mln punktów adresowych). Jedno zapytanie zwraca rozłożony adres — miejscowość, ulicę, numer, kod pocztowy, współrzędne — plus ocenę dopasowania każdego pola (exact / normalized / partial / ambiguous / not-found), werdykt (valid / corrected / ambiguous / incomplete / invalid) i listę rozbieżności do rozstrzygnięcia. Kod pocztowy to zawsze kod dopasowanego punktu adresowego — nigdy domysł.
/v1/validate?address=…
dokumentacja →
Gotowy widget formularza
Cały ten workflow w jednym pliku bez zależności: podpowiedzi miejscowości i ulic, walidacja, przegląd wyniku z werdyktem i listą rozbieżności. Etykiety konfigurowalne, gotowy do podpięcia pod własny formularz.
/assets/address-widget.js ·
/assets/address-widget.css
demo →
Jedno pole — cały katalog
Autouzupełnianie miast, miejscowości, ulic i kodów w jednym zapytaniu — z opcjonalnym punktem odniesienia.
/v1/autosuggest?q=warsz
dokumentacja →
Wszystkie miejscowości
Każda samodzielna miejscowość z SIMC — wsie, kolonie, osady — z filtrami rodzaju (RM) i hierarchii TERC, trybem geograficznym, stronicowaniem i kartą szczegółów miejscowości.
/v1/localities?q=kolonia&lat=52.2&lon=21.0
dokumentacja →
Ulice w miejscowości
Szukaj ulicy w obrębie miejscowości (SYM) w rejestrze ULIC; wyniki rankingują wg ważności (populacja, punkty adresowe). Karta ulicy (/v1/streets/{symUl}, np. /v1/streets/12400) zbiera wszystkie jej wystąpienia i agregaty PRG — np. ul. Marszałkowska.
/v1/streets?city=0983988&q=marsza
dokumentacja →
Kody pocztowe
Kod pocztowy → miejscowość (PNA, z koordynatami) albo odwrotnie: lista kodów dla miejscowości na karcie /v1/localities/:sym — np. /v1/localities/0983988.
/v1/postal-codes?q=00-002
dokumentacja →
Statystyki
Polska w liczbach: rejestr adresowy policzony do budynku — punkty adresowe PRG, miejscowości, ulice i kody pocztowe w podziale na 16 województw, z podaniem źródła i daty każdej liczby.
/wojewodztwa/14
Hierarchia administracyjna i numer kierunkowy
Województwa → powiaty → gminy (TERC) — idealne do kaskadowych selectów adresowych — oraz numer kierunkowy gminy ze stref numeracyjnych UKE, definiowanych per gmina, a nie per powiat.
/v1/regions →
/v1/regions/14/counties →
/v1/regions/14/municipalities ·
/v1/area-codes/302116
dokumentacja →
Granice administracyjne w GeoJSON
380 powiatów i 16 województw jako RFC 7946 w WGS84, kluczowanych kodem TERC — z punktem etykietowania każdego kształtu i wspólną granicą sąsiadów bez rys. Filtr ?province= zawęża zbiór do jednego województwa; demo pokazuje choropleth zbudowany na tym samym endpointcie.
/v1/boundaries/counties?province=14
dokumentacja →
Odwrócone geokodowanie
Najbliższe miejsca dla współrzędnych — dokładny punkt adresowy z PRG (ulica, kod), a gdy sięga poza sieć — najbliższe miejscowości z odległością w kilometrach.
/v1/reverse-geocode?lat=52.23&lon=21.01
dokumentacja →
GeoJSON na wyjściu
format=geojson zwraca RFC 7946 FeatureCollection (localities, cities, postal-codes, geocode, reverse-geocode) — geometrie od razu do Leaflet albo MapLibre.
/v1/localities?q=warsz&format=geojson
Wsadowe operacje
50 adresów albo 100 kodów pocztowych na jedno żądanie — czyszczenie danych bez festiwalu round-tripów.
POST /v1/geocode/batch ·
POST /v1/postal-codes/bulk
Masowa normalizacja z CSV
Wgraj plik, nazwij kolumny, odbierz plik wynikowy: oryginalne kolumny bez zmian plus potwierdzony adres, ocena dopasowania i powody, dla których wiersze nie zostały potwierdzone. Wymaga klucza API (plany i limity), a wgrany plik jest usuwany po 24 godzinach.
POST /v1/bulk/addresses
Feed zmian rejestru
GUS publikuje „pliki aktualizacyjne” — różnice między stanami katalogu. Feed podaje je jako zmiany: co się dodało, zmieniło, przeniosło, przemianowało i zniknęło, z datą stanu katalogu. Likwidacja to fakt rejestru, nie informacja o poprawności adresu.
/v1/changes?dataset=simc
dokumentacja →
Cache, ETag i meta.total
Udane GET-y są cache'owane (Cache-Control: 1 dzień) i wersjonowane ETagiem — 304 oszczędza transfer. Wyszukiwania zwracają meta.total: pełną liczbę trafień przed stronicowaniem. Co serwer widzi o Twoich zapytaniach: /v1/whoami; zużycie klucza: /v1/usage.
ETag + If-None-Match
Dane w przeglądarce
Strona informacyjna dla każdej miejscowości i kodu pocztowego: hierarchia TERC, ludność (NSP 2021), często statystyki gminy z BDL i mapa położenia. Np. Warszawa, Dzierżoniów czy kod 00-002.
/miasta/warszawa
Quick start
Bez kluczy i rejestracji — pierwsze zapytanie w 10 sekund.
curl "https://teryt24.pl/v1/localities?q=warsz&limit=5"
curl "https://teryt24.pl/v1/geocode?address=Warszawa,%20ul.%20Anilinowa%202"
curl "https://teryt24.pl/v1/reverse-geocode?lat=52.2297&lon=21.0122&limit=3"
Pełna lista parametrów i schematy odpowiedzi w dokumentacji
oraz maszynowcu openapi.json. Limity: 60 zapytań/min na IP,
po przekroczeniu HTTP 429 z nagłówkiem Retry-After. To, co serwer
widzi o Twoich zapytaniach, pokaże /v1/whoami,
a klucz API może sprawdzić własne zużycie przez /v1/usage.
Chcesz krok po kroku? Przewodnik integracji prowadzi od autouzupełniania formularza do map GeoJSON — curl, Python i JavaScript.
Klucze API i limity
X-API-Key i raport zużycia:
dokumentacja limitów i kluczy. Zasady użycia i atrybucja danych:
zasady użycia.