API adresów, kodów pocztowych i TERYT

Darmowe REST API oparte na urzędowych danych PRG i TERYT. Odpowiedzi w JSON (UTF-8), CORS włączony, specyfikacja OpenAPI 3.1. Adres bazowy: https://polskieadresy.pl/api/v1.

Bez rejestracji

30 zapytań/min i 1000/dzień z adresu IP — do testów.

Z kluczem API

Darmowy plan: 5000 zapytań/mies. Klucz w nagłówku X-API-Key. Załóż konto · Cennik

Szybkość

Zwykle <1 ms po stronie serwera, zapytania wsadowe do 1000 adresów.

Szybki start

curl "https://polskieadresy.pl/api/v1/szukaj?q=Marszałkowska+10+Warszawa&limit=1"

Odpowiedź

{
  "zapytanie": "Marszałkowska 10 Warszawa",
  "wyniki": [
    {
      "typ": "adres",
      "id": 5208372,
      "id_prg": "f6e4c2c1-df6a-43bb-bcde-fdec293dfdbf",
      "adres": "ul. Marszałkowska 10/16, 00-590 Warszawa",
      "ulica": "ul. Marszałkowska",
      "numer": "10/16",
      "kod_pocztowy": "00-590",
      "poczta": "Warszawa",
      "miejscowosc": "Warszawa",
      "rodzaj_miejscowosci": "miasto",
      "dzielnica": "Śródmieście",
      "gmina": "Warszawa",
      "powiat": "Warszawa",
      "wojewodztwo": "mazowieckie",
      "teryt": {
        "simc": "0918123",
        "ulic": "12400",
        "terc": "1465011"
      },
      "ewidencja": {
        "obreb": {
          "kod": "146510_8.0511",
          "nazwa": "5-05-11"
        },
        "jednostka": {
          "kod": "146510_8",
          "nazwa": "Śródmieście"
        }
      },
      "budynek": {
        "funkcja": "budynek wielorodzinny",
        "funkcje_dodatkowe": [
          "obiekt handlowo-usługowy",
          "restauracja"
        ],
        "kategoria": "budynki mieszkalne",
        "kondygnacje": 6,
        "powierzchnia_zabudowy_m2": 1534,
        "powierzchnia_calkowita_szac_m2": 9204,
        "stan": "eksploatowany",
        "dopasowanie": "punkt adresowy wewnątrz obrysu",
        "id_bdot": "38F62225-E56A-F520-E053-CA2BA8C0BE14",
        "zrodlo": "BDOT10k (GUGiK)"
      },
      "odleglosc_do_morza_km": 263.3,
      "lat": 52.215704,
      "lon": 21.020648,
      "data_nadania": null,
      "url": "/miejscowosc/warszawa-0918123/marszalkowska/10-16/"
    }
  ]
}

Gotowy widget do formularza

Nie chcesz pisać kodu? Użyj widgetu adresowego — jedna linijka <script> dodaje podpowiadanie adresów i wypełnianie pól formularza.

Autouzupełnianie w przeglądarce (JavaScript)

const input = document.querySelector('#adres');
let ctrl;
input.addEventListener('input', async () => {
  ctrl?.abort(); ctrl = new AbortController();
  const r = await fetch('https://polskieadresy.pl/api/v1/szukaj?limit=8&q=' + encodeURIComponent(input.value), { signal: ctrl.signal });
  const { wyniki } = await r.json();
  console.log(wyniki.map(w => w.adres ?? w.nazwa));
});

Python

import requests
r = requests.get("https://polskieadresy.pl/api/v1/geokoduj", params={"q": "ul. Piotrkowska 100, Łódź"})
w = r.json()["wynik"]
print(w["kod_pocztowy"], w["lat"], w["lon"], w["teryt"]["simc"])

Normalizacja pliku (CSV/XLSX)

curl -X POST "https://polskieadresy.pl/api/v1/normalizuj/plik?format=xlsx" -H "X-API-Key: TWÓJ_KLUCZ" -F "[email protected]" -o klienci-znormalizowane.xlsx

Wersja w przeglądarce, z podglądem i wyborem kolumn: /normalizacja/.

Geokodowanie wsadowe

curl -X POST "https://polskieadresy.pl/api/v1/geokoduj" -H "Content-Type: application/json" \
  -d '{"adresy": ["Długa 5 Gdańsk", "Rynek 1, 50-106 Wrocław"]}'

Endpointy

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.

ParametrTypWymaganyOpis
qstringtakZapytanie, np. „Marszałkowska 10 Warszawa”, „00-590”, „Nowa Wieś gm. Łomianki”
limitintnie1–50, domyślnie 10
typstringnieOgranicz do: miejscowosc | ulica

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.

ParametrTypWymaganyOpis
qstringtakAdres w dowolnej postaci

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/odwrotne

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

ParametrTypWymaganyOpis
latnumbertakSzerokość geograficzna
lonnumbertakDługość geograficzna
radiusintniePromień w metrach, 1–5000, domyślnie 500
limitintnie1–50, domyślnie 1

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.

