Журнал змін API

Нове: справжній MCP-сервер за адресою https://nakordoni.eu/mcp, що надає безпечну підмножину API лише для читання (status, checkpoints, border queue, live queue, forecast) у вигляді MCP-інструментів. Той самий API-ключ і квота, що й у REST API. Картка сервера за адресою /.well-known/mcp/server-card.json. Див. розділ MCP-сервер у документації.

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.

Виправлено помилку, через яку кожен виклик /multi тарифікувався двічі — спочатку загальною перевіркою на 1 одиницю, а потім власною формулою змінної вартості ендпоінту (N PPID × підпродукти). Тепер виклик коштує рівно ⌈(N×M)/2⌉ одиниць, як і задокументовано, без додаткового нарахування.

Також на сторінці документації додано значок класу квоти (Standard/Heavy) для кожного продукту, щоб було одразу зрозуміло, яку денну квоту витрачає ендпоінт.

country та countries об'єднано в один параметр (1-15 кодів через кому). Новий параметр compare_to: порівняння однакових і різних свят між країнами, поєднується з upcoming+days. lang тепер приймає кілька мов (додає об'єкт names). days=0 або відсутній тепер означає без обмеження в режимі upcoming.

Офіційні державні свята для кожної європейської країни — дати, місцеві назви та тип. Працює на тому самому сервісі Nager.Date / OpenHolidaysAPI (з локально обчисленим календарем Косова), що й сторінка календаря свят nakordoni.eu та календарні фактори системи прогнозування.

• ?country=PL&year=2026 — повний річний перелік свят для однієї країни
• ?upcoming=1&days=30 — плоский список найближчих свят по країнах
• Без параметрів — індекс базового набору країн із найближчим святом для кожної

Додано продукт currency — курси обміну на основі EUR для PLN, CZK, HUF, USD, GBP, CHF, NOK та UAH, з джерела Frankfurter (ECB), кешуються на 6 годин. Без параметрів, завжди повертає повну таблицю курсів. Див. документацію.

Вбудуйте актуальні європейські заборони руху вантажівок на власний сайт — безкоштовний iframe-віджет із 3 дизайнами (light, dark, board), 5 мовами (en, uk, pl, de, ru), необов'язковим фільтром за країнами та живим статусом «зараз діє». Ключ API не потрібен. Налаштуйте та скопіюйте код на nakordoni.eu/en/for_truck_drivers/traffic_bans/widget. Потрібні сирі дані? Продукт API truck-bans та публічний JSON-фід залишаються доступними.

Три доповнення, усі зворотно сумісні — v1 без змін.

Версіонування на рівні ендпоінтів. Тепер є базова URL-адреса /api/v2/. Воно діє на рівні ендпоінтів: інакше поводяться лише ті ендпоінти, що дійсно змінилися; кожен інший ендпоінт прозоро віддає свою відповідь v1 (тож /api/v2/data/queue = ті самі дані, що й v1, лише з "api_version":"v2"). Мігрувати ендпоінти, які працюють, не потрібно.

border v2 є напрямленим. Порядок у шляху задає напрямок руху:

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)

Кожен пункт пропуску також отримує об'єкт direction {from,to} та булеве значення stale, а ?max_age_min=N повертає лише нещодавно оновлені пункти. (v1 border досі повертає обидві сторони кордону незалежно від порядку — без змін.)

Інтерактивний Sandbox. Авторизовані розробники тепер можуть спробувати будь-який ендпоінт із браузера на Developers → Sandbox — оберіть ендпоінт, версію та один зі своїх ключів, змініть параметри й побачте живу відповідь. Тестування в Sandbox має власний окремий добовий ліміт (50 calls/day) і ніколи не зачіпає вашу робочу квоту API.

Документацію тепер розділено за ендпоінтами (Developers → API Docs) із перемикачем версій на ендпоінтах, що мають більш ніж одну версію.

Два нових фактори додано до формули часу очікування, поряд із наявними коригуваннями section_mode та погодою:

• service_rate — виміряна кількість авто/хв, що зараз обробляються, порівняно з налаштованою базовою швидкістю пункту пропуску. Мультиплікативний, у межах 0.5x-1.5x.
• shift_change — вплив власної локальної зміни варти прикордонників о 08:00/20:00 на пункті пропуску. Адитивний (хвилини), а не мультиплікативний — застосовується лише в межах +/-60 хвилин від зміни, потребує мінімальної історії вибірки, обмежений до +/-120 хвилин.

advanced_wait_min тепер дорівнює round(base_wait × section_mode × weather × service_rate) + shift_change.adjustment_min. Обидва фактори також відображаються в driver_reported.prognosed_advanced_wait_min для історичних порівнянь.

У межах перегляду безпеки/приватності видалено такі поля — вони розкривали внутрішні деталі реалізації (нашу таксономію джерел даних, ідентифікатори рядків БД, внутрішні анотації конвеєра, невикористані/мертві поля) без реальної продуктової цінності:

• id та corrected — видалено з об'єктів рядків queue
• tmin/tpercar — видалено з queue, border та multi (константи формули часу очікування; уже обчислені wait_min/wait_time не зачіпаються)
• source (сирий рядок, напр. "line") — видалено з queue, multi та update-info. update-info та multi (його блок update_info) досі містять source_category/source_label_en (невеликий публічний словник); queue та multi (його блок queue) більше не містять жодного поля джерела
• traffic_status — видалено з border; воно завжди було null і ніколи не заповнювалося жодною частиною системи

Якщо ваша інтеграція читає будь-яке з цих полів, оновіть її — див. поточний перелік полів на сторінці документації відповідного продукту.

Добове використання квоти (usage.used у кожній відповіді) тепер може бути десятковим значенням (напр. 67.5) замість завжди цілого числа. Це побічний ефект того, що queue-advanced тарифікується за дробовою ставкою — див. нижче. usage.limit не зачіпається й завжди є цілим числом. Якщо ваш клієнт строго типізує usage.used як ціле число, розширте його до прийняття десяткового/дробового значення.

Ці три продукти тепер повертають ті самі поля живого статусу, що показує сайт: wait_status (green/yellow/red, на основі власної нещодавньої історії цього пункту пропуску) та trend_percent/trend_direction (up/up-slight/down/down-slight/stable, порівняння останніх 3 годин). Суто адитивне.

У /api/v1/data/queue рядки data[] раніше мали wait_time: null для більшості джерел — лише кілька зовнішніх фідів повідомляють час очікування напряму. Рядки без нього тепер отримують стандартну оцінку tmin + queue×tpercar, позначену новим булевим значенням wait_time_estimated, щоб ви могли відрізнити реально повідомлене значення від обчисленого.

queue-advanced тепер коштує 1.5 одиниці за виклик замість 1 (відображаючи додаткові запити трафіку/погоди/повідомлень водіїв, які він робить) — див. usage.used вище. Відповідь також більше не містить tmin, tpercar чи total_crossing_time, а driver_reported тепер лише {wait_min, ts, age_min} — попередні поля порівняння прогнозу з реальністю (prognosed_wait_min, diff_min, historical_section_mode, historical_weather тощо) видалено. section_mode, weather, advanced_wait_min та exceeds_crossing_time без змін.

/api/v1/data/truck-bans тепер повертає для кожної країни в bans_by_country значення status (active/clear) плюс active_window, next_window, local_time та tz — обчислені у власному часовому поясі цієї країни, тож вам більше не потрібно самостійно звіряти сирі вікна заборон із годинником. Відповідь також додає список covered_countries верхнього рівня та UTC-мітку часу as_of.

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

Суто адитивне — наявні поля current_bans/upcoming_bans/bans_by_country без змін. Невідомий ?country= тепер повертає порожній результат із countries_not_covered замість заборон усіх країн.

Новий підключуваний продукт, що коригує стандартний час очікування з урахуванням живого потоку трафіку та погоди. Повертає повну розбивку кожного коригування.

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

Надається за запитом — відкрийте тикет Data у своїй панелі, щоб увімкнути його.

/api/v1/data/border тепер коректно обчислює wait_min (і повертає tmin/tpercar) для кожного пункту пропуску у відповіді, як у продуктах queue та multi. Раніше це поле завжди було null.

/api/v1/data/forecast тепер надійно використовує ансамблеву модель v4 для будь-якого значення prediction_steps (раніше деякі нестандартні горизонти могли тихо відкочуватися до старішої моделі). Погодний фактор, що живить ансамбль, також виправлено, і він тепер справді відображає живі умови (дощ, сніг, вітер, туман) замість того, щоб завжди повідомляти про недоступність.

Схвалені розробники тепер можуть завантажувати усереднені за годину історичні дані черг на кордоні для до 5 пунктів пропуску (ковзне вікно до 90 днів) у форматі CSV або NDJSON з нової вкладки Data export. Дані лише опубліковані та перевірені на якість; мітки часу в UTC. Потрібен доступ? Відкрийте тикет Data.

Ще немає сайту? Тепер ви можете створити акаунт розробника, описавши, де і як плануєте використовувати наші дані, замість того щоб обов'язково вводити URL робочої сторінки. Додайте справжню URL пізніше зі своєї панелі (Account & data → Your project), щойно ваш сайт чи застосунок запрацює — видиме зворотне посилання на nakordoni.eu на цій сторінці вимагається нашими Умовами.

Розробники тепер можуть надсилати власні прикордонні новини до стрічки новин Nakordoni. Якщо наші редактори їх опублікують, ви отримаєте індексоване dofollow-посилання на ваш сервіс (згадка видавця + рядок джерела), і ми безкоштовно перекладемо статтю всіма 24 мовами.

Одна стаття на тиждень безкоштовно; додаткові статті — платне доповнення. Оберіть 'ми можемо трохи відредагувати + додати внутрішні посилання' або 'опублікувати як є'. Надсилайте та відстежуйте статус перевірки в розділі Developers → Submit news.

Multi-Checkpoint API (/api/v1/data/multi) тепер списує квоту за формулою ⌈(N PPIDs × sub-products) / 2⌉ — половина вартості еквівалентних окремих викликів. Запит на 10 пунктів пропуску з обома суб-продуктами тепер коштує 10 одиниць замість 20. Заголовок X-Devapi-Units та meta.units_consumed у відповіді відображають знижену суму.

Отримуйте живий статус черг та свіжість даних для до 20 пунктів пропуску одним викликом API — розроблено для творців дашбордів, які зараз опитують багато PPIDs у циклі.

Квота чесно рахується як N PPIDs × sub-products запитаних, тож загальне використання ідентичне окремим викликам — але з одним зверненням замість багатьох. Патерни в стилі GreenTravel зменшуються з 24+ викликів/годину до 2.

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

• include=queue — поточні queue_now, оцінений wait_min, вік даних та назва пункту пропуску
• include=update-info — свіжість даних, класифікація джерела, вік у секундах/хвилинах
• Максимум 20 PPIDs на запит; поєднайте обидва суб-продукти в одному виклику для повних даних дашборда
• Відповідь містить meta.units_consumed, щоб ви могли точно відстежувати використання квоти

Відповідь продукту queue тепер містить об'єкт snapshot верхнього рівня з найсвіжішими даними в реальному часі та обчисленим прогнозованим часом очікування — та сама формула, що використовується в hero-секції 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

Масив data (історичні записи) без змін — це суто адитивне доповнення. Клієнти, які не читають snapshot, не зачіпаються.

Запитуйте всі пункти пропуску на заданому кордоні + тип транспорту одним викликом замість того, щоб робити окремий запит на кожен PPID.

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

• Підтримує одну країну призначення, список через кому або all для розгортання на всіх відстежуваних сусідів одразу.
• Результати відсортовано за queue_now за зростанням (спершу найкоротша черга).
• Повністю локалізовано: додайте ?lang=uk (або будь-яку з наших 22 підтримуваних мов), щоб отримати назви пунктів пропуску цією мовою.

Знаходьте значення PPID пунктів пропуску за назвою без перегляду всього каталогу.

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

• Приймає одну назву або список через кому (до 20).
• Шукає в усіх 24 мовах перекладу — передайте назву українською, польською, німецькою чи будь-якою підтримуваною мовою, і вона співпаде.
• Повертає всі PPIDs у цій локації, згруповані за типом транспорту (легковик / автобус / пішохід / вантажівка).

Продукт alternatives тепер приймає ?lang= усіма 22 підтримуваними мовами (було лише 12).

Новий параметр crossing_type дозволяє перевизначити фільтр типу транспорту — напр. передайте crossing_type=4, щоб отримати альтернативи для легковиків навіть під час запиту з автобусного PPID.

Поле crossing_type_label у відповідях checkpoints, border та search тепер перекладається на запитану мову всіма 22 підтримуваними мовами. Поля назв країн (origin_name, destination_name) слідують тій самій локалі.

Портал Nakordoni Developer API працює за адресою /en/developers. Зареєструйте безкоштовний ключ Explorer (200 requests/day), щоб отримати доступ до даних черг на кордоні, прогнозів, цін на пальне, POI для водіїв тощо.

Продукти, доступні на старті: checkpoints, queue, stats, day-stats, forecast, alternatives, update_info, fuel, pois, truck_bans, trading_sundays, bus_carriers, road_conditions, assistant.