API változásnapló

Új: egy valódi MCP-szerver a https://nakordoni.eu/mcp címen, amely az API biztonságos, csak olvasható részhalmazát (status, checkpoints, border queue, live queue, forecast) MCP-eszközökként teszi elérhetővé. Ugyanaz az API-kulcs és kvóta, mint a REST API-nál. Szerverkártya a /.well-known/mcp/server-card.json címen. Lásd az MCP-szerver szakaszt a dokumentációban.

The retitle to "Live Queue & Freshness API" below did not actually reach the docs page. The page renders each product title through a translation lookup that falls back to the endpoint's title only when no translation exists — and a translation already existed, frozen at the old name, in all 25 UI languages. It now wins over any future update to the underlying title until it is updated too.

Retitled the translation key in all 25 languages so the docs page matches. No endpoint, parameter or response change — title text only.

If you poll live queue data frequently, you may be spending heavy quota you do not need to. /update-info is standard-class and already returns the live figure:

GET /api/v1/data/update-info?ppid=id_13

It returns queue_now, freshness, age_minutes, is_realtime, status, timestamp and timezone. Use it for the frequent refresh against your standard daily quota, and keep /queue, /multi and /forecast (all heavy-class) for when you need wait_min, the trend fields or history.

Nothing changed in the endpoint itself — only its documentation. It was listed as the "Data Freshness API" and its description mentioned only the freshness rating, never queue_now, so it was easy to miss. It is now titled "Live Queue & Freshness API" with the returned fields spelled out. Thanks to the developer who raised this.

Some failed requests were returning HTTP 200 with ok: true and the error buried inside data — so the documented if (!ok) throw pattern could not detect them, and the call was still billed. Affected calls now return HTTP 400 with ok: false and a proper error.code / error.message, as documented. Seen on fuel-cities with an unsupported country and travel-matrix with malformed coordinates.

Separately, a missing required parameter returned 500 internal_error instead of 400 bad_request (an upstream 4xx body was being discarded before its status was read). It now returns 400 bad_request with the upstream message — e.g. search without ?name=.

Successful responses are byte-for-byte unchanged — same fields, same params, same quota cost. If your client already branches on ok, no change is needed. If it ignored ok and read data directly, it will now see error envelopes on calls that were always failing.

Fixed a bug where /multi could return a wrong queue count for some checkpoints — mainly Balkan and Hungary–Serbia crossings — whenever its cache was cold. The fallback read a table that, for those crossings, holds no queue data, and reported unrelated values as car counts. Measured examples: a checkpoint with 12 cars reported 6, and several with real queues reported 0.

Three changes you may notice:

• found: false now means there is genuinely no recent queue data. Previously you could receive found: true with a fabricated queue_now: 0.
• wait_status, trend_percent and trend_direction are now returned on cold requests — they were null before.
• The endpoint also falls back when its cached snapshot is stale (older than 24h), not only when it is missing.

No changes to request parameters, quota cost or response shape.

Kijavítottunk egy hibát, amely miatt minden /multi hívás kétszer került leszámlázásra — egyszer egy általános 1 egységes ellenőrzéssel, majd az endpoint saját, változó költségű képletével (N PPID × al-termékek). Egy hívás mostantól pontosan ⌈(N×M)/2⌉ egységbe kerül a dokumentációnak megfelelően, extra terhelés nélkül.

Emellett a dokumentáció oldalon minden termékhez hozzáadtunk egy Standard/Heavy kvótaosztály-jelvényt, hogy első pillantásra látszódjon, melyik napi kvótát terheli az adott endpoint.

A country és a countries egy paraméterré lett összevonva (1-15 vesszővel elválasztott kód). Új compare_to paraméter: azonos vs. eltérő ünnepek összehasonlítása országok között, kombinálható az upcoming+days paraméterekkel. A lang mostantól több nyelvet is elfogad (egy names objektumot ad hozzá). A days=0 vagy elhagyva az upcoming módban mostantól korlátlan mennyiséget jelent.

Hivatalos munkaszüneti napok európai országonként — dátumok, helyi elnevezések és típus. Ugyanaz a Nager.Date / OpenHolidaysAPI szolgáltatás áll mögötte (helyben számított koszovói naptárral), amely a nakordoni.eu ünnepnaptár oldalát és az előrejelző rendszer naptári tényezőit is táplálja.

• ?country=PL&year=2026 — egy ország teljes évi ünneplistája
• ?upcoming=1&days=30 — a közelgő ünnepek egyszerű listája több országon átívelően
• Paraméterek nélkül — egy alap országcsoport indexe a soron következő ünneppel

Hozzáadtuk a currency terméket — EUR-alapú árfolyamok PLN, CZK, HUF, USD, GBP, CHF, NOK és UAH devizákhoz, a Frankfurter (EKB) forrásból, 6 órán át gyorsítótárazva. Paraméterek nélkül, mindig a teljes árfolyamtáblát adja vissza. Lásd a dokumentációt.

