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",
  "terms": "https://nakordoni.eu/en/p/developer_api_terms",
  "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, not_approved, bad_request, duplicate_request, market_not_allowed, internal_error, status_unavailable, timeout) oraz statusem HTTP 400/401/403/404/429/500/503/504. Nagłówki limitu częstotliwości X-Devapi-Limit i X-Devapi-Remaining są wysyłane w każdej rozliczanej odpowiedzi. ok:false jest rozstrzygające — nigdy nie odczytuj data z nieudanego wywołania. Obiekt usage występuje w każdym rozliczanym produkcie; /status jest publiczny i nierozliczany, więc nie zwraca usage.

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→PL (crossing_type=9; in v3 that one code covers both freight lanes):

let
    ApiKey = "NKD-DEV-XXXX-XXXX-XXXX",
    Source = Json.Document(Web.Contents("https://nakordoni.eu/api/v4/data/border/1/2/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" }
    }
  }
}

OAuth dla integracji (Home Assistant i inne)

Integracje, w których każdy użytkownik potrzebuje własnego klucza (niestandardowe integracje Home Assistant, aplikacje desktopowe i mobilne), mogą pozwolić użytkownikowi się zalogować zamiast wklejać klucz. Przepływ to OAuth 2.0 authorization code dla klientów publicznych z PKCE (S256) — nie ma client secret. Zwracany przez nas access token to własny klucz NKD-DEV użytkownika, który następnie wysyłasz w nagłówku Bearer dokładnie tak jak dotychczas.

Klienci nie są tworzeni samodzielnie: złóż wniosek na stronie integracji, każdą integrację weryfikujemy ręcznie i wydajemy client ID z dozwolonymi adresami URI przekierowania. Klucze wydane przez zatwierdzonego klienta są aktywowane natychmiast dla rynków zatwierdzonych dla tej integracji. Złóż wniosek o klienta integracji →

• Kod autoryzacyjny jest ważny przez 60 sekund, jest jednorazowy i powiązany z klientem, użytkownikiem, adresem URI przekierowania oraz PKCE challenge.
• Klucz jest zwracany wyłącznie w treści odpowiedzi z tokenem (access_token) — nigdy w adresie URL. Przechowuj go jak hasło.
• expires_in wynosi 30 dni; odświeżenie zwraca ten sam klucz, dopóki jest aktywny. Jeśli użytkownik unieważni lub wygeneruje klucz ponownie, odświeżenie kończy się błędem invalid_grant, a wywołania API zwracają 401 — rozpocznij ponowne uwierzytelnienie.
• Żądania mają limit na adres IP oraz dzienny limit na klienta; błędy są zgodne z RFC 6749 (error, error_description).
• Każdy użytkownik dostaje najwyżej własny limit krajów: gdy integracja obejmuje więcej krajów, niż użytkownik ma wolnych miejsc, wybiera je na stronie zgody (przekaż markets=DE,AT w /oauth/authorize, aby je wstępnie zaznaczyć). Obie odpowiedzi token zwracają też markets_approved (zatwierdzone kraje użytkownika), markets_allowed (jego limit; null = bez limitu), markets_available (Twoje kraje, których jeszcze nie ma) i upgrade_url (gdzie doda „Dodatkowe kraje”).

curl -X POST https://api.nakordoni.dev/oauth/token \
  -d grant_type=authorization_code -d client_id=nkd_xxxxxxxxxxxxxxxxxxxxxxxx \
  -d code=CODE -d code_verifier=VERIFIER \
  -d redirect_uri=https://my.home-assistant.io/redirect/oauth

{"access_token":"NKD-DEV-XXXX-XXXX-XXXX","token_type":"Bearer","expires_in":2592000,
 "refresh_token":"nkdrt_…","scope":"data","markets_approved":["DE"]}

Home Assistant

Użyj config_entry_oauth2_flow z LocalOAuth2ImplementationWithPkce (client_secret pusty) oraz adresu URI przekierowania https://my.home-assistant.io/redirect/oauth, który jest wstępnie zarejestrowany dla klientów Home Assistant. Odczytaj klucz z entry.data["token"]["access_token"] i nadal wywołuj API z nagłówkiem Authorization: Bearer. Po odpowiedzi 401 z API zgłoś ConfigEntryAuthFailed, aby Home Assistant zaproponował ponowne uwierzytelnienie.

from homeassistant.helpers import config_entry_oauth2_flow

impl = config_entry_oauth2_flow.LocalOAuth2ImplementationWithPkce(
    hass, DOMAIN, client_id="nkd_xxxxxxxxxxxxxxxxxxxxxxxx",
    authorize_url="https://api.nakordoni.dev/oauth/authorize",
    token_url="https://api.nakordoni.dev/oauth/token",
)
config_entry_oauth2_flow.async_register_implementation(hass, DOMAIN, impl)

Integracje: pokazuj pozostałe limity

GET /api/v2/account/usage — Ile zostało z Twoich limitów w tej chwili dla klucza, którym wywołujesz: plan, limit na sekundę oraz dla każdej klasy dziennego limitu (cheap, heavy, route) limit, zużycie, pozostało i czas resetu (północ UTC); także Twoje kraje widziane przez ten klucz i gdzie zmienić plan. Nie jest liczone, 30 wywołań na minutę na klucz.

Klucze integracji (OAuth) zawsze mogą wywołać GET /api/v2/account/usage, niezależnie od produktów dozwolonych dla integracji. Jego liczby są zgodne z nagłówkami X-Devapi-Limit i X-Devapi-Remaining; X-Devapi-Reset podaje czas resetu jako znacznik czasu Unix.

{"ok":true,"api_version":"v2","product":"account-usage","data":{
 "plan":{"slug":"explorer","name":"Explorer"},"qps":2,
 "quotas":{"cheap":{"limit":1000,"used":42,"remaining":958,"reset_at":"2026-10-17T00:00:00Z"},"heavy":{…},"route":{…}},
 "markets":{"approved":["DE"],"allowed":1,"available":["AT"],"key_bound":true},
 "pass":{"active":true,"expires_at":"2026-10-19T14:05:00Z","days_left":3},"upgrade_url":"https://nakordoni.eu/en/developers/billing",
 "pass_url":"https://nakordoni.eu/en/developers/billing?section=trip-pass#trip-pass"}}

Gdy limit zostanie osiągnięty, błąd wskazuje, dokąd przejść: 429 quota_exceeded zwraca też error.reset_at (północ UTC) i error.upgrade_url; 403 market_not_allowed i 403 integration_product_not_allowed zwracają error.upgrade_url. Klucze integracji dostają też error.pass_url (Trip Pass, poniżej).

Home Assistant: odpytuj /account/usage nie częściej niż co 15 minut i udostępnij czujnik „pozostałe wywołania” z quotas.cheap.remaining. Między odpytaniami czytaj X-Devapi-Remaining ze zwykłych wywołań. Przy 429 quota_exceeded lub 403 market_not_allowed utwórz repair issue z linkiem do error.upgrade_url i wstrzymaj wywołania do reset_at.

Trip Pass

Użytkownicy integracji mogą kupić Trip Pass (1, 3, 7 lub 14 dni, płatność jednorazowa) na stronie płatności. Gdy jest aktywny, klucz integracji dostaje wszystkie kraje integracji, więcej wywołań trasy ciężarówki i danych dziennie oraz wyższą częstotliwość; produkty integracji, limity prognoz i opóźnienie danych się nie zmieniają. Klucze deweloperskie tego samego konta nigdy nie są podnoszone.

Dla kluczy integracji account/usage zwraca pass: {active, expires_at, days_left} i pass_url (sekcja Trip Pass na stronie płatności); 429 quota_exceeded oraz 403 market_not_allowed / integration_product_not_allowed zawierają ten sam error.pass_url. Dla innych kluczy oba pola są null.

Country and vehicle-type codes

Border endpoints address countries and vehicle types by numeric id: /api/v1/data/border/{origin}/{destination}/{crossing_type}. destination also accepts a comma-separated list or the word all. The ids are stable and are the same in every product that takes an origin, a destination or a crossing_type.

Country ids

The border products accept the ids marked as origins below; the neighbours column is what destination=all expands to for that origin. Ids without neighbours are countries we name in responses but hold no crossings for yet. The Checkpoints Directory returns the origin, destination and crossing_type of every crossing we actually serve, so it stays the authoritative list.

Vehicle types (crossing_type)

The label in this table is the crossing_type_label the API returns with every response, in the language you request. Types outside the accepted list belong to crossings the directory carries but the border products do not answer for — ferry (10-13), freight up to 3.5 t (14) and rail (15) — and asking for one returns 400, not an empty result. Read crossing_type from the Checkpoints Directory rather than assuming: a crossing returns data only for the types it actually has.

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  ·  Trasa dla ciężarówek korzysta z własnego limitu tras dla ciężarówek — zob. Limity

Kolejki graniczne

Prognozy i statystyki

Paliwo i lokalizacje

Kantory wymiany walut

Planowanie podróży

Logistyka

Kierowcy i drogi

Your Fleet (NakBus Live)

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: widoczny, zwykły odnośnik HTML <a href> obok danych, który Google może zaindeksować i po którym może przejść — NIE dodawaj rel="nofollow", rel="sponsored" ani rel="ugc" i nie ukrywaj go przez CSS. Link dodany przez JavaScript jest w porządku, jeśli pojawia się na stronie renderowanej przez Google (Warunki Developer API v1.0, sekcja 8.1).

<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 widoczny, zwykły link HTML 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, na której wykorzystywane są dane", podanej przy rejestracji. Brak lub ukrycie atrybucji w bezpłatnym planie Explorer skutkuje najpierw przypomnieniem, a następnie zawieszeniem klucza. Klienci planów płatnych mogą pominąć atrybucję.

Weryfikacja odbywa się mniej więcej raz w tygodniu przez naszego weryfikatora, którego user agent zawiera NakordoniComplianceBot/1.0. Otwiera on wyłącznie strony wymienione w Twoim panelu dewelopera, nie podąża za innymi linkami i pomija robots.txt dla tych stron, ponieważ to właśnie je prosisz nas sprawdzać. Jeśli ochrona przed botami lub firewall blokuje nieznane crawlery, zezwól na ten user agent — gdy nie uda nam się otworzyć strony, napiszemy do Ciebie w zgłoszeniu.

Licencja danych i rynki

Twój klucz API udziela licencji na wykorzystanie naszych danych wyłącznie w krajach zadeklarowanych przy rejestracji. Weryfikujemy każdą deklarację przed przyznaniem pełnego dostępu, ponieważ nasze dane są naszym własnym produktem i nie licencjonujemy ich na rynki, nie wiedząc, gdzie zostaną opublikowane.

• Zadeklaruj każdy kraj, który obsługuje Twoja strona, aplikacja lub produkt. Listę możesz zmienić w dowolnym momencie z panelu; zmiana ponownie kieruje konto do weryfikacji.
• Do momentu zatwierdzenia rynków klucz działa z ograniczonymi limitami — połową limitu planu Starter. Dotyczy to niezależnie od tego, na jakim planie jesteś.
• 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ą.
• Publikowanie lub redystrybucja naszych danych na rynku, którego nie zadeklarowałeś, lub odsprzedaż ich jako konkurencyjnego strumienia danych stanowi naruszenie niniejszych warunków i może spowodować zawieszenie klucza bez uprzedzenia.
• Niektóre plany są dostępne tylko w wybranych regionach. Dostępność zależy od zadeklarowanych przez Ciebie rynków.
• Pełną umową są Warunki Developer API. Mają one pierwszeństwo przed tym podsumowaniem; wersją wiążącą jest wersja angielska.

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