API-dokumentáció

Röviden

Az Adatka API a https://adatka.hu webcímen, HTTPS-en érhető el, és JSON-formátumban, UTF-8 kódolással válaszol.

A /suggest, a /reverse és a /clean egységes címobjektumot ad vissza: a cím részeit, a közigazgatási adatokat, a koordinátát, a találati szintet és a felhasznált forrásokat.

A szolgáltatás jelenleg meghívásos, díjmentes bétaüzemben érhető el.

Gyors kezdés

A parancsok Linux- és macOS-terminálhoz készültek (bash, zsh). API-kulcsot az oldal alján, a „Hozzáférés” résznél kérhet. A bétaüzemben a szolgáltatás egyelőre kulcs nélkül is válaszol: ha még nincs kulcsa, hagyja ki a kulcs megadását — a parancsok így is futnak (részletek: API-kulcs).

Ha van kulcsa, először adja meg: illessze be az alábbi sort, és nyomja meg az Entert; a „Kulcs:” felirat után illessze be a kulcsot, és ismét nyomja meg az Entert. A beírt kulcs nem jelenik meg a képernyőn.

printf "Kulcs: "; read -rs ADATKA_KEY; export ADATKA_KEY; echo

Az első kéréssel három javaslatot kap a beírt szövegre:

curl -sG https://adatka.hu/suggest -H "Authorization: Bearer $ADATKA_KEY" --data-urlencode "q=szeged tisza lajos krt 2" --data-urlencode "limit=3"

Várható eredmény JSON; a suggestions listában három cím, az első: 6720 Szeged, Tisza Lajos körút 2 ("match_level": "house").

Tipp: a válasz olvashatóbb, ha a parancs végére ezt írja: | python3 -m json.tool.

API-kulcs

A kulcsot minden kérés fejlécében küldje el; a két forma egyenértékű:

Authorization: Bearer <API-kulcs>
X-API-Key: <API-kulcs>

Az URL-ben küldött kulcsot nem vesszük figyelembe, mert az URL-ek naplókban és a böngésző előzményeiben megmaradnak; az ilyen kérés kulcs nélkülinek számít.

Kétféle kulcs van:

A szerverkulcs titok: ne kerüljön a böngészőnek küldött kódba (HTML, JavaScript), Git-tárolóba, URL-be vagy naplóba. Ha illetéktelen kézbe került, írjon azonnal az info@adatka.hu címre, lehetőleg arról az e-mail-címről, amelyre a kulcsot küldtük. A kulcsot visszavonjuk, és újat adunk helyette. Böngészőkulcs igénylésekor írja meg a webhely pontos webcímét, a https:// előtaggal együtt; ha a webhely www nélkül is megnyílik, mindkét változatot.

A végpontok böngészőből közvetlenül is hívhatók: a válaszok Access-Control-Allow-Origin: * fejlécet kapnak, az előzetes (preflight) kérés a GET és a POST metódust és bármely kérésfejlécet engedi. Weboldalról böngészőkulccsal hívjon; a szerverkulcs a böngészőbe nem való.

A bétaüzemben a szolgáltatás egyelőre kulcs nélkül is válaszol, az érvénytelen vagy visszavont kulcsot azonban mindig elutasítja (401). Így könnyen ellenőrizheti, hogy a kulcs eljut-e hozzánk: az alábbi parancs egy betűt (x) fűz a kulcs végére — 401-es választ kell kapnia.

curl -sG https://adatka.hu/suggest -H "Authorization: Bearer ${ADATKA_KEY:?nincs megadva}x" --data-urlencode "q=Szeged" -o /dev/null -w "%{http_code}\n"

Várható eredmény 401. Ha mégis 200-at kap, a kulcs nem jut el hozzánk: ellenőrizze a fejléc írásmódját. Ha a kulcsot nem adta meg, a parancs nem fut le, és a terminál hibaüzenetet ír ki; ennek a végén ez áll: ADATKA_KEY: nincs megadva.

