API adresów, kodów pocztowych i TERYT

GET /api/v1/szukaj

Wyszukiwanie i autouzupełnianie adresów. Pełnotekstowe wyszukiwanie w trakcie pisania. Rozpoznaje numer budynku, kod pocztowy, skróty (ul., al.) i poprawia literówki. Zwraca adresy, ulice, miejscowości lub kody pocztowe.

Przykład: /api/v1/szukaj?q=Marszałkowska+10+Warszawa&limit=3

GET /api/v1/geokoduj

Geokodowanie i walidacja adresu. Dopasowuje „brudny” adres do rejestru PRG i zwraca najlepszy wynik z oceną pewności (score 0–1) oraz statusem: dopasowano | niska_pewnosc | czesciowe | nie_znaleziono.

Przykład: /api/v1/geokoduj?q=ul.+Piotrkowska+100,+Lodz

POST /api/v1/geokoduj

Geokodowanie wsadowe (do 1000 adresów). Body JSON: {"adresy": ["adres 1", "adres 2", …]}. Każdy adres liczy się jako jedno zapytanie w limicie.

GET /api/v1/weryfikuj-zamowienie

Weryfikacja adresu w zamówieniu sklepu (plany płatne). Dla wtyczek sklepów (WooCommerce, PrestaShop) i własnych integracji koszyka: sprawdza, czy adres wpisany przez klienta istnieje w rejestrze PRG i czy kod pocztowy jest zgodny z rejestrem. Zwraca poprawny: true | false, powod (nie_znaleziono | kod_pocztowy), gotowy komunikat dla klienta i dopasowany adres. Wymaga klucza z planu Start lub Business (dla planu Free: 402). Bez parametru ulica zwraca tylko informację o dostępności funkcji dla planu.

Przykład: /api/v1/weryfikuj-zamowienie?ulica=Marszałkowska+10/16&kod=00-590&miasto=Warszawa

GET /api/v1/odwrotne

Geokodowanie odwrotne (współrzędne → adres). Najbliższe punkty adresowe do podanych współrzędnych WGS84 wraz z odległością w metrach.

Przykład: /api/v1/odwrotne?lat=52.2297&lon=21.0122&limit=3

GET /api/v1/kod-dla-adresu

Kod pocztowy dla adresu. Zwraca kod pocztowy dla dokładnego adresu podanego w polach.

Przykład: /api/v1/kod-dla-adresu?miejscowosc=Kraków&ulica=Rynek+Główny&nr=1

GET /api/v1/kod-pocztowy/{kod}

Ulice i miejscowości dla kodu pocztowego. Miejscowości, ulice i zakresy numerów przypisane do kodu pocztowego.

Przykład: /api/v1/kod-pocztowy/00-590

GET /api/v1/adres/{id}

Szczegóły adresu. Pełne dane adresu po identyfikatorze serwisu. Alternatywnie /api/v1/adres?prg={uuid} — po identyfikatorze PRG.

Przykład: /api/v1/adres/1

GET /api/v1/miejscowosci

Autouzupełnianie miejscowości. Miejscowości pasujące do prefiksu nazwy, posortowane wg wielkości.

Przykład: /api/v1/miejscowosci?q=nowa+wies&limit=5

GET /api/v1/miejscowosc/{simc}

Miejscowość wg SIMC. Dane miejscowości z kodami pocztowymi, ludnością i odnośnikami do Wikidata.

Przykład: /api/v1/miejscowosc/0950463

GET /api/v1/ulice

Autouzupełnianie ulic w miejscowości. Ulice danej miejscowości pasujące do prefiksu nazwy.

Przykład: /api/v1/ulice?simc=0918123&q=marsz

GET /api/v1/ulica/{id}

Ulica z listą adresów. Wszystkie numery budynków ulicy z kodami pocztowymi i współrzędnymi.

GET /api/v1/teryt/{kod}

Dekodowanie kodu TERYT. Rozpoznaje: 2 cyfry — województwo, 4 — powiat, 7 cyfr — SIMC miejscowości lub TERC gminy, SIMC+ULIC (12 cyfr) — ulica.

Przykład: /api/v1/teryt/1261011

GET /api/v1/dzialka

Działka ewidencyjna w punkcie. Identyfikator działki ewidencyjnej (ULDK GUGiK) dla współrzędnych.

Przykład: /api/v1/dzialka?lat=52.2297&lon=21.0122

GET /api/v1/adres/{id}?pelne=1

