Změnový protokol API

Novinka: skutečný MCP server na adrese https://nakordoni.eu/mcp, který zpřístupňuje bezpečnou podmnožinu API pouze pro čtení (status, checkpoints, border queue, live queue, forecast) jako MCP nástroje. Stejný API klíč a kvóta jako u REST API. Karta serveru na adrese /.well-known/mcp/server-card.json. Viz sekce MCP server v dokumentaci.

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.

Opravena chyba, kvůli které se každé volání /multi účtovalo dvakrát — jednou obecnou kontrolou 1 jednotky a podruhé vlastním vzorcem proměnlivých nákladů endpointu (N PPID × podprodukty). Volání nyní stojí přesně ⌈(N×M)/2⌉ jednotek dle dokumentace, bez dalšího poplatku.

Na stránce dokumentace jsme také přidali odznak třídy kvóty (Standard/Heavy) u každého produktu, aby bylo na první pohled jasné, ze které denní kvóty daný endpoint čerpá.

country a countries byly sloučeny do jednoho parametru (1-15 kódů oddělených čárkou). Nový parametr compare_to: porovnání stejných a odlišných svátků mezi zeměmi, kombinuje se s upcoming+days. lang nyní přijímá více jazyků (přidává objekt names). days=0 nebo vynechání nyní znamená bez omezení v režimu upcoming.

Oficiální státní svátky pro každou evropskou zemi — data, místní názvy a typ. Postaveno na téže službě Nager.Date / OpenHolidaysAPI (s lokálně vypočítaným kalendářem Kosova), která pohání stránku kalendáře svátků nakordoni.eu a kalendářní faktory předpovědního systému.

• ?country=PL&year=2026 — úplný roční seznam svátků pro jednu zemi
• ?upcoming=1&days=30 — plochý seznam nadcházejících svátků napříč zeměmi
• Bez parametrů — index základní sady zemí s nejbližším svátkem pro každou

Přidán produkt currency — směnné kurzy vůči EUR pro PLN, CZK, HUF, USD, GBP, CHF, NOK a UAH, ze zdroje Frankfurter (ECB), ukládané do mezipaměti na 6 hodin. Bez parametrů, vždy vrací kompletní tabulku kurzů. Viz dokumentace.

Vložte na vlastní web aktuální evropské zákazy jízdy kamionů — bezplatný iframe widget se 3 designy (light, dark, board), 5 jazyky (en, uk, pl, de, ru), volitelným filtrem podle země a živým stavem «aktivní nyní». Klíč API není potřeba. Nastavte a zkopírujte kód na nakordoni.eu/en/for_truck_drivers/traffic_bans/widget. Preferujete surová data? Produkt API truck-bans a veřejný JSON kanál zůstávají dostupné.

Tři novinky, všechny zpětně kompatibilní — v1 beze změn.

Verzování na úrovni endpointů. Nyní existuje základní URL /api/v2/. Funguje na úrovni endpointů: odlišně se chovají pouze endpointy, které se skutečně změnily; každý ostatní endpoint transparentně vrací svou odpověď v1 (takže /api/v2/data/queue = stejná data jako v1, jen s "api_version":"v2"). Fungující endpointy migrovat netřeba.

border v2 je směrový. Pořadí v cestě určuje směr jízdy:

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)

Každý hraniční přechod navíc získává objekt direction {from,to} a booleovskou hodnotu stale, a ?max_age_min=N vrací pouze nedávno aktualizované přechody. (v1 border stále vrací obě strany hranice bez ohledu na pořadí — beze změn.)

Interaktivní Sandbox. Přihlášení vývojáři nyní mohou vyzkoušet libovolný endpoint z prohlížeče na Developers → Sandbox — vyberte endpoint, verzi a jeden ze svých klíčů, upravte parametry a uvidíte živou odpověď. Testování v Sandbox má vlastní samostatný denní rozpočet (50 calls/day) a nikdy se nedotýká vaší produkční kvóty API.

Dokumentace je nyní rozdělena podle endpointů (Developers → API Docs) s přepínačem verzí u endpointů, které mají více než jednu verzi.

Dva nové faktory zapojené do vzorce čekací doby, vedle stávajících úprav section_mode a počasí:

• service_rate — naměřený počet aut/min aktuálně odbavovaných oproti nakonfigurované základní rychlosti přechodu. Multiplikativní, v rozmezí 0.5x-1.5x.
• shift_change — vliv vlastního místního střídání směn pohraniční stráže v 08:00/20:00 na daném přechodu. Aditivní (minuty), nikoli multiplikativní — uplatňuje se pouze v rozmezí +/-60 minut od střídání, vyžaduje minimální historii vzorků, omezen na +/-120 minut.