A kulcsot már most küldje minden kérésben: így a kéréseit a kulcsához rendeljük, és ha a kulcs kötelezővé válik, nem kell semmit átírnia. Erről az API-kulccsal rendelkezőket előre, e-mailben értesítjük. Kulcsot az oldal alján, a „Hozzáférés” résznél kérhet.

Címjavaslat — GET /suggest

Címjavaslatok gépelés közben, a címmezőbe beírt szöveg alapján; az első javaslat a legjobb találat. A szöveg lehet hiányos, ékezet nélküli, rövidített („bp”, „krt”, „u.”) vagy elgépelt, az irányítószám pedig állhat elöl vagy a végén.

Válasz: {"query": …, "suggestions": [címobjektum, …]}. Ha nincs találat, a lista üres; ez nem hiba, a válasz kódja 200.

A paraméterek értékét URL-kódolva küldje: a curl ezt a --data-urlencode kapcsolóval végzi el, a requests programkönyvtár (Python) a params argumentummal.

Gépelés közben ne küldjön kérést minden billentyűleütésre: várja meg, amíg a gépelésben rövid szünet áll be. A demónk például az utolsó leütés után 180 ezredmásodperccel küldi a kérést. Így kevesebb kérést küld, és nem éri el feleslegesen a percenkénti korlátot.

curl -sG https://adatka.hu/suggest -H "Authorization: Bearer $ADATKA_KEY" --data-urlencode "q=9022 gyor baross gabor ut 12" --data-urlencode "limit=1"

Várható eredmény 9021 Győr, Baross Gábor út 12, és a meta.postal_not_matched értéke "9022": a beírt irányítószám nem ehhez a címhez tartozik.

Lépésenkénti kiválasztás

Ha az űrlap lépésenként kéri a címet — irányítószám vagy település, közterület, házszám —, a már kiválasztott részt külön paraméterben küldje, a q paraméterben pedig csak azt, amit a felhasználó utána beír. Az értékeket a kiválasztott javaslat mezőiből vegye át.

A postal_code a settlement mellé is megadható: ilyenkor szűkíti a találatokat. Ha a felhasználó településrészt választott (a javaslat settlement_part mezője), azt a settlement_part paraméterben küldje a settlement mellett; a házszámoknál is: a részben igazoltan lévő háznál a settlement_part ki van töltve, a rész határán kívüli háznál a settlement_part_not_matched jelzés jelenik meg.

curl -sG https://adatka.hu/suggest -H "Authorization: Bearer $ADATKA_KEY" --data-urlencode "settlement=Szeged" --data-urlencode "street=Tisza Lajos körút" --data-urlencode "q=2"

Várható eredmény öt házszám (2, 20, 21, 22 és 23), mindegyiknél "match_level": "house".

Cím koordinátából (fordított geokódolás) — GET /reverse

A ponthoz legközelebbi ismert házszámos címek, a legközelebbi elöl. (Címből koordinátát a /suggest és a /clean ad: a címobjektum geo mezőjében; a pontosságát a geo.precision mutatja.)

Válasz: {"lat": …, "lon": …, "suggestions": [címobjektum, …]}.

curl -sG https://adatka.hu/reverse -H "Authorization: Bearer $ADATKA_KEY" --data-urlencode "lat=46.2557" --data-urlencode "lon=20.1562"

Várható eredmény 6720 Szeged, Tisza Lajos körút 2 ("match_level": "house").

A válasz mindig a legközelebbi ismert magyarországi házat adja, a távolságot azonban nem. Ha a pont távol esik a házaktól — mezőn, vízen vagy az országhatáron túl —, a talált cím messze lehet a ponttól; ha ez fontos, a távolságot számolja ki a geo.lat és a geo.lon mezőből. Ha a limit 1-nél nagyobb, ugyanaz a cím többször is szerepelhet, mert a forrásban egy házhoz több címpont is tartozhat; megjelenítés előtt szűrje ki az ismétlődéseket.

Címlista ellenőrzése — POST /clean

Soronként egy cím, kérésenként legfeljebb 1000 sor. A válaszban minden sorhoz pontosan egy címobjektum tartozik, ugyanabban a sorrendben; az eredeti sor az input mezőben áll.