Adres z obwodem wyborczym, cenami mieszkań i szkołami. Jak /adres/{id}, plus obwód głosowania i okręgi, mediany cen mieszkań (budynek, ulica, miejscowość, gmina) i 5 najbliższych szkół.

Przykład: /api/v1/adres/1?pelne=1

GET /api/v1/wybory

Obwód głosowania i okręgi wyborcze dla adresu. Lokal wyborczy (obwód PKW, wybory 2025) oraz okręg do Sejmu i Senatu (2023). Adres przez adres_id albo współrzędne.

Przykład: /api/v1/wybory?lat=52.2297&lon=21.0122

GET /api/v1/obwod-glosowania/{teryt-nr}

Obwód głosowania. Siedziba komisji i opis granic obwodu, np. 146510-38.

Przykład: /api/v1/obwod-glosowania/020101-1

GET /api/v1/szkoly

Szkoły i przedszkola. Placówki w pobliżu punktu (z odległością), w miejscowości (simc) lub gminie (terc). Filtr typ, np. „przedszkole”, „podstawowa”, „liceum”.

Przykład: /api/v1/szkoly?lat=50.0617&lon=19.9373&typ=podstawowa&limit=5

GET /api/v1/szkola/{rspo}

Szkoła wg numeru RSPO. Adres, typ, liczba uczniów, oddziałów i nauczycieli, organ prowadzący, położenie.

GET /api/v1/ceny/mieszkania

Ceny transakcyjne mieszkań. Mediana i kwartyle zł/m², liczba transakcji i trend półroczny z Rejestru Cen Nieruchomości (ostatnie 24 miesiące, min. 5 transakcji). Dla adresu (adres_id lub lat/lon — zwraca budynek, ulicę, miejscowość, gminę) albo dla simc, ulica_id, terc, kod.

Przykład: /api/v1/ceny/mieszkania?simc=0950463

GET /api/v1/ceny/domy

Ceny transakcyjne domów. Mediana ceny domu (grunt zabudowany budynkiem mieszkalnym) oraz zł/m² powierzchni użytkowej; dla adresu (adres_id, lat/lon), miejscowości (simc), gminy lub powiatu (terc).

Przykład: /api/v1/ceny/domy?terc=1465011

GET /api/v1/ceny/dzialki

Ceny transakcyjne działek. Mediana zł/m² działek niezabudowanych: budowlanych (domyślnie) lub rolnych i leśnych (rodzaj=rolne). Parametry jak w /ceny/domy.

Przykład: /api/v1/ceny/dzialki?terc=1206

GET /api/v1/gmina/{terc}

Gmina: statystyki GUS i ceny. Ludność, powierzchnia, gęstość, struktura wieku, migracje, przyrost naturalny, bezrobocie, dochody na mieszkańca, mieszkania, podmioty REGON (GUS BDL) oraz mediany cen mieszkań, domów i działek.

Przykład: /api/v1/gmina/1261011

GET /api/v1/teryt/zmiany

Historia zmian TERYT. Zmiany w rejestrze TERYT od 1999 r. (GUS): nowe i zniesione jednostki, zmiany nazw i rodzajów miejscowości, ulice. Filtry: kod (SIMC/TERC/SIMC+ULIC — zmiany danego obiektu, także jako następcy), rok, rejestr. Także /api/v1/teryt/{kod}/zmiany. Dla kodu usuniętego z rejestru /api/v1/teryt/{kod} zwraca następcę.

Przykład: /api/v1/teryt/zmiany?rok=2025&rejestr=TERC

POST /api/v1/normalizuj/plik

Normalizacja pliku CSV/XLSX. Prześlij plik (multipart, pole "plik") lub surowy CSV w body. Kolumny rozpoznawane automatycznie albo wskazane parametrami kolumna_adres / kolumna_ulica, kolumna_numer, kolumna_kod, kolumna_miejscowosc (nazwa lub numer kolumny od 1). Zwraca plik (format=csv|xlsx) albo JSON (format=json) z dodanymi kolumnami: status, pewność, adres znormalizowany, kod, TERYT, współrzędne. Każdy wiersz liczy się jako zapytanie; bez klucza do 200 wierszy.

GET /api/v1/komunikacja

Komunikacja publiczna przy adresie. Najbliższe przystanki (zgrupowane perony) z liniami, liczbą odjazdów w dzień roboczy i godzinami pierwszego/ostatniego odjazdu, odległość do przystanku i stacji kolejowej oraz ocena dostępności komunikacyjnej. Rozkłady GTFS miast i kolei; w innych miejscowościach przystanki z BDOT10k (bez rozkładu).

Przykład: /api/v1/komunikacja?lat=50.0617&lon=19.9373