Ágyazza be az élő európai kamionközlekedési tilalmakat a saját webhelyére — ingyenes iframe widget 3 dizájnnal (light, dark, board), 5 nyelven (en, uk, pl, de, ru), opcionális országonkénti szűrővel és élő «most aktív» státusszal. Nincs szükség API-kulcsra. Állítsa be és másolja a kódot itt: nakordoni.eu/en/for_truck_drivers/traffic_bans/widget. Inkább nyers adatokat szeretne? A truck-bans API-termék és a nyilvános JSON-feed továbbra is elérhető.

Három bővítés, mind visszafelé kompatibilis — a v1 változatlan.

Végpontonkénti verziózás. Mostantól létezik egy /api/v2/ alap-URL. Végpontonként működik: csak azok a végpontok viselkednek másképp a v2 alatt, amelyek ténylegesen megváltoztak; minden más végpont átlátszóan a v1 válaszát adja vissza (így a /api/v2/data/queue = ugyanaz az adat, mint a v1-nél, csak "api_version":"v2" értékkel). A működő végpontokat nem kell migrálni.

A border v2 irányfüggő. Az útvonalban a sorrend a haladási irányt jelenti:

GET /api/v2/data/border/1/2/6   → buses UA→PL (Ukrainian-side crossings)
GET /api/v2/data/border/2/1/6   → buses PL→UA (Polish-side crossings)

Minden checkpoint kap egy direction {from,to} objektumot és egy stale logikai értéket is, a ?max_age_min=N pedig csak a nemrég frissített átkelőket adja vissza. (A v1 border a sorrendtől függetlenül továbbra is a határ mindkét oldalát visszaadja — változatlanul.)

Interaktív Sandbox. A bejelentkezett fejlesztők mostantól bármely végpontot kipróbálhatnak a böngészőből itt: Developers → Sandbox — válasszon egy végpontot, verziót és egy saját kulcsát, módosítsa a paramétereket, és nézze meg az élő választ. A Sandbox-tesztelésnek saját, külön napi kerete van (50 hívás/nap), és soha nem érinti az élő API-kvótáját.

A dokumentáció mostantól végpontonként van felosztva (Developers → API Docs), verzióválasztóval azoknál a végpontoknál, amelyeknek több verziója van.

Két új tényező épült be a várakozásiidő-képletbe a meglévő section_mode és időjárási korrekciók mellé:

• service_rate — a jelenleg feldolgozott mért autó/perc a checkpoint konfigurált alaprátájához viszonyítva. Multiplikatív, 0.5x-1.5x közé korlátozva.
• shift_change — a checkpoint saját helyi 08:00/20:00 határőr-váltásának hatása. Additív (perc), nem multiplikatív — csak a váltás körüli +/-60 percen belül alkalmazva, minimális mintaelőzményt igényel, +/-120 percre korlátozva.

Az advanced_wait_min mostantól round(base_wait × section_mode × weather × service_rate) + shift_change.adjustment_min. Mindkét tényező megjelenik a driver_reported.prognosed_advanced_wait_min mezőben is a korábbi összehasonlításokhoz.

Egy biztonsági/adatvédelmi felülvizsgálat keretében a következő mezőket eltávolítottuk — belső megvalósítási részleteket tártak fel (a forrásadatok taxonómiája, adatbázis-sorazonosítók, belső pipeline-annotációk, nem használt/holt mezők) valódi termékérték nélkül:

• id és corrected — eltávolítva a queue sorobjektumaiból
• tmin/tpercar — eltávolítva a queue, border és multi végpontokból (a várakozásiidő-képlet állandói; a már kiszámított wait_min/wait_time nem érintett)
• source (nyers string, pl. "line") — eltávolítva a queue, multi és update-info végpontokból. Az update-info és a multi update_info blokkja továbbra is tartalmazza a source_category/source_label_en mezőket (egy kis nyilvános szótár); a queue és a multi queue blokkja már egyáltalán nem tartalmaz source mezőt
• traffic_status — eltávolítva a border végpontból; mindig null volt, és a rendszer egyetlen része sem töltötte fel soha

Ha az integrációja ezen mezők bármelyikét olvassa, kérjük, frissítse — az aktuális mezőlistát az adott termék dokumentációs oldalán találja.

A napi kvótafelhasználás (usage.used minden válaszban) mostantól tizedes érték is lehet (pl. 67.5) a korábbi mindig egész szám helyett. Ez annak a mellékhatása, hogy a queue-advanced tört ráta szerint kerül elszámolásra — lásd alább. A usage.limit nem érintett, és mindig egész szám. Ha a kliense szigorúan egész számként típusozza a usage.used mezőt, kérjük, bővítse ki, hogy tizedes/lebegőpontos értéket is elfogadjon.