A kérés törzse JSON (Content-Type: application/json): {"records": ["…", "…"]}. Válasz: {"results": [címobjektum, …]}.

curl -s https://adatka.hu/clean -H "Authorization: Bearer $ADATKA_KEY" -H "Content-Type: application/json" -d '{"records": ["Szeged, Tisza Lajos krt. 2", "pecs kiraly u 999"]}'

Várható eredmény a results listában két címobjektum; az első 6720 Szeged, Tisza Lajos körút 2 ("quality_code": 0), a második Pécs, Király utca ("quality_code": 1, "house_not_found": "999").

Ha 1000-nél több sort küld, a válasz 413: ossza fel a listát legfeljebb 1000 soros részekre — lásd a Python-példát.

Állapot — GET /health

Monitorozáshoz: fut-e a szolgáltatás, és melyik adatállománnyal. Kulcs nem kell hozzá, és nem számít bele a korlátokba.

curl -s https://adatka.hu/health

Várható eredmény JSON, benne "message": "adatka él!" és (a bétaüzemben) "api_key_required": false.

A többi mező belső üzemeltetési adat, nem része a dokumentált felületnek; a programja ne építsen rájuk.

Címobjektum

A /suggest, a /reverse és a /clean ugyanilyen felépítésű objektumot ad vissza (a /clean ezen felül az input mezőt is). Ha egy adat nem ismert, a mező értéke null. Valódi címobjektum — a /suggest válaszának első javaslata a „Szeged Tisza Lajos körút 2” szövegre:

{
  "country_code": "HU",
  "postal_code": "6720",
  "settlement": "Szeged",
  "settlement_part": null,
  "street": "Tisza Lajos körút",
  "house_number": "2",
  "sub_premise": {
    "building": null,
    "staircase": null,
    "floor": null,
    "door": null,
    "verified": false
  },
  "admin": {
    "county": "Csongrád-Csanád",
    "county_ksh": null,
    "district": "Szegedi",
    "district_ksh": "075 1",
    "city_district": null,
    "settlement_ksh": "33367",
    "iso_3166_2": null,
    "geoname_id": "715429"
  },
  "geo": {
    "lat": 46.255697,
    "lon": 20.156243,
    "precision": "house",
    "timezone": "Europe/Budapest"
  },
  "meta": {
    "match_level": "house",
    "confidence": 0.99,
    "quality_code": 0,
    "sources": [
      "OSM",
      "KSH",
      "GeoNames"
    ]
  }
}

A settlement_part a településrész: városrész, lakótelep vagy egyéb belterület (például Békásmegyer, Jereván-lakótelep, Felsőváros). A településrész önálló találat is lehet ("match_level": "settlement_part"). Címtalálatnál akkor kap értéket, ha a kérés megnevezi a településrészt, és a talált cím igazolhatóan a részben van: a rész határán belül esik (ahol a határ ismert — Budapesten a városrészek többségénél), vagy olyan irányítószámon van, amely a településen csak ehhez a részhez tartozik, vagy — saját koordinátájú háznál — a település részei közül ennek a résznek a középpontja van hozzá a legközelebb, legfeljebb 1 km-re. Ha a részhez tartozást nem tudjuk igazolni, a mező üres marad. Két mező a séma része, de jelenleg nem töltjük ki: admin.county_ksh, admin.iso_3166_2. Budapesti címnél az admin.county és az admin.district értéke null, mert a főváros sem vármegyéhez, sem járáshoz nem tartozik; a kerületet az admin.city_district adja.

Találati szintek és jelzések

A meta megmondja, mit és mennyire biztosan találtunk:

Ha a beírt szöveg egy része nem illik a talált címhez, a válasz ezt nem hallgatja el: a meta külön mezőben jelzi. A jelzés értéke a beírt szövegrész (a kerület egységesített alakban); kivétel a house_exists, amelynek értéke objektum.

A house_exists jelzés értéke a „tiszafured petofi u 12” kérésre:

{
  "source": "Nemzeti Választási Iroda",
  "dataset": "Körzetállomány (szavazóköri címállomány)",
  "extract_date": "2026-01-16",
  "street_matching": "Adatka"
}

