Dokumentacja API

Uwierzytelnianie

Każde żądanie wymaga Twojego klucza API w nagłówku Authorization (zalecane) lub jako parametr ?key=.

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

Format odpowiedzi

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

Błędy zwracają ok:false z error.code (missing_api_key, invalid_api_key, qps_exceeded, quota_exceeded, unknown_product, product_unavailable, bad_request, internal_error) oraz statusem HTTP 401/403/404/429/500. Nagłówki limitu częstotliwości X-Devapi-Limit i X-Devapi-Remaining są wysyłane w każdej rozliczanej odpowiedzi.

Limity

Liczniki dzienne resetują się o północy UTC. Otrzymujesz e-mail przy 80% i 100% limitu.

Płatne plany podnoszą każdy z tych limitów. Aktualne plany i ich limity: Plany

Przykłady kodu

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)

Pobieraj dane o kolejkach, prognozach czy zakazach dla ciężarówek prosto do arkusza dzięki wbudowanemu konektorowi JSON w Power Query — bez kodu, z odświeżaniem według harmonogramu. Ten sam wzorzec nagłówków (Headers) działa dla każdego produktu tego API — wystarczy zmienić 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

Trzymaj klucz API wewnątrz zapytania M (Home → Advanced Editor), a nie w komórce arkusza — Power Query blokuje żądanie internetowe zbudowane na podstawie innego zapytania lub komórki ("Formula.Firewall"), chyba że poziom prywatności ustawiono na Organizational.

Wiele przejść granicznych w jednej tabeli (dashboardy flotowe) — 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 w Excelu lub zaplanowane odświeżanie w Power BI / Excel Online utrzymuje aktualność danych — bez kodu odpytywania (polling).

Integracja z ERP (BAS / BAF i platformy z rodziny 1C)

BAS / BAF i inne platformy z rodziny 1C mogą wywoływać to API bezpośrednio z zadania cyklicznego — HTTPConnection plus ReadJSON, bez warstwy pośredniej. Najczęstszy scenariusz to utrzymywanie aktualnego rejestru informacji z cenami paliw w UE.

Odświeżanie rejestru informacji (ceny paliw, wszystkie kraje w jednym wywołaniu)

// 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;

Trzy rzeczy do zrobienia poprawnie: przekaż New OpenSSLSecureConnection na porcie 443, inaczej żądanie polegnie na TLS; wywołuj /api/v1/data/fuel bez parametru country, żeby jedno żądanie zwróciło wszystkie kraje zamiast osobnego wywołania dla każdego; i sprawdzaj ok, zanim sięgniesz po data — błędy wracają jako ok:false z error.code, a nie jako wyjątek. Przykład używa angielskiego zestawu słów kluczowych platformy; zlokalizowane odpowiedniki (HTTPСоединение, ПрочитатьJSON, РегистрыСведений) działają identycznie.

Ceny paliw u źródeł zmieniają się raz na dobę, więc zadanie raz lub dwa razy dziennie w zupełności wystarczy i mieści się głęboko w darmowym limicie Explorer. Dane kolejek na żywo (queue, multi, border) zmieniają się co kilka minut — odpytuj je we własnym rytmie i użyj multi, aby odczytać do 5 przejść jednym żądaniem zamiast w pętli.

Serwer MCP

Wolisz wywoływanie narzędzi zamiast REST? Uruchamiamy prawdziwy serwer MCP (transport Streamable HTTP), udostępniający bezpieczny, tylko do odczytu podzbiór tego API jako narzędzia MCP — ten sam klucz API, ten sam limit, po prostu inny transport.

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

Konfiguracja klienta (Claude Desktop / Claude Code):

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

Produkty

Wybierz endpoint, aby zobaczyć pełną dokumentację, parametry, wersje i żywą piaskownicę.

Standardowy korzysta z domyślnej puli danych  ·  Ciężki korzysta z limitu prognozy i statystyk — zobacz Limity

Kolejki graniczne

Prognozy i statystyki

Paliwo i lokalizacje

Planowanie podróży

Kierowcy i drogi

Your Fleet (NakBus Live)

Asystent AI

Eksport danych historycznych

Zatwierdzeni deweloperzy mogą pobrać opublikowaną historię kolejek granicznych uśrednioną godzinowo dla maksymalnie 5 przejść (okno ruchome do 90 dni) w postaci spakowanego gzipem CSV, NDJSON lub JSON. To funkcja wyłącznie w portalu — NIE endpoint API; eksporty budujesz i pobierasz w zakładce „Eksport danych” w swoim koncie.

