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

# 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}
  }'

# 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

POST /api/v1/match/file

Prześlij plik z adresami (CSV UTF-8 lub XLSX, do 100 tys. wierszy). Otrzymasz ten sam plik z dopisanymi kolumnami: dopasowanie, TERYT, współrzędne, score.

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

Streaming (NDJSON): POST /api/v1/match/stream — wyniki lecą zanim całość się zakończy.

Inne endpointy

Kody błędów

FAQ