A hiányzó találat nem bizonyíték: ha egy házszám nem szerepel az Adatka adatforrásaiban, az nem jelenti, hogy a cím nem létezik. A street vagy settlement szintű, illetve üres válasz önmagában ne akadályozza meg a megrendelést, a regisztrációt vagy az ügyintézést — a programja mindig adjon kézi beviteli vagy ellenőrzési lehetőséget (ÁSZF).

Új jelzés is megjelenhet: a programja hagyja figyelmen kívül, amit nem ismer.

Hibakódok

Elutasított kérésnél a válasz törzse: {"detail": {"error": "…", "message": "…"}}. A message magyar nyelvű, embernek szól; a programban az error értékére támaszkodjon. A 413-as és a 422-es válasz törzse más alakú.

Korlátok

• /suggest, /reverse: legfeljebb 20 cím egy válaszban (limit).
• /clean: legfeljebb 1000 sor egy kérésben.
• Szerverkulcs: alapértelmezés szerint percenként 120 kérés.
• Böngészőkulcs: alapértelmezés szerint percenként 120 és naponta 2000 kérés, mindkettő látogatónként (IP-címenként).
• Kulcs nélkül, 2026. november 4-ig — visszaélés elleni fék (ÁSZF 5. pont): címenként 60 kérés tartalék, amely másodpercenként 10 kéréssel töltődik vissza. A /clean minden sora egy kérésnek számít, ezért kulcs nélkül egy kérésben legfeljebb 60 sor küldhető.
• Kulcs nélkül, 2026. november 5-től — keret: címenként 60 kérés tartalék, amely másodpercenként 2 kéréssel töltődik vissza (kb. percenként 120), és naponta legfeljebb 3000 kérés; a /clean-ben egy kérésben legfeljebb 60 sor. IPv6-nál a /64-es hálózat számít egy címnek.
• Az összes kulcs nélküli kérésre együtt: másodpercenként 30 kérés (60 tartalék). Ha ez elfogy, a kulcs nélküli kérések kapnak 429-et; a kulccsal küldött kéréseket ez nem érinti — a kulcs elsőbbséget ad.
• A kulcsokhoz tartozó korlátokat egész percekre és naptári napokra számoljuk, nem csúszó ablakkal: a számláló minden egész perckor, illetve UTC szerint éjfélkor nullázódik. A kulcs nélküli tartalék folyamatosan töltődik vissza a megadott ütemben; a kulcs nélküli napi keret UTC szerint éjfélkor nullázódik. A 429-es válasz Retry-After fejléce megmondja, hány másodperc múlva próbálkozhat újra.

A kulcsához tartozó korlátokat a kulcs kiadásáról szóló levélben közöljük; ha eltérnek a fentiektől, a levél az irányadó. A kulcs nélküli korlátok a szolgáltatás védelmére valók: egy cím a többiek elől ne vehesse el a kapacitást (ÁSZF 5. pont). Ha kulcs nélkül rendszeresen a korlátba ütközik, kérjen API-kulcsot a „Hozzáférés” résznél: a kulcshoz magasabb keret és elsőbbség jár. A kiszolgáló saját gépéről küldött üzemeltetési kérésekre a kulcs nélküli korlátok nem vonatkoznak.

Python-példa

Teljes példa a requests programkönyvtárral: a kulcsot az ADATKA_KEY környezeti változóból veszi, a 429-es válasz után annyit vár, amennyit a Retry-After kér, a hosszú listát pedig 1000 soros részekben küldi. Ugyanabban a terminálban futtassa, amelyben a kulcsot megadta.

A requests könyvtárat telepítse saját virtuális környezetbe — az újabb Linux-rendszerek nem engedik, hogy a pip install a rendszer Pythonjába telepítsen:

python3 -m venv adatka-venv && . adatka-venv/bin/activate && pip install requests

Ha a python3 -m venv hibát ad („ensurepip is not available”), Debianon és Ubuntun előbb telepítse a python3-venv csomagot. Új terminálban aktiválja újra a környezetet (. adatka-venv/bin/activate), és adja meg újra a kulcsot.

Mentse el a példát adatka_pelda.py néven:

import os, time
import requests  # pip install requests

API = "https://adatka.hu"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ.get("ADATKA_KEY", "")  # bétaüzemben kulcs nélkül is fut

def call(method, path, **kw):
    for attempt in range(3):
        r = session.request(method, API + path, timeout=30, **kw)
        if r.status_code == 429:                  # korlát: annyit várunk, amennyit a válasz kér
            time.sleep(int(r.headers.get("Retry-After", "1")))
            continue
        r.raise_for_status()
        return r.json()
    raise RuntimeError("Adatka: a korlát háromszori próbálkozás után sem engedett")

def clean_all(lines):                             # kérésenként legfeljebb 1000 sor
    results = []
    for i in range(0, len(lines), 1000):
        results += call("POST", "/clean", json={"records": lines[i:i + 1000]})["results"]
    return results

hints = call("GET", "/suggest", params={"q": "Szeged Tisza Lajos körút 2", "limit": 5})["suggestions"]
rows = clean_all(["Szeged, Tisza Lajos krt. 2", "pecs kiraly u 999"])
print(hints[0]["postal_code"], [r["meta"]["quality_code"] for r in rows])

python3 adatka_pelda.py

Várható eredmény 6720 [0, 1] — az első javaslat irányítószáma és a két sor quality_code értéke.

Más programozási nyelven ugyanígy: a kulcs a fejlécben, a paraméterek URL-kódolva, a válasz JSON.

Adatvédelem a kérésekben

Csak címet vagy koordinátát küldjön. Nevet, e-mail-címet, telefonszámot, ügyfél- vagy rendelésazonosítót ne küldjön (ÁSZF 5. pont); ha a rendelés címmezőjében a címzett neve vagy telefonszáma is szerepel, küldés előtt távolítsa el.

A kérések szövegét nem naplózzuk. A GET /suggest és a GET /reverse kérésből a rendszernaplóba csak az útvonal, a paraméterek neve és értékük hossza, valamint a válasz kódja kerül, IP-cím és API-kulcs nélkül; ezeket a bejegyzéseket legfeljebb 14 napig őrizzük meg. A POST /clean törzse nem kerül naplóba. Részletek: Adatkezelési tájékoztató.

Változások

2026. október 6.: lépésenkénti kiválasztás településrésszel — új settlement_part paraméter a settlement mellé (Lépésenkénti kiválasztás).

2026. október 6.: a settlement_part címtalálatnál csak akkor kap értéket, ha a részhez tartozás igazolható — a rész határa, a csak a részhez tartozó irányítószám vagy a legközelebbi rész alapján (Címobjektum); a settlement_part_not_matched jelzés akkor is megjelenik, ha a ház a megnevezett rész határán kívül esik (Találati szintek és jelzések).

2026. október 5.: településrészek a keresésben — városrész, lakótelep, egyéb belterület („Békásmegyer”, „Jereván-lakótelep Sopron”, „szeged felsőváros”): új találati szint ("settlement_part"), a settlement_part mező kitöltése a rész irányítószámain belül talált címnél, új jelzés (settlement_part_not_matched); forrás: OpenStreetMap és KSH Helységnévtár (Találati szintek és jelzések, Források és licencek).

2026. október 5.: kulcs nélküli korlátok — visszaélés elleni fék azonnal, számszerű keret 2026. november 5-től; a 429-es válasz törzse kulcs nélkül megmondja az okot (Korlátok, Hibakódok).

2026. október 5.: a leírásba bekerült a böngészős hívás (CORS) módja (API-kulcs) és a hiányzó találat kezelésének szabálya (Találati szintek és jelzések).

Új mező, jelzés vagy végpont bármikor megjelenhet; a programja hagyja figyelmen kívül, amit nem ismer. A meglévő mezők és végpontok lényeges változásáról az ÁSZF 8. pontja szerint tájékoztatást adunk.

Hozzáférés

A szolgáltatás jelenleg meghívásos bétaüzemben, díjmentesen érhető el; önkiszolgáló regisztráció még nincs. Kérjen hozzáférést, és felvesszük Önnel a kapcsolatot.