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.

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 20 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

Asystent AI

Inne

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 planie Explorer prowadzi najpierw do przypomnienia, potem do zawieszenia klucza. Klienci Pay As You Grow mogą pominąć atrybucję.

Uzyskaj darmowy klucz API