Ez a három termék mostantól ugyanazokat az élő állapotmezőket adja vissza, amelyeket a webhely is mutat: wait_status (green/yellow/red, e checkpoint saját közelmúltbeli előzményei alapján), valamint trend_percent/trend_direction (up/up-slight/down/down-slight/stable, az elmúlt 3 óra összehasonlításával). Tisztán additív.

A /api/v1/data/queue data[] sorainál korábban a legtöbb forrásnál wait_time: null szerepelt — csak néhány forrásfeed jelent várakozási időt közvetlenül. Az ilyen érték nélküli sorok mostantól a szabványos tmin + queue×tpercar becslést kapják, amelyet egy új wait_time_estimated logikai érték jelöl, így megkülönböztetheti a ténylegesen jelentett értéket a számítotttól.

A queue-advanced mostantól hívásonként 1.5 units értékbe kerül 1 helyett (tükrözve a plusz forgalmi/időjárási/sofőrjelentés-lekérdezéseket, amelyeket elvégez) — lásd a fenti usage.used mezőt. A válasz továbbá már nem tartalmazza a tmin, tpercar vagy total_crossing_time mezőket, a driver_reported pedig mostantól csak {wait_min, ts, age_min} — a korábbi, előrejelzést a valósággal összehasonlító mezők (prognosed_wait_min, diff_min, historical_section_mode, historical_weather stb.) eltávolításra kerültek. A section_mode, weather, advanced_wait_min és exceeds_crossing_time változatlan.

A /api/v1/data/truck-bans mostantól minden országnál a bans_by_country alatt visszaad egy status értéket (active/clear), valamint az active_window, next_window, local_time és tz mezőket — az adott ország saját időzónájában számítva, így többé nem kell magának a nyers tilalmi időablakokat az órához mérnie. A válasz továbbá kiegészül egy legfelső szintű covered_countries listával és egy as_of UTC időbélyeggel.

GET /api/v1/data/truck-bans?country=PL

Tisztán additív — a meglévő current_bans/upcoming_bans/bans_by_country mezők változatlanok. Egy ismeretlen ?country= mostantól üres eredményt ad vissza a countries_not_covered mezővel az összes ország tilalmai helyett.

Egy új, opcionális termék, amely a szabványos várakozási időt az élő forgalmi áramláshoz és az időjáráshoz igazítja. Minden korrekció teljes lebontását visszaadja.

GET /api/v1/data/queue-advanced?ppid=id_13

Kérésre engedélyezve — nyisson egy Data ticketet az irányítópultjáról az aktiváláshoz.

A /api/v1/data/border mostantól helyesen számítja ki a wait_min értéket (és visszaadja a tmin/tpercar mezőket) a válasz minden checkpointjához, összhangban a queue és multi termékekkel. Korábban ez a mező mindig null volt.

A /api/v1/data/forecast mostantól megbízhatóan a v4 ensemble modellt használja bármely prediction_steps értékhez (korábban néhány nem szabványos időtáv csendben egy régebbi modellre válthatott vissza). Az ensemble-t tápláló időjárási tényező is javítva lett, és mostantól valóban tükrözi az élő körülményeket (eső, hó, szél, köd) ahelyett, hogy mindig nem elérhetőt jelentene.

A jóváhagyott fejlesztők mostantól letölthetik az óránként átlagolt előzményi határsor-adatokat legfeljebb 5 checkpointra (legfeljebb 90 napos gördülő ablak) CSV vagy NDJSON formátumban az új Data export fülről. Csak közzétett és minőség-ellenőrzött adatok érhetők el; az időbélyegek UTC szerintiek. Hozzáférésre van szüksége? Nyisson egy Data ticketet.

Még nincs webhelye? Mostantól úgy is létrehozhat fejlesztői fiókot, hogy leírja, hol és hogyan tervezi használni az adatainkat, ahelyett, hogy egy élő oldal URL-jét kellene megadnia. A valódi URL-t később is hozzáadhatja az irányítópultjáról (Account & data → Az Ön projektje), amint a webhelye vagy alkalmazása élővé válik — a Feltételeink szerint az adott oldalon egy látható, nakordoni.eu-ra visszamutató link szükséges.

A fejlesztők mostantól beküldhetik saját, határral kapcsolatos híreiket a Nakordoni hírfolyamába. Ha szerkesztőink közzéteszik, indexelhető dofollow backlinket kap a szolgáltatásához (közzétevői szerzősor + forrássor), és ingyenesen lefordítjuk a cikket mind a 24 nyelvre.

Hetente egy cikk ingyenes; a további cikkek fizetős kiegészítők. Válassza a 'enyhén szerkeszthetjük + belső linkeket adhatunk hozzá' vagy a 'változatlanul közzétesszük' lehetőséget. Beküldés és az ellenőrzési állapot követése itt: Developers → Submit news.

A Multi-Checkpoint API (/api/v1/data/multi) mostantól ⌈(N PPIDs × sub-products) / 2⌉ szerint számolja a kvótát — az egyenértékű egyedi hívások költségének fele. Egy 10 checkpointra vonatkozó, mindkét sub-productot tartalmazó kérés mostantól 20 helyett 10 units. A válaszban az X-Devapi-Units fejléc és a meta.units_consumed a kedvezményes összeget tükrözi.

Kérje le az élő queue-állapotot és az adatfrissességet legfeljebb 20 checkpointra egyetlen API-hívásban — az irányítópult-fejlesztők számára tervezve, akik jelenleg sok PPID-t kérdeznek le ciklusban.

A kvóta méltányosan az igényelt N PPIDs × sub-products szerint számolódik, így a teljes felhasználás megegyezik az egyedi hívásokéval — de sok helyett egyetlen körüljárással. A GreenTravel-jellegű minták 24+ hívás/óra helyett 2-re csökkennek.

GET /api/v1/data/multi?ppids=id_2,id_13,id_15,id_59&include=queue,update-info&lang=en

• include=queue — aktuális queue_now, becsült wait_min, adatkor és checkpoint-név
• include=update-info — adatfrissesség, forrásbesorolás, kor másodpercben/percben
• Kérésenként legfeljebb 20 PPID; kombinálja mindkét sub-productot egyetlen hívásban a teljes irányítópult-adatért
• A válasz tartalmazza a meta.units_consumed mezőt, így pontosan követheti a kvótafelhasználást

A queue termék válasza mostantól tartalmaz egy legfelső szintű snapshot objektumot a legfrissebb valós idejű adatokkal és egy kiszámított, prognosztizált várakozási idővel — ugyanaz a képlet, mint a nakordoni.eu hero szekciójában:

snapshot.queue_now  — current cars in queue
snapshot.wait_min   — tmin + queue_now × tpercar (minutes)
snapshot.tmin       — minimum crossing time (minutes)
snapshot.tpercar    — added time per vehicle (minutes)
snapshot.updated_at — when the queue data was recorded
snapshot.age_min    — minutes since last update
snapshot.source     — data source identifier

A data tömb (előzményi bejegyzések) változatlan — ez tisztán additív kiegészítés. Azok a kliensek, amelyek nem olvassák a snapshot mezőt, nem érintettek.

Kérdezze le egy adott határ + járműtípus összes checkpointját egyetlen hívásban, ahelyett, hogy PPID-nként külön kérést indítana.

GET /api/v1/data/border/{origin}/{destination}/{crossing_type}

• Támogat egyetlen célországot, vesszővel elválasztott listát, vagy az all értéket, amely egyszerre kiterjed minden figyelt szomszédra.
• Az eredmények a queue_now szerint növekvő sorrendben (legrövidebb sor elöl).
• Teljesen lokalizált: adja hozzá a ?lang=uk paramétert (vagy a 22 támogatott nyelv bármelyikét), hogy a checkpoint-neveket az adott nyelven kapja meg.

Fedezze fel a checkpointok PPID-értékeit név alapján a teljes könyvtár böngészése nélkül.

GET /api/v1/data/search?name=Krakovets,Shehyni&lang=en

• Egyetlen nevet vagy vesszővel elválasztott listát fogad el (legfeljebb 20).
• Mind a 24 fordítási nyelven keres — adjon meg egy nevet ukránul, lengyelül, németül vagy bármely támogatott nyelven, és megtalálja.
• Visszaadja az adott helyszín összes PPID-jét járműtípus szerint csoportosítva (autó / busz / gyalogos / kamion).

Az alternatives termék mostantól mind a 22 támogatott nyelven elfogadja a ?lang= paramétert (korábban csak 12-t).

Az új crossing_type paraméterrel felülbírálhatja a járműtípus-szűrőt — pl. adja meg a crossing_type=4 értéket, hogy autós alternatívákat kapjon akkor is, ha busz PPID-ről kérdez le.

A crossing_type_label mező a checkpoints, border és search válaszaiban mostantól mind a 22 támogatott nyelven a kért nyelvre van fordítva. Az országnév-mezők (origin_name, destination_name) ugyanazt a nyelvi beállítást követik.

A Nakordoni Developer API portál elérhető itt: /en/developers. Regisztráljon egy ingyenes Explorer kulcsért (200 kérés/nap), hogy hozzáférjen a határsor-adatokhoz, előrejelzésekhez, üzemanyagárakhoz, sofőr-POI-khoz és még többhöz.

Az induláskor elérhető termékek: checkpoints, queue, stats, day-stats, forecast, alternatives, update_info, fuel, pois, truck_bans, trading_sundays, bus_carriers, road_conditions, assistant.