Dostęp przyznajemy na wniosek: otwórz zgłoszenie kategorii Data i napisz, których przejść dotyczy, jakiego okna czasowego i do czego chcesz go użyć. Po zatwierdzeniu w Twoim koncie pojawia się zakładka „Eksport danych”. Domyślny limit: 1 eksport dziennie, do 5 przejść w każdym — poproś nas o jego podniesienie.

Pola — jeden wiersz na przejście graniczne na każdą godzinę UTC

Dane są wyłącznie opublikowane i przed eksportem przechodzą nasze kontrole anomalii i jakości (żadnych surowych danych z pojedynczych zgłoszeń). Wszystkie znaczniki czasu są w UTC. Pliki przechowujemy 10 dni.

Pochodzenie: każdy plik zawiera w nagłówku podpisany odcisk (sha256 + HMAC), więc dowolną kopię można później potwierdzić jako autentyczne dane nakordoni.eu i sprawdzić pod kątem manipulacji — nawet po pobraniu.

# 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

Co możesz zbudować

Te same produkty danych renderują wizualizacje na nakordoni.eu — tygodniowe wykresy prognoz, godzinowe profile kolejek, karty statusu na żywo. Przedsmak tego, co zawierają API prognoz i statystyk:

Atrybucja

Integracje w planie Explorer muszą pokazywać widoczny link "Data by nakordoni.eu" wszędzie tam, gdzie wyświetlane są dane. To utrzymuje darmowy plan darmowym.

Dokładny kod

Skopiuj ten fragment bez zmian. Link musi pozostać indeksowalny: zwykły HTML <a href>, po którym mogą podążać wyszukiwarki — NIE dodawaj rel="nofollow" ani rel="sponsored", nie renderuj go wyłącznie przez JavaScript i nie ukrywaj przez CSS.

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

Kompaktowy drobny wariant (np. pod wykresem lub widżetem):

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

Możesz linkować do swojej wersji językowej, np. https://nakordoni.eu/pl/ — liczy się każdy indeksowalny link do nakordoni.eu. Tekst kotwicy "Data by nakordoni.eu" musi pozostać po angielsku.

Gdzie umieścić

• Bezpośrednio obok lub pod blokiem danych (tabela, wykres, widżet, odpowiedź) — na tym samym ekranie, widoczny bez dodatkowych kliknięć.
• Na każdej stronie lub ekranie aplikacji, gdzie pojawiają się nasze dane — nie tylko na stronie "o nas".
• Czytelny rozmiar i kontrast: co najmniej ~11px, nie ukryty, nie zwinięty, nie w kolorze tła.
• Natywne aplikacje mobilne bez linków HTML: pokaż tekst "Data by nakordoni.eu" na ekranie z danymi i umieść klikalny link na ekranie informacyjnym.

Okresowo weryfikujemy atrybucję na "stronie wykorzystania danych" podanej przy rejestracji. Brak lub deindeksacja atrybucji w darmowym planie Explorer prowadzi najpierw do przypomnienia, potem do zawieszenia klucza. Klienci planu płatnego mogą pominąć atrybucję.

Licencja danych i rynki

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.
• Możemy zatwierdzić tylko niektóre z krajów, które wskazałeś. Zatwierdzona lista, a nie ta, którą wskazałeś, określa kraje objęte Twoją licencją.
• 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.

Aktualność danych

To, jak świeże są dane, zależy od Twojego planu. W samej odpowiedzi nie ma żadnego znacznika — każdy plan zwraca te same pola, te same typy i tę samą strukturę odpowiedzi.

• Plany płatne — Student, Starter, Pro i Pro MAX: telemetria na żywo, bez opóźnienia.
• Bezpłatny plan Explorer: migawka z ostatnich 15–30 minut. Dokładne przesunięcie różni się w zależności od zapytania.

Opóźniona odpowiedź nigdy nie jest błędem ani problemem z limitem — to kompletna, poprawna odpowiedź ze starszymi liczbami. Ponowne wysłanie zapytania nie zwróci nowszych danych.

Jeśli Twoja aplikacja potrzebuje aktualnych danych, każdy płatny plan zwraca telemetrię w czasie rzeczywistym.

Uzyskaj darmowy klucz API