Документація API

Автентифікація

Кожен запит потребує вашого ключа API в заголовку Authorization (рекомендовано) або як параметр ?key=.

curl "https://nakordoni.eu/api/v1/data/queue?ppid=id_13" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

Формат відповіді

{
  "ok": true,
  "api_version": "v1",
  "product": "queue",
  "attribution": "Data by nakordoni.eu",
  "data": { ... },
  "usage": { "limit": 1000, "used": 42, "reset": "2026-06-06T00:00:00Z" }
}

Помилки повертають ok:false з error.code (missing_api_key, invalid_api_key, qps_exceeded, quota_exceeded, unknown_product, product_unavailable, bad_request, internal_error) та HTTP-статусом 401/403/404/429/500. Заголовки обмеження частоти X-Devapi-Limit і X-Devapi-Remaining надсилаються в кожній тарифікованій відповіді.

Квоти

Денні лічильники скидаються опівночі за UTC. Ви отримуєте email при досягненні 80% і 100% квоти.

Платні тарифи піднімають кожен із цих лімітів. Актуальні тарифи та їхні ліміти: Плани

Приклади коду

curl

curl "https://nakordoni.eu/api/v1/data/queue?ppid=id_13" \
  -H "Authorization: Bearer $NKD_API_KEY"

JavaScript (fetch)

const res = await fetch('https://nakordoni.eu/api/v1/data/forecast?ppid=id_13&prediction_steps=24', {
  headers: { Authorization: `Bearer ${process.env.NKD_API_KEY}` }
});
const { ok, data, error, usage } = await res.json();
if (!ok) throw new Error(error?.code ?? res.status);
console.log(`forecast points: ${data.length}, calls left today: ${usage.limit - usage.used}`);

Python (requests)

import os, requests

r = requests.get(
    "https://nakordoni.eu/api/v1/data/stats",
    params={"ppid": "id_15", "compare": 1},
    headers={"Authorization": f"Bearer {os.environ['NKD_API_KEY']}"},
    timeout=15,
)
payload = r.json()
print(payload["data"]["daily"], payload["usage"])

Excel (Power Query)

Отримуйте дані про черги, прогнози чи заборони для вантажівок прямо в таблицю за допомогою вбудованого JSON-конектора Power Query — без коду, з оновленням за розкладом. Та сама схема заголовків (Headers) працює для будь-якого продукту цього API — достатньо змінити URL.

Data → Get Data → From Other Sources → Blank Query, then Home → Advanced Editor and paste:

let
    ApiKey = "NKD-DEV-XXXX-XXXX-XXXX",
    Source = Json.Document(Web.Contents("https://nakordoni.eu/api/v1/data/queue",
        [Query = [ppid = "id_13"], Headers = [Authorization = "Bearer " & ApiKey]])),
    data = Source[data],
    AsTable = Record.ToTable(data)
in
    AsTable

Тримайте ключ API всередині M-запиту (Home → Advanced Editor), а не в клітинці аркуша — Power Query блокує вебзапит, побудований на основі іншого запиту чи клітинки ("Formula.Firewall"), якщо рівень конфіденційності не встановлено як Organizational.

Кілька пунктів пропуску в одній таблиці (дашборди для автопарку) — e.g. every truck crossing UA→EU (crossing_type=9):

let
    ApiKey = "NKD-DEV-XXXX-XXXX-XXXX",
    Source = Json.Document(Web.Contents("https://nakordoni.eu/api/v1/data/border/1/all/9",
        [Headers = [Authorization = "Bearer " & ApiKey]])),
    checkpoints = Source[data],
    AsTable = Table.FromRecords(checkpoints)
in
    AsTable

Data → Refresh All в Excel або заплановане оновлення в Power BI / Excel Online тримає дані актуальними — без коду опитування (polling).

Інтеграція з ERP (BAS / BAF та платформи родини 1С)

BAS / BAF та інші платформи родини 1С можуть звертатися до цього API просто з регламентного завдання — HTTPConnection плюс ReadJSON, без проміжного сервісу. Найпоширеніший сценарій: тримати в актуальному стані регістр відомостей із цінами на пальне в ЄС.

Оновлення регістру відомостей (ціни на пальне, усі країни одним запитом)

