История на промените в API

If an assistant has a feed enabled but the call does not carry the context that feed needs — queue without a ppid, for example — the feed is now skipped before any request is made and is not charged. Previously it was called anyway, failed, and still cost a unit. The studio shows what each feed needs, recalculates the price as you fill the context in, and marks results ✓ ran / ⊘ skipped, not charged / ✕ failed; the API returns data.feeds_skipped telling you exactly which parameter to pass.

Answers no longer mention feeds, data sources or anything technical: a missing feed is at most one plain sentence to the end user, never an internal name. Feeds with only optional filters (such as fuel narrowed to a country we have no data for) now fall back to the broad dataset instead of returning nothing.

New: /{lang}/developers/studio. Build an AI assistant that answers from your content and our live border data. Give us your markdown, or just name the pages and we fetch and index them — you only ever maintain your own files. Pick which of our feeds it may use (queue, forecast, alternatives, day-stats, fuel, truck bans, trading Sundays, holidays, road conditions, bus carriers, POIs, currency), pick a model tier (fast / balanced / pro — that is what sets the price), write your own instructions with {{feed.slug}} placeholders saying exactly where our data lands in the answer, and add a closing sentence of your own that is appended to every reply. Ready-made blueprints: personal travel assistant, work/freight assistant, insurance & Green Card sales assistant.

Test it in the studio (30 answers/day, separate from your API quota), then call it in production at GET /api/v2/data/assistant-custom?assistant_id=N&q=…. Price per answer = model tier units + 1 unit per enabled feed, returned in X-Devapi-Units. The product is v2-only — a v1 URL returns unsupported_version. The existing assistant product is unchanged.

Every assistant runs under a platform content policy that outranks your instructions: no impersonating officials, no help evading border or customs control, no invented numbers, no profanity. Instructions and answers are both screened; blocked calls are logged.

Ново: истински 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 widget с 3 дизайна (light, dark, board), 5 езика (en, uk, pl, de, ru), незадължителен филтър по държава и актуален статус «активно сега». Не е нужен API ключ. Настройте и копирайте кода на nakordoni.eu/en/for_truck_drivers/traffic_bans/widget. Предпочитате сурови данни? Продуктът API truck-bans и публичният JSON feed остават достъпни.

Три допълнения, всички обратно съвместими — v1 остава непроменен.

Версиониране на ниво endpoint. Вече има базов URL /api/v2/. То е на ниво отделен endpoint: само endpoint-ите, които действително са се променили, се държат различно под v2; всеки друг endpoint прозрачно връща своя v1 отговор (така че /api/v2/data/queue = същите данни като v1, само с "api_version":"v2"). Няма нужда да мигрирате endpoint-и, които работят.

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)

Всеки checkpoint също получава обект direction {from,to} и булев stale, а ?max_age_min=N връща само наскоро обновените пунктове. (v1 border продължава да връща и двете страни на границата независимо от реда — непроменен.)

Интерактивен Sandbox. Влезлите разработчици вече могат да изпробват всеки endpoint направо от браузъра на Developers → Sandbox — изберете endpoint, версия и един от вашите ключове, променете параметрите и вижте отговора на живо. Тестването в Sandbox има собствен отделен дневен бюджет (50 заявки/ден) и никога не засяга реалната ви API квота.

Документацията вече е разделена по endpoint (Developers → API Docs) с избор на версия при endpoint-ите, които имат повече от една версия.

Във формулата за времето на изчакване са добавени два нови фактора, наред със съществуващите корекции 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 на редове в базата, вътрешни анотации на pipeline, неизползвани/мъртви полета) без реална продуктова стойност:

• 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 вече изобщо не съдържат поле source
• traffic_status — премахнато от border; винаги беше null и никога не се попълваше от която и да е част на системата

Ако вашата интеграция чете някое от тези полета, моля обновете я — вижте актуалния списък с полета на страницата с документация на съответния продукт.

Дневното използване на квотата (usage.used във всеки отговор) вече може да е десетична стойност (напр. 67.5) вместо винаги цяло число. Това е страничен ефект от това, че queue-advanced се таксува с дробна ставка — вижте по-долу. usage.limit не се засяга и винаги е цяло число. Ако вашият клиент строго типизира usage.used като цяло число, моля разширете го, за да приема десетично число/float.

Тези три продукта вече връщат същите полета за статус на живо, които показва сайтът: 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 ticket от таблото си, за да го активирате.

/api/v1/data/border вече правилно изчислява wait_min (и връща tmin/tpercar) за всеки checkpoint в отговора, съответствайки на продуктите queue и multi. Преди това поле винаги беше null.

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

Одобрените разработчици вече могат да свалят усреднени по час исторически данни за граничните опашки за до 5 checkpoint-а (плъзгащ прозорец до 90 дни) като CSV или NDJSON от новия раздел Data export. Данните са само публикувани и проверени за качество; времевите маркери са в UTC. Нуждаете се от достъп? Отворете Data ticket.

Още нямате уебсайт? Вече можете да създадете акаунт за разработчици, като опишете къде и как планирате да използвате данните ни, вместо да сте задължени да въведете URL на активна страница. Добавете реалния URL по-късно от таблото си (Акаунт & данни → Вашият проект), веднага щом сайтът или приложението ви заработи — видима обратна връзка към nakordoni.eu на тази страница се изисква от нашите Условия.

Разработчиците вече могат да изпращат собствени новини, свързани с границите, към новинарската линия на Nakordoni. Ако редакторите ни ги публикуват, получавате индексируема dofollow обратна връзка към вашата услуга (посочен издател + ред за източник) и превеждаме статията на всичките 24 езика безплатно.

Една статия седмично е безплатна; допълнителните статии са платена добавка. Изберете 'може леко да редактираме + да добавим вътрешни връзки' или 'публикуване без промени'. Изпращайте и следете статуса на прегледа в Developers → Submit news.

Multi-Checkpoint API (/api/v1/data/multi) вече таксува квотата като ⌈(N PPIDs × под-продукти) / 2⌉ — половината от цената на еквивалентните индивидуални извиквания. Заявка за 10 checkpoint-а с двата под-продукта вече струва 10 единици вместо 20. Хедърът X-Devapi-Units и meta.units_consumed в отговора отразяват намалената сума.

Извличайте статус на опашката на живо и свежест на данните за до 20 checkpoint-а с едно API извикване — предназначено за създатели на табла, които в момента опитват много PPIDs в цикъл.

Квотата се брои справедливо като N PPIDs × под-продукти заявени, така че общото използване е идентично с индивидуалните извиквания — но с едно отиване-връщане вместо много. Модели от типа 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, възраст на данните и име на checkpoint
• 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, не се засягат.

Заявявайте всички checkpoint-и на дадена граница + тип превозно средство с едно извикване, вместо да правите по една заявка на PPID.

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

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

Откривайте стойностите на PPID на checkpoint-и по име, без да разглеждате целия указател.

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) следват същия locale.

Порталът Nakordoni Developer API е достъпен на /en/developers. Регистрирайте се за безплатен Explorer ключ (200 заявки/ден), за да получите достъп до данни за граничните опашки, прогнози, цени на горива, шофьорски POIs и още.

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