GET /api/v1/zabudowa

Struktura zabudowy. Udział adresów w budynkach jednorodzinnych, wielorodzinnych i innych, średnia i maksymalna liczba kondygnacji, budynki w budowie — dla ulicy, miejscowości lub gminy (BDOT10k). Dla pojedynczego adresu pole budynek jest w /api/v1/adres/{id}.

Przykład: /api/v1/zabudowa?simc=0950463

GET /api/v1/porownaj

Porównanie gmin. Pełne metryki dla wielu gmin naraz (do 10): ludność, demografia, bezrobocie, dochody, REGON, mieszkania, nowe adresy wg lat, ceny mieszkań/domów/działek, szkoły, adresy, odległość do morza.

Przykład: /api/v1/porownaj?terc=1261011,0264011

GET /api/v1/rankingi/gminy/{wskaznik}

Ranking gmin. Gminy uszeregowane wg wskaźnika (lista: /api/v1/rankingi/gminy). Filtry: województwo (kod 2-cyfrowy lub nazwa), rodzaj gminy, kolejność.

Przykład: /api/v1/rankingi/gminy/dochody?woj=malopolskie&limit=10

GET /api/v1/gminy

Wyszukiwanie gmin. Autouzupełnianie nazw gmin (całych gmin, z kodem TERC) — np. do porównywarki.

Przykład: /api/v1/gminy?q=nowy

GET /api/v1/okolica

Co jest w okolicy. Najbliższe sklepy spożywcze, apteki, paczkomaty, przychodnie, poczty, bankomaty, stacje paliw i szpitale (OpenStreetMap) z odległościami, liczba punktów w promieniu 1 km, najbliższe szkoły i przystanki.

Przykład: /api/v1/okolica?lat=52.2297&lon=21.0122

GET /api/v1/poi

Punkty zainteresowania (POI) w promieniu. Lista punktów OpenStreetMap (sklepy, apteki, paczkomaty, przychodnie, poczty, bankomaty, stacje paliw, szpitale) w zadanym promieniu od punktu — bez ograniczenia do kilku najbliższych na kategorię jak w /okolica; do analiz i mapowania.

Przykład: /api/v1/poi?lat=52.2297&lon=21.0122&radius=1500&kategoria=apteka

GET /api/v1/granice/{kod}

Granice administracyjne (GeoJSON). Geometria granic województwa, powiatu lub gminy jako obiekt GeoJSON Feature (Polygon/MultiPolygon, WGS84). Poziom rozpoznawany z długości kodu TERYT: 2 znaki — województwo, 4 — powiat, 7 — gmina.

Przykład: /api/v1/granice/1465011

GET /api/v1/izochrona

Izochrona — obszar dojazdu w X minut. Obszar osiągalny z punktu w zadanym czasie, liczony po rzeczywistej sieci dróg (Valhalla, OpenStreetMap). GeoJSON FeatureCollection z jednym Polygonem na każdą wartość czasu. Do wyznaczania stref dostaw, obszarów obsługi, analiz dostępności.

Przykład: /api/v1/izochrona?lat=52.2297&lon=21.0122&minuty=10,20&transport=auto

GET /api/v1/adresy-w-zasiegu

Adresy w zasięgu dojazdu. Wszystkie punkty adresowe PRG leżące wewnątrz izochrony: łączna liczba, podsumowanie wg miejscowości i kodów pocztowych oraz lista najbliższych adresów (do 1000). Z obszar=1 zwraca też sam poligon. Gotowa lista adresów obsługiwanych przez punkt dostaw/oddział w zadanym czasie dojazdu.

Przykład: /api/v1/adresy-w-zasiegu?lat=52.2297&lon=21.0122&minuty=10&transport=pieszo

GET /api/v1/firma

Weryfikacja kontrahenta: status VAT, rachunki, REGON, CEIDG. Plany płatne (Start, Business; plan Free: 402). Łączy białą listę podatników VAT (Ministerstwo Finansów: status VAT, rachunki bankowe, adres, reprezentanci) z danymi podstawowymi z rejestru REGON (GUS BIR1.1: nazwa, adres, data zakończenia działalności) oraz, dla NIP lub REGON, z wpisem w CEIDG (jednoosobowe działalności; pole pomijane, gdy serwer nie ma tokenu). Z parametrem rachunek dodaje weryfikację pary NIP + rachunek w wykazie podatników VAT (plik płaski MF, także rachunki wirtualne). Zapytanie na żywo, wynik buforowany dobę; koszt 5 jednostek planu. Wyszukiwanie po REGON/KRS działa tylko w rejestrze GUS (biała lista przyjmuje tylko NIP).