// Scheduled job — runs once a day
Connection = New HTTPConnection("nakordoni.eu", 443, , , , 30, New OpenSSLSecureConnection);

Headers = New Map;
Headers.Insert("Authorization", "Bearer NKD-DEV-XXXX-XXXX-XXXX");

Request  = New HTTPRequest("/api/v1/data/fuel", Headers);
Response = Connection.Get(Request);

Reader = New JSONReader;
Reader.SetString(Response.GetBodyAsString("UTF-8"));
Answer = ReadJSON(Reader, True);
Reader.Close();

If Answer["ok"] <> True Then
    // Answer["error"]["code"] says why; Answer["usage"] holds your quota state
    Return;
EndIf;

For Each Row In Answer["data"] Do
    Record = InformationRegisters.FuelPrices.CreateRecordManager();
    Record.Period   = CurrentSessionDate();
    Record.Country  = Row["country"];    // "PL", "DE", "SK", "RO", ...
    Record.Diesel   = Row["diesel"];
    Record.Petrol   = Row["petrol"];
    Record.LPG      = Row["lpg"];
    Record.Currency = Row["currency"];
    Record.Write();
EndDo;

Три речі, які треба зробити правильно: передайте New OpenSSLSecureConnection на порт 443, інакше запит впаде на TLS; викликайте /api/v1/data/fuel без параметра country — один запит поверне всі країни замість окремого виклику на кожну; і перевіряйте ok перед тим, як читати data — помилки приходять як ok:false з error.code, а не як виняток. У прикладі використано англомовний набір ключових слів платформи; локалізовані відповідники (HTTPСоединение, ПрочитатьJSON, РегистрыСведений) працюють ідентично.

Ціни на пальне у джерелах змінюються раз на добу, тож регламентного завдання раз або двічі на день достатньо — і це залишається глибоко в межах безкоштовної квоти Explorer. Дані живих черг (queue, multi, border) оновлюються кожні кілька хвилин: опитуйте їх за власним графіком і беріть multi, щоб зчитати до 5 пунктів пропуску одним запитом замість циклу.

MCP-сервер

Надаєте перевагу виклику інструментів замість REST? Ми запускаємо справжній MCP-сервер (транспорт Streamable HTTP), що надає безпечну підмножину цього API лише для читання у вигляді MCP-інструментів — той самий API-ключ, та сама квота, просто інший транспорт.

Endpoint: https://nakordoni.eu/mcp · Server card: /.well-known/mcp/server-card.json

get_api_status      — no key required
list_checkpoints     — country, lang
get_border_queue     — origin, destination, crossing_type, lang
get_live_queue       — ppid, lang
get_queue_forecast   — ppid, prediction_steps

Налаштування клієнта (Claude Desktop / Claude Code):

{
  "mcpServers": {
    "nakordoni": {
      "url": "https://nakordoni.eu/mcp",
      "headers": { "Authorization": "Bearer NKD-DEV-XXXX-XXXX-XXXX" }
    }
  }
}

Продукти

Оберіть ендпоінт, щоб побачити повний довідник, параметри, версії та живу пісочницю.

Стандартний використовує стандартну квоту даних  ·  Важкий використовує прогноз та статистику ліміту — див. Квоти

Черги на кордоні

Прогнози та статистика

Пальне та локації

Планування маршруту

Водії та дороги

Your Fleet (NakBus Live)

ШІ-асистент

Експорт історичних даних

Схвалені розробники можуть завантажити опубліковану історію черг на кордоні, усереднену погодинно, для до 5 пунктів пропуску (рухоме вікно до 90 днів) у форматі gzip-CSV, NDJSON або JSON. Це можливість лише в порталі — НЕ ендпоінт API; експорти ви формуєте й завантажуєте на вкладці «Експорт даних» у своєму акаунті.

Доступ надається за запитом: відкрийте тікет категорії Data й вкажіть, які пункти пропуску, за який період і для чого вам потрібні. Після схвалення в акаунті з’явиться вкладка «Експорт даних». Ліміт за замовчуванням: 1 експорт на день, до 5 пунктів пропуску в кожному — попросіть нас підняти його.