ParametrTypWymaganyOpis
miejscowoscstringtakNazwa miejscowości
ulicastringnieNazwa ulicy (pomiń dla miejscowości bez ulic)
nrstringtakNumer budynku
simcstringnieSIMC miejscowości — rozstrzyga niejednoznaczne nazwy

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.

ParametrTypWymaganyOpis
kodstringtakKod w formacie XX-XXX

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.

ParametrTypWymaganyOpis
idinttakID adresu

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.

ParametrTypWymaganyOpis
qstringtakPoczątek nazwy
limitintnie1–50

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.

ParametrTypWymaganyOpis
simcstringtak7-cyfrowy kod SIMC

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.

ParametrTypWymaganyOpis
simcstringtakSIMC miejscowości
qstringniePoczątek nazwy ulicy
limitintnie1–500, domyślnie 20

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.

ParametrTypWymaganyOpis
idinttakID ulicy (pole id z wyników)

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.

ParametrTypWymaganyOpis
kodstringtakKod TERYT

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.

ParametrTypWymaganyOpis
latnumbertak
lonnumbertak

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ół.

ParametrTypWymaganyOpis
idinttakID adresu

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.

ParametrTypWymaganyOpis
adres_idintnieID adresu
latnumbernie
lonnumbernie

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.

ParametrTypWymaganyOpis
teryt-nrstringtakKod gminy PKW i numer obwodu

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”.

ParametrTypWymaganyOpis
latnumbernie
lonnumbernie
radiusintniemetry, domyślnie 2000
simcstringnie
tercstringnie7 cyfr
typstringnie
limitintniedo 200

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.

ParametrTypWymaganyOpis
rspointtakNumer RSPO

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.

ParametrTypWymaganyOpis
adres_idintnie
latnumbernie
lonnumbernie
simcstringnie
ulica_idintnie
tercstringnie
kodstringnieXX-XXX

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).

ParametrTypWymaganyOpis
adres_idintnie
latnumbernie
lonnumbernie
simcstringnie
tercstringnie7 cyfr (gmina) lub 4 (powiat)

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.

ParametrTypWymaganyOpis
rodzajstringniebudowlane | rolne
simcstringnie
tercstringnie
adres_idintnie
latnumbernie
lonnumbernie

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.

ParametrTypWymaganyOpis
tercstringtak7-cyfrowy kod TERC

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ę.

ParametrTypWymaganyOpis
kodstringnie
rokintnie
rejestrstringnieTERC | SIMC | ULIC
limitintniedo 5000, domyślnie 200

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.

ParametrTypWymaganyOpis
formatstringniecsv | xlsx | json
kolumna_adresstringnie
kolumna_ulicastringnie
kolumna_numerstringnie
kolumna_kodstringnie
kolumna_miejscowoscstringnie

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).

ParametrTypWymaganyOpis
adres_idintnie
latnumbernie
lonnumbernie
radiusintnie100–2000 m, domyślnie 800

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}.

ParametrTypWymaganyOpis
simcstringnie
ulica_idintnie
tercstringnie

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.

ParametrTypWymaganyOpis
tercstringtakkody TERC po przecinku, np. 1261011,0264011

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ść.

ParametrTypWymaganyOpis
wskaznikstringtaknp. dochody, bezrobocie, cena_m2_mieszkania
wojstringnienp. 12 lub malopolskie
typstringniemiejskie | wiejskie | miejsko-wiejskie
kolejnoscstringniemalejaco | rosnaco
limitintniedo 3000

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.

ParametrTypWymaganyOpis
qstringtak
limitintnie

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

GET /api/v1/status

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

Przykład: /api/v1/status

Kody odpowiedzi

200OK (również gdy nic nie znaleziono — pusta lista wyniki)
400Błędne parametry — szczegóły w polu blad
404Nie znaleziono obiektu (adres, ulica, kod)
401Nieprawidłowy lub unieważniony klucz API
403Klucz ograniczony do domen użyty z innej domeny lub bez nagłówka Origin
429Przekroczono limit na minutę (nagłówek Retry-After) lub miesięczny limit planu (nagłówki X-Quota-Limit, X-Quota-Remaining)

Pola adresu

adres — sformatowany adres pocztowy; kod_pocztowy, poczta; teryt.simc, teryt.ulic, teryt.terc; lat/lon — WGS84; id_prg — identyfikator punktu w PRG (lokalnyId); url — strona adresu w serwisie.

Warunki

Dane pochodzą z PRG (GUGiK) i TERYT (GUS). Prosimy o podanie źródła: „PolskieAdresy.pl, dane PRG GUGiK, TERYT GUS”. Stan danych PRG: 2026-09-28.

💬 Pomoc B2B / WhatsApp
👨‍💻Inżynier B2B OnlineWsparcie integracji API adresów

Pomożemy wdrożyć API, dobrać plan i przygotować ofertę dla firmy.

✉️[email protected]Wyceny, plan Business, faktury 📞+48 22 100 40 80pon.–pt. 9:00–17:00