Przykład: /api/v1/firma?nip=1132775939

GET /api/v1/firma/krs/{numer}

Odpis aktualny z KRS. Pełny odpis aktualny z Krajowego Rejestru Sądowego (Ministerstwo Sprawiedliwości): dane podmiotu, organy, wspólnicy, przedmiot działalności. Zapytanie na żywo, wynik buforowany do godziny.

Przykład: /api/v1/firma/krs/335412

GET /api/v1/firma/ceidg/lista

Lista przedsiębiorców z CEIDG wg lokalizacji. Plany płatne. Aktywne jednoosobowe działalności z CEIDG dla gminy, powiatu, miasta lub kodu pocztowego (strona po stronie, do 25 na stronę (limit CEIDG)). Zwraca id wpisu, nazwę działalności, adres działalności, NIP, REGON, status i datę rozpoczęcia — bez imion i nazwisk właścicieli. Do katalogów lokalnych firm; szczegóły i PKD w /api/v1/firma/ceidg/{id}. Wynik buforowany dobę; koszt 5 jednostek planu; limity CEIDG są wspólne dla wszystkich klientów.

Przykład: /api/v1/firma/ceidg/lista?gmina=Bia%C5%82a%20Piska&powiat=piski&limit=25

GET /api/v1/firma/ceidg/{id}

Szczegóły wpisu CEIDG (PKD). Plany płatne. Szczegóły działalności z CEIDG po identyfikatorze wpisu (z /api/v1/firma/ceidg/lista): główny kod PKD i pozostałe PKD, status, daty rozpoczęcia, zawieszenia i zakończenia. Wynik buforowany dobę; koszt 5 jednostek planu.

Przykład: /api/v1/firma/ceidg/CCD08AF8-0FA2-4FF4-A251-8C077B4FDB19

GET /api/v1/firma/rachunek

Czy rachunek należy do podatnika VAT. Plany płatne. Sprawdza, czy para NIP + numer rachunku (NRB, 26 cyfr) występuje w wykazie podatników VAT na dany dzień — z dziennego pliku płaskiego Ministerstwa Finansów, lokalnie, bez limitów rejestru (także rachunki wirtualne przez maski banków). Zwraca zgodny: true | false, status_vat (czynny | zwolniony), rachunek_wirtualny i datę wykazu. Do sprawdzenia przelewu przed wysłaniem (split payment, odpowiedzialność solidarna). Koszt 1 jednostki planu.

Przykład: /api/v1/firma/rachunek?nip=1132775939&rachunek=19102010260000140201913912

GET /api/v1/zagrozenia

Zagrożenia i środowisko. Strefy zagrożenia powodziowego z map ISOK (Wody Polskie; scenariusze Q10%, Q1%, Q0,2%, zniszczenie wału), bieżący indeks jakości powietrza najbliższej stacji GIOŚ oraz szacunek narażenia na hałas komunikacyjny wg odległości od autostrad, dróg ekspresowych, kolei i lotnisk. Powódź i powietrze pobierane na żywo (do kilku sekund).

Przykład: /api/v1/zagrozenia?lat=50.677&lon=21.756

POST /api/v1/monitoring/adresy

Monitoring zmian adresów. Wymaga klucza API przypisanego do konta. POST {"adresy": ["…"] lub [{"ref","adres"}]} dodaje adresy do monitoringu (geokodowanie liczy się do limitu); GET /api/v1/monitoring/adresy — lista; DELETE /api/v1/monitoring/adresy/{ref} — usunięcie; GET /api/v1/monitoring/zmiany?od=RRRR-MM-DD — wykryte zmiany (kod pocztowy, ulica, miejscowość, gmina, TERYT, usunięcie); GET/PUT /api/v1/monitoring/ustawienia {"webhook","email"} — powiadomienia (podpis X-PolskieAdresy-Signature: sha256=HMAC).

POST /mcp

Serwer MCP dla asystentów AI. Model Context Protocol (Streamable HTTP, JSON-RPC): narzędzia szukaj_adresu, geokoduj, odwrotne_geokodowanie, kod_pocztowy, kod_dla_adresu, szczegoly_adresu, teryt, okolica. Klucz opcjonalny: Authorization: Bearer pa_… lub X-API-Key. Konfiguracja dla Claude, ChatGPT i Cursor: /integracje/#mcp.

GET /api/v1/status

Stan danych. Data danych PRG i TERYT oraz liczby rekordów.

Przykład: /api/v1/status