API.adresy.app

Quickstart — pierwszy request w 30 sekund

Endpointy: https://api.adresy.app/api/v1. Odpowiedzi JSON (UTF-8). GET dla odczytu, POST dla batch.

curl -s "https://api.adresy.app/api/v1/match?q=Rynek+1,+Wrocław&api_key=TWOJ_KLUCZ"

Odpowiedź:

{
  "results": [
    {
      "input": "Rynek 1, Wrocław",
      "status": "found",
      "match": {
        "miejscowosc": "Wrocław",
        "ulica_norm": "Rynek",
        "nr_budynku": "1",
        "kod_pocztowy": "50-106",
        "teryt_simc": "0986283",
        "teryt_ulic": "19357",
        "gmina": "Wrocław",
        "powiat": "Wrocław",
        "wojewodztwo": "DOLNOŚLĄSKIE",
        "lat": 51.10893,
        "lon": 17.03262,
        "score": 0.98,
        "match_layer": "EXACT"
      }
    }
  ]
}

GET /match?q= to najprostszy sposób — podaj dowolny adres jako tekst, otrzymasz dopasowanie z rejestru PRG z kodem pocztowym, TERYT i współrzędnymi.

Uwierzytelnianie i limity

curl -s "https://api.adresy.app/api/v1/lookup/kod-pocztowy?kod=00-001" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx"

Alternatywnie: &api_key=TWOJ_KLUCZ jako query param — wygodne do testów w przeglądarce:

https://api.adresy.app/api/v1/match?q=Rynek+1,+Wrocław&api_key=sk_live_xxx

1. Wyszukiwanie po kodzie pocztowym

GET /api/v1/lookup/kod-pocztowy

Zwraca ulice i numery przypisane do kodu pocztowego. Dane z PRG (GUGiK).

total i ulic to sumy dla całego kodu (nie tylko zwróconej strony); zwrocono mówi, ile grup zmieściło się w limicie, a obciete:true sygnalizuje przyciętą listę. Kod nieobecny w PRG (np. skrytki pocztowe 00-950) zwraca found:false.

# curl
curl -s "https://api.adresy.app/api/v1/lookup/kod-pocztowy?kod=50-079"

# Python
import httpx
r = httpx.get("https://api.adresy.app/api/v1/lookup/kod-pocztowy",
    params={"kod": "50-079"}, headers={"Authorization": "Bearer sk_live_xxx"})
data = r.json()

// JavaScript
const res = await fetch("https://api.adresy.app/api/v1/lookup/kod-pocztowy?kod=50-079",
  { headers: { "Authorization": "Bearer sk_live_xxx" } });
const data = await res.json();

2. Kod pocztowy dla adresu

GET /api/v1/lookup/kod-dla-adresu

Podaj miejscowość, ulicę i numer — otrzymasz kod pocztowy. Idealne do walidacji formularzy.

curl -s "https://api.adresy.app/api/v1/lookup/kod-dla-adresu" \
  --data-urlencode "miejscowosc=Wrocław" \
  --data-urlencode "ulica=Rynek" \
  --data-urlencode "nr=1" -G

{
  "found": true,
  "kod_pocztowy": "50-106",
  "miejscowosc": "Wrocław",
  "ulica": "Rynek",
  "nr": "1",
  "teryt_simc": "0986283",
  "teryt_ulic": "19357"
}

3. TERYT — SIMC i ULIC

GET /api/v1/lookup/teryt

Kody TERYT (SIMC/ULIC) z przynależnością administracyjną. Wyszukiwanie po nazwie lub kodzie SIMC.

curl -s "https://api.adresy.app/api/v1/lookup/teryt" \
  --data-urlencode "miejscowosc=Kraków" \
  --data-urlencode "ulica=Floriańska" -G

{
  "found": true,
  "results": [{
    "simc": "0950463",
    "nazwa": "Kraków",
    "typ": "miasto",
    "gmina": "Kraków",
    "powiat": "Kraków",
    "wojewodztwo": "małopolskie",
    "ulice": [{"ulic": "05123", "cecha": "ul.", "nazwa_1": "Floriańska"}]
  }]
}

4. Dekoduj TERYT — pełna hierarchia adresowa

GET /api/v1/teryt/decode

Zamienia kody TERYT na pełną hierarchię adresową: województwo → powiat → gmina → miejscowość → dzielnica → ulica → numer. Obsługuje trzy formaty wejścia:

• SIMC (7 cyfr) — kod miejscowości: 0986283 → Wrocław
• ULIC (5 cyfr) — kod ulicy: 19357 → Rynek (Wrocław)
• SIMC#ULIC#NR — pełny adres punktowy: 0986283#19357#1

# Miejscowość (SIMC)
curl -s "https://api.adresy.app/api/v1/teryt/decode?simc=0986283"

# Ulica (ULIC)
curl -s "https://api.adresy.app/api/v1/teryt/decode?ulic=19357"

# Pełny adres (SIMC#ULIC#NR)
curl -s "https://api.adresy.app/api/v1/teryt/decode?simc=0986283%2319357%231"

{
  "found": true,
  "typ": "adres",
  "wojewodztwo": "DOLNOŚLĄSKIE",
  "powiat": "Wrocław",
  "gmina": "Wrocław",
  "miejscowosc": "Wrocław",
  "teryt_simc": "0986283",
  "dzielnica": "Stare Miasto",
  "teryt_simc_dzielnica": "0986544",
  "ulica": "Rynek",
  "teryt_ulic": "19357",
  "nr_budynku": "1",
  "kod_pocztowy": "50-106",
  "lat": 51.10893,
  "lon": 17.03262
}

5. Adresy po współrzędnych (geokodowanie odwrotne)

GET /api/v1/lookup/blisko

Najbliższe punkty adresowe dla współrzędnych WGS84. PostGIS + indeks GiST.

curl -s "https://api.adresy.app/api/v1/lookup/blisko?lat=51.1089&lon=17.0326&radius=200&limit=5"

{
  "found": true,
  "count": 5,
  "results": [{
    "miejscowosc": "Wrocław",
    "ulica": "Rynek",
    "nr_budynku": "1",
    "kod_pocztowy": "50-106",
    "distance_m": 12.4,
    "lat": 51.10893,
    "lon": 17.03262
  }]
}

6. Szybkie dopasowanie — GET /match?q=

GET /api/v1/match?q=...

Najprostszy endpoint — podaj adres jako tekst, otrzymasz dopasowanie z PRG z pełnym TERYT, kodem pocztowym i współrzędnymi. Obsługuje literówki, skróty, brak kodu.

curl -s "https://api.adresy.app/api/v1/match?q=Marszalkowska+1+Warszawa"

# Python
import httpx
r = httpx.get("https://api.adresy.app/api/v1/match",
    params={"q": "Marszałkowska 1 Warszawa"},
    headers={"Authorization": "Bearer sk_live_xxx"})
print(r.json()["results"][0]["match"]["kod_pocztowy"])

// JavaScript
const res = await fetch(
  "https://api.adresy.app/api/v1/match?q=" + encodeURIComponent("Rynek 1, Wrocław"),
  { headers: { "Authorization": "Bearer sk_live_xxx" } }
);
const { results } = await res.json();
console.log(results[0].match.kod_pocztowy);

7. Dopasowywanie adresów — POST /match

POST /api/v1/match

Najmocniejszy endpoint. Bierze „brudny" adres (literówki, skróty, bez kodu) i dopasowuje do rekordu PRG z pełnym TERYT, kodem pocztowym i współrzędnymi. Fuzzy-match (RapidFuzz) + heurystyki polskich skrótów.

curl -s -X POST "https://api.adresy.app/api/v1/match" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_xxx" \
  -d '{
    "addresses": ["ul. Marsz Pilsudskiego 5a, Wroclaw"],
    "context": {"wojewodztwo": "dolnośląskie"},
    "options": {"fuzzy_threshold": 82, "max_candidates": 5}
  }'

Zamiast addresses możesz podać structured — listę adresów rozbitych na pola (street, building_number, city, postal_code, prefix) — gdy dane już są w kolumnach, parser tekstu nie ma czego psuć. context zawęża wyszukiwanie (miejscowosc, gmina, wojewodztwo, kod_pocztowy), a options.priority (ADDRESS/TERYT/COORDS) steruje kolejnością interpretacji wejścia.

# Python
import httpx
r = httpx.post("https://api.adresy.app/api/v1/match",
    json={"addresses": ["Kościuszki 14 Kraków"]},
    headers={"Authorization": "Bearer sk_live_xxx"})
data = r.json()

// JavaScript
const res = await fetch("https://api.adresy.app/api/v1/match", {
  method: "POST",
  headers: {"Content-Type": "application/json", "Authorization": "Bearer sk_live_xxx"},
  body: JSON.stringify({addresses: ["Kościuszki 14 Kraków"]})
});
const data = await res.json();

8. Walidacja pliku CSV/XLSX (batch)

POST /api/v1/match/file

Prześlij plik z adresami (CSV, XLSX, TXT lub JSON — kodowanie UTF-8 lub ANSI/windows-1250, wykrywane automatycznie). Endpoint tworzy job i zwraca natychmiast {job_id, status, row_count}; wyniki odbierasz z endpointów joba poniżej. Wynik to Twój plik z dopisanymi kolumnami: status, TERYT, kod pocztowy, współrzędne, score, AID.

curl -s -X POST "https://api.adresy.app/api/v1/match/file" \
  -H "Authorization: Bearer sk_live_xxx" \
  -F "[email protected]"

Trzy tryby dopasowania (match_mode):

# tryb twardy po kodach TERYT
curl -s -X POST "https://api.adresy.app/api/v1/match/file" \
  -H "Authorization: Bearer sk_live_xxx" \
  -F "[email protected]" -F "match_mode=teryt" \
  -F "simc_column=kod_simc" -F "number_column=nr" -F "ulic_column=kod_ulic"

Odbiór wyników i cykl życia joba:

Przetwarzanie różnicowe: podaj parent_job_id — wiersze identyczne z poprzednim jobem dostają wynik z cache, liczysz tylko nowe i zmienione. Webhook (plan Business): callback_url — POST z podsumowaniem po zakończeniu. send_email=true — powiadomienie mailowe. Tryb synchroniczny (mały plik, wynik od razu w odpowiedzi): POST /match/file/download. Streaming (NDJSON): POST /api/v1/match/stream — wyniki lecą zanim całość się zakończy.

9. Autouzupełnianie — miejscowości, ulice, numery

GET /api/v1/miejscowosci · /api/v1/ulice · /api/v1/numery

Podpowiedzi do formularzy checkout i wtyczek e-commerce (od planu Mini). Kaskada: miejscowość → ulica w niej → numery na ulicy.

curl -s "https://api.adresy.app/api/v1/miejscowosci?q=wro&api_key=sk_live_xxx"
curl -s "https://api.adresy.app/api/v1/ulice?miejscowosc=Wrocław&q=ryn&api_key=sk_live_xxx"
curl -s "https://api.adresy.app/api/v1/numery?miejscowosc=Wrocław&ulica=Rynek&api_key=sk_live_xxx"

Po wybraniu adresu GET /api/v1/lookup/autofill dopełnia kod pocztowy, TERYT i współrzędne — jedno zapytanie zamiast walidacji całego formularza.

Inne endpointy

Kody błędów

FAQ