advanced_wait_min je nyní round(base_wait × section_mode × weather × service_rate) + shift_change.adjustment_min. Oba faktory se také promítají do driver_reported.prognosed_advanced_wait_min pro historická porovnání.

V rámci bezpečnostní/soukromí revize byla odstraněna následující pole — odhalovala interní detaily implementace (naši taxonomii zdrojů dat, ID řádků DB, interní anotace pipeline, nepoužívaná/mrtvá pole) bez reálné produktové hodnoty:

• id a corrected — odstraněno z objektů řádků queue
• tmin/tpercar — odstraněno z queue, border a multi (konstanty vzorce čekací doby; již vypočítané wait_min/wait_time zůstávají beze změny)
• source (surový řetězec, např. "line") — odstraněno z queue, multi a update-info. update-info a multi (jeho blok update_info) stále obsahují source_category/source_label_en (malý veřejný slovník); queue a multi (jeho blok queue) již neobsahují žádné pole zdroje
• traffic_status — odstraněno z border; vždy bylo null a nikdy nebylo naplněno žádnou částí systému

Pokud vaše integrace čte kterékoli z těchto polí, aktualizujte ji — viz aktuální seznam polí na stránce dokumentace příslušného produktu.

Denní spotřeba kvóty (usage.used v každé odpovědi) může nyní být desetinná hodnota (např. 67.5) namísto vždy celého čísla. Jde o vedlejší efekt toho, že queue-advanced je účtován zlomkovou sazbou — viz níže. usage.limit zůstává beze změny a je vždy celé číslo. Pokud váš klient striktně typuje usage.used jako celé číslo, rozšiřte jej, aby přijímal desetinnou/plovoucí hodnotu.

Tyto tři produkty nyní vracejí stejná pole živého stavu, jaká zobrazuje web: wait_status (green/yellow/red, na základě vlastní nedávné historie tohoto přechodu) a trend_percent/trend_direction (up/up-slight/down/down-slight/stable, porovnání posledních 3 hodin). Čistě aditivní.

V /api/v1/data/queue měly řádky data[] dříve wait_time: null pro většinu zdrojů — jen několik externích kanálů hlásí čekací dobu přímo. Řádky bez ní nyní dostávají standardní odhad tmin + queue×tpercar, označený novou booleovskou hodnotou wait_time_estimated, abyste rozlišili skutečně nahlášenou hodnotu od vypočítané.

queue-advanced nyní stojí 1.5 jednotky za volání místo 1 (odráží dodatečné dotazy na provoz/počasí/hlášení řidičů, které provádí) — viz usage.used výše. Odpověď již také neobsahuje tmin, tpercar ani total_crossing_time a driver_reported je nyní jen {wait_min, ts, age_min} — předchozí pole porovnání prognózy se skutečností (prognosed_wait_min, diff_min, historical_section_mode, historical_weather atd.) byla odstraněna. section_mode, weather, advanced_wait_min a exceeds_crossing_time zůstávají beze změny.

/api/v1/data/truck-bans nyní vrací pro každou zemi v bans_by_country hodnotu status (active/clear) plus active_window, next_window, local_time a tz — vypočítané ve vlastním časovém pásmu dané země, takže už nemusíte sami porovnávat surová okna zákazů s hodinami. Odpověď také přidává seznam covered_countries nejvyšší úrovně a UTC časové razítko as_of.

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

Čistě aditivní — stávající pole current_bans/upcoming_bans/bans_by_country zůstávají beze změny. Neznámý ?country= nyní vrací prázdný výsledek s countries_not_covered místo zákazů všech zemí.

Nový volitelný produkt, který upravuje standardní čekací dobu podle živého toku provozu a počasí. Vrací kompletní rozpis každé úpravy.

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

Poskytováno na vyžádání — otevřete tiket Data ve svém panelu, abyste jej povolili.

/api/v1/data/border nyní správně počítá wait_min (a vrací tmin/tpercar) pro každý přechod v odpovědi, stejně jako produkty queue a multi. Dříve bylo toto pole vždy null.

/api/v1/data/forecast nyní spolehlivě používá ansámblový model v4 pro jakoukoli hodnotu prediction_steps (dříve se některé nestandardní horizonty mohly tiše vrátit ke staršímu modelu). Faktor počasí, který napájí ansámbl, byl také opraven a nyní skutečně odráží aktuální podmínky (déšť, sníh, vítr, mlha) místo toho, aby vždy hlásil nedostupnost.

Schválení vývojáři nyní mohou stahovat hodinově zprůměrovaná historická data hraničních front pro až 5 přechodů (klouzavé okno až 90 dní) ve formátu CSV nebo NDJSON z nové záložky Data export. Data jsou pouze publikovaná a zkontrolovaná na kvalitu; časová razítka v UTC. Potřebujete přístup? Otevřete tiket Data.

Ještě nemáte web? Nyní si můžete vytvořit vývojářský účet tím, že popíšete, kde a jak plánujete naše data využít, místo povinného zadání URL funkční stránky. Skutečnou URL doplňte později ze svého panelu (Account & data → Your project), jakmile bude váš web nebo aplikace v provozu — viditelný zpětný odkaz na nakordoni.eu na této stránce vyžadují naše Podmínky.

Vývojáři nyní mohou odesílat vlastní hraniční zprávy do zpravodajské linky Nakordoni. Pokud je naši editoři zveřejní, získáte indexovatelný zpětný odkaz dofollow na vaši službu (zmínka o vydavateli + řádek zdroje) a my zdarma přeložíme článek do všech 24 jazyků.

Jeden článek týdně je zdarma; další články jsou placený doplněk. Zvolte 'můžeme mírně upravit + přidat interní odkazy' nebo 'zveřejnit tak, jak je'. Odesílejte a sledujte stav kontroly v sekci Developers → Submit news.

Multi-Checkpoint API (/api/v1/data/multi) nyní účtuje kvótu podle vzorce ⌈(N PPIDs × sub-products) / 2⌉ — poloviční náklady oproti ekvivalentním jednotlivým voláním. Požadavek na 10 přechodů s oběma podprodukty nyní stojí 10 jednotek místo 20. Hlavička X-Devapi-Units a meta.units_consumed v odpovědi odrážejí sníženou částku.

Získejte živý stav front a čerstvost dat pro až 20 přechodů jedním voláním API — navrženo pro tvůrce dashboardů, kteří nyní dotazují mnoho PPIDs ve smyčce.

Kvóta se počítá spravedlivě jako N PPIDs × sub-products požadovaných, takže celková spotřeba je totožná s jednotlivými voláními — ale s jedním dotazem místo mnoha. Vzory ve stylu GreenTravel klesají z 24+ volání/hodinu na 2.

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

• include=queue — aktuální queue_now, odhadovaný wait_min, stáří dat a název přechodu
• include=update-info — čerstvost dat, klasifikace zdroje, stáří v sekundách/minutách
• Maximálně 20 PPIDs na požadavek; zkombinujte oba podprodukty v jednom volání pro kompletní data dashboardu
• Odpověď obsahuje meta.units_consumed, takže můžete přesně sledovat spotřebu kvóty

Odpověď produktu queue nyní obsahuje objekt snapshot nejvyšší úrovně s nejnovějšími daty v reálném čase a vypočítanou prognózovanou čekací dobou — stejný vzorec, jaký se používá v hero sekci nakordoni.eu:

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

Pole data (historické záznamy) zůstává beze změny — jde o čistě aditivní rozšíření. Klientů, kteří snapshot nečtou, se to netýká.

Dotazujte se na všechny přechody na dané hranici + typ vozidla jedním voláním místo samostatného požadavku pro každý PPID.

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

• Podporuje jednu cílovou zemi, seznam oddělený čárkami nebo all pro rozšíření na všechny sledované sousedy najednou.
• Výsledky seřazené podle queue_now vzestupně (nejkratší fronta první).
• Plně lokalizováno: přidejte ?lang=uk (nebo kterýkoli z našich 22 podporovaných jazyků) pro získání názvů přechodů v daném jazyce.

Vyhledávejte hodnoty PPID přechodů podle názvu bez procházení celého adresáře.

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

• Přijímá jeden název nebo seznam oddělený čárkami (až 20).
• Vyhledává ve všech 24 jazycích překladu — zadejte název v ukrajinštině, polštině, němčině nebo kterémkoli podporovaném jazyce a bude nalezen.
• Vrací všechny PPIDs v dané lokalitě seskupené podle typu vozidla (auto / autobus / chodec / kamion).

Produkt alternatives nyní přijímá ?lang= ve všech 22 podporovaných jazycích (dříve pouze 12).

Nový parametr crossing_type umožňuje přepsat filtr typu vozidla — např. předejte crossing_type=4 pro získání alternativ pro auta i při dotazu z autobusového PPID.

Pole crossing_type_label v odpovědích checkpoints, border a search se nyní překládá do požadovaného jazyka ve všech 22 podporovaných jazycích. Pole názvů zemí (origin_name, destination_name) se řídí stejnou lokalizací.

Portál Nakordoni Developer API běží na adrese /en/developers. Zaregistrujte si bezplatný klíč Explorer (200 requests/day) pro přístup k datům hraničních front, předpovědím, cenám paliva, POI pro řidiče a dalšímu.

Produkty dostupné při spuštění: checkpoints, queue, stats, day-stats, forecast, alternatives, update_info, fuel, pois, truck_bans, trading_sundays, bus_carriers, road_conditions, assistant.