Поля — один рядок на пункт пропуску за кожну годину UTC

Дані — лише опубліковані, і перед експортом вони проходять наші перевірки аномалій та якості (жодних сирих даних окремих повідомлень). Усі позначки часу — UTC. Файли зберігаються 10 днів.

Походження: кожен файл містить у заголовку підписаний відбиток (sha256 + HMAC), тож будь-яку копію можна пізніше підтвердити як справжні дані nakordoni.eu і перевірити на зміни — навіть після завантаження.

# sha256: 3f9c…   # signature: e87b…
ppid,checkpoint_name,hour_utc,direction,vehicle_type,avg_queue_length,avg_wait_minutes,sample_count
id_10,Hrushiv,2026-06-12T02:00:00Z,UA->PL,car,11,,4

Що ви можете створити

Ті самі продукти даних формують візуалізації на nakordoni.eu — тижневі графіки прогнозів, погодинні профілі черг, картки статусу в реальному часі. Невеликий приклад того, що містять API прогнозів і статистики:

Атрибуція

Інтеграції плану Explorer мають показувати видиме посилання "Data by nakordoni.eu" скрізь, де відображаються дані. Це зберігає безкоштовний план безкоштовним.

Точний код

Скопіюйте цей фрагмент як є. Посилання має залишатися індексованим: звичайний HTML <a href>, який пошукові системи можуть переходити — НЕ додавайте rel="nofollow" чи rel="sponsored", не рендеріть його лише через JavaScript і не ховайте через CSS.

<a href="https://nakordoni.eu/" title="Border queues, forecasts &amp; statistics">Data by nakordoni.eu</a>

Компактний дрібний варіант (наприклад, під графіком чи віджетом):

<p style="font-size:12px;margin:4px 0">
  Data by <a href="https://nakordoni.eu/">nakordoni.eu</a>
</p>

Можна посилатися на свою мовну версію, наприклад https://nakordoni.eu/uk/ — рахується будь-яке індексоване посилання на nakordoni.eu. Текст якоря "Data by nakordoni.eu" має залишатися англійською.

Де розміщувати

• Безпосередньо поруч або під блоком даних (таблиця, графік, віджет, відповідь) — на тому ж екрані, видимо без додаткових кліків.
• На кожній сторінці чи екрані застосунку, де відображаються наші дані — не лише на сторінці "про нас".
• Читабельний розмір і контраст: щонайменше ~11px, не приховано, не згорнуто, не кольором фону.
• Нативні мобільні застосунки без HTML-посилань: показуйте текст "Data by nakordoni.eu" на екрані з даними та розмістіть клікабельне посилання на екрані "про застосунок".

Ми періодично перевіряємо атрибуцію на "сторінці використання даних", яку ви вказали під час реєстрації. Відсутність або деіндексація атрибуції на безкоштовному плані Explorer спершу веде до нагадування, потім до призупинення ключа. Клієнти платного плану можуть не вказувати атрибуцію.

Ліцензія на дані та ринки

Your API key grants a licence to use our data in the countries you declared when you signed up, and only in those countries. We review every declaration before granting full access, because our data is our own product and we do not license it into markets without knowing where it will be published.

• Declare every country your site, app or product serves. You can change the list from your dashboard at any time; a change puts your account back into review.
• Until your markets are approved your key runs on reduced limits - half of the Starter plan allowance. This applies whatever plan you are on.
• Ми можемо схвалити лише деякі країни з тих, які ви запросили. Затверджений список, а не запрошений, визначає країни, які покриває ваша ліцензія.
• Publishing or redistributing our data in a market you did not declare, or reselling it as a competing data feed, is a breach of these terms and can suspend your key without notice.
• Some plans are offered only in selected regions. Availability depends on the markets you declare.

Свіжість даних

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

• Платні тарифи — Student, Starter, Pro і Pro MAX: жива телеметрія, без затримки.
• Безкоштовний тариф Explorer: знімок за останні 15–30 хвилин. Точне зміщення змінюється від запиту до запиту.

Затримана відповідь — це не помилка і не проблема з лімітом: це повноцінна валідна відповідь зі старішими числами. Повторний запит новіших даних не поверне.

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

Отримати безкоштовний ключ API