Dokumentace API

Autentizace

Každý požadavek potřebuje váš API klíč v hlavičce Authorization (doporučeno) nebo jako parametr ?key=.

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

Obálka odpovědi

{
  "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" }
}

Chyby vracejí ok:false s 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) a HTTP stavem 400/401/403/404/429/500/503/504. Hlavičky omezení rychlosti X-Devapi-Limit a X-Devapi-Remaining se odesílají u každé měřené odpovědi. ok:false je rozhodující — data u neúspěšného volání nikdy nečtěte. Objekt usage je v každém zpoplatněném produktu; /status je veřejný a nezpoplatněný, proto usage nevrací.

Kvóty

Denní čítače se resetují o půlnoci UTC. E-mail dostanete při 80 % a 100 % kvóty.

Placené tarify zvyšují každý z těchto limitů. Aktuální tarify a jejich limity: Plány

Ukázky kódu

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)

Získejte živá data o frontách, předpovědích či zákazech pro nákladní vozidla přímo do sešitu pomocí vestavěného JSON konektoru Power Query — bez kódu, s obnovou podle plánu. Stejný vzor Headers funguje pro každý produkt tohoto API — stačí změnit 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

Klíč API uchovávejte uvnitř M-dotazu (Home → Advanced Editor), ne v buňce listu — Power Query blokuje webový požadavek sestavený z jiného dotazu nebo buňky ("Formula.Firewall"), pokud není úroveň ochrany osobních údajů nastavena na Organizational.

Více hraničních přechodů v jedné tabulce (flotilové dashboardy) — 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 v Excelu nebo naplánovaná obnova v Power BI / Excel Online udržuje čísla aktuální — bez kódu pro dotazování (polling).

Integrace s ERP (BAS / BAF a platformy rodiny 1C)

BAS / BAF a další platformy rodiny 1C mohou volat toto API přímo z naplánované úlohy — HTTPConnection plus ReadJSON, bez mezivrstvy a bez další služby. Nejčastější nasazení udržuje aktuální registr informací s cenami paliv v EU.

Aktualizace registru informací (ceny paliv, všechny země jedním voláním)

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

Tři věci je třeba trefit: předejte New OpenSSLSecureConnection na portu 443, jinak požadavek padne na TLS; volejte /api/v1/data/fuel bez parametru country, aby jeden požadavek vrátil všechny země místo volání na každou zvlášť; a ověřte ok dřív, než sáhnete na data — chyby přicházejí jako ok:false s error.code, ne jako výjimka. Ukázka používá anglickou sadu klíčových slov platformy; lokalizované ekvivalenty (HTTPСоединение, ПрочитатьJSON, РегистрыСведений) se chovají stejně.

Ceny paliv se ve zdrojích mění jednou denně, takže naplánovaná úloha jednou či dvakrát denně stačí a zůstává hluboko v bezplatné kvótě Explorer. Živá data o frontách (queue, multi, border) se mění každých pár minut — ta stahujte vlastním tempem a pomocí multi načtěte až 5 hraničních přechodů jedním požadavkem místo cyklu.

MCP server

Preferujete volání nástrojů před REST? Provozujeme skutečný MCP server (přenos Streamable HTTP), který zpřístupňuje bezpečnou podmnožinu tohoto API pouze pro čtení jako MCP nástroje — stejný API klíč, stejná kvóta, jen jiný přenos.

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

Konfigurace klienta (Claude Desktop / Claude Code):

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

OAuth pro integrace (Home Assistant a další)

Integrace, jejichž uživatelé potřebují každý vlastní klíč (vlastní integrace Home Assistant, desktopové a mobilní aplikace), mohou uživateli umožnit přihlášení místo vkládání klíče. Tok je OAuth 2.0 authorization code pro veřejné klienty s PKCE (S256) — client secret neexistuje. Přístupový token, který vracíme, je vlastní klíč NKD-DEV uživatele, který pak posíláte v hlavičce Bearer přesně jako dosud.

Klienty si nelze vytvořit samoobslužně: požádejte o ně na stránce Integrace, každou integraci kontrolujeme ručně a vydáváme client ID s povolenými přesměrovacími URI. Klíče vydané přes schváleného klienta se okamžitě aktivují pro trhy schválené pro danou integraci. Požádat o klienta integrace →

• Autorizační kód platí 60 sekund, je jednorázový a vázaný na klienta, uživatele, přesměrovací URI a PKCE challenge.
• Klíč se vrací pouze v těle odpovědi s tokenem (access_token) — nikdy v URL. Uchovávejte ho jako heslo.
• expires_in je 30 dní; obnovení vrátí stejný klíč, dokud je aktivní. Pokud uživatel klíč zruší nebo vygeneruje nový, obnovení selže s invalid_grant a volání API vrátí 401 — spusťte opětovnou autentizaci.
• Požadavky mají omezenou frekvenci na IP adresu a denní limit na klienta; chyby odpovídají RFC 6749 (error, error_description).
• Každý uživatel dostane nejvýše vlastní limit zemí: pokud integrace obsahuje více zemí, než má uživatel volných míst, vybere si je na stránce souhlasu (markets=DE,AT v /oauth/authorize je předvybere). Obě odpovědi token vracejí také markets_approved (schválené země uživatele), markets_allowed (jeho limit; null = bez limitu), markets_available (vaše země, které ještě nemá) a upgrade_url (kde přidá „Extra země“).

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

Použijte config_entry_oauth2_flow s LocalOAuth2ImplementationWithPkce (client_secret prázdný) a přesměrovací URI https://my.home-assistant.io/redirect/oauth, které je předem zaregistrováno pro klienty Home Assistant. Klíč čtěte z entry.data["token"]["access_token"] a API dál volejte s hlavičkou Authorization: Bearer. Při odpovědi 401 z API vyvolejte ConfigEntryAuthFailed, aby Home Assistant nabídl opětovnou autentizaci.

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)

Integrace: zobrazte zbývající limity

GET /api/v2/account/usage — Kolik vám právě zbývá z limitů pro klíč, kterým voláte: tarif, limit za sekundu a pro každou třídu denní kvóty (cheap, heavy, route) limit, spotřeba, zbývá a čas resetu (půlnoc UTC); také vaše země tak, jak je vidí tento klíč, a kde přejít na vyšší tarif. Nepočítá se, 30 volání za minutu na klíč.

Klíče integrací (OAuth) mohou vždy volat GET /api/v2/account/usage bez ohledu na produkty povolené integraci. Čísla odpovídají hlavičkám X-Devapi-Limit a X-Devapi-Remaining; X-Devapi-Reset udává čas resetu jako Unix timestamp.

{"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"}}

Když dosáhnete limitu, chyba řekne, kam jít: 429 quota_exceeded vrací také error.reset_at (půlnoc UTC) a error.upgrade_url; 403 market_not_allowed a 403 integration_product_not_allowed vracejí error.upgrade_url. Klíče integrací dostanou také error.pass_url (Trip Pass, níže).

Home Assistant: dotazujte /account/usage nejvýše jednou za 15 minut a zpřístupněte senzor „zbývající volání“ z quotas.cheap.remaining. Mezi dotazy čtěte X-Devapi-Remaining z běžných volání. Při 429 quota_exceeded nebo 403 market_not_allowed vytvořte repair issue s odkazem na error.upgrade_url a pozastavte volání do reset_at.

Trip Pass

Uživatelé integrací si mohou na stránce fakturace koupit Trip Pass (1, 3, 7 nebo 14 dní, jednorázová platba). Dokud je aktivní, klíč integrace dostane všechny země integrace, více volání trasy pro kamiony a dat denně a vyšší frekvenci; produkty integrace, limity předpovědí a zpoždění dat se nemění. Vývojářské klíče téhož účtu se nikdy nezvyšují.

Pro klíče integrace vrací account/usage pass: {active, expires_at, days_left} a pass_url (sekce Trip Pass na stránce fakturace); 429 quota_exceeded a 403 market_not_allowed / integration_product_not_allowed obsahují stejné error.pass_url. Pro jiné klíče jsou obě 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

Vyberte endpoint a zobrazí se jeho úplná dokumentace, parametry, verze a živý sandbox.

Standardní čerpá ze standardní datové kvóty  ·  Těžký čerpá z kvóty prognóz a statistik — viz Kvóty  ·  Trasa pro nákladní vozidla čerpá z vlastní kvóty tras pro nákladní vozidla — viz Kvóty

Fronty na hranici

Předpovědi a statistiky

Palivo a lokace

Směnárny

Cestovní plánování

Logistika

Řidiči a silnice

Your Fleet (NakBus Live)

AI asistent

Ostatní

Export historických dat

Schválení vývojáři si mohou stáhnout publikovanou historii front na hranicích zprůměrovanou po hodinách pro až 5 přechodů (klouzavé okno až 90 dní) jako gzipované CSV, NDJSON nebo JSON. Jde o funkci pouze v portálu — NENÍ to API endpoint; exporty si sestavujete a stahujete v záložce „Export dat“ ve svém účtu.

Přístup udělujeme na vyžádání: založte tiket kategorie Data a napište, které přechody, jaké časové okno a k čemu to chcete použít. Po schválení se ve vašem účtu objeví záložka „Export dat“. Výchozí limit: 1 export denně, až 5 přechodů v každém — o zvýšení si řekněte.

Pole — jeden řádek na hraniční přechod za každou hodinu UTC

Data jsou pouze publikovaná a před exportem procházejí našimi kontrolami anomálií a kvality (žádná surová data jednotlivých hlášení). Všechny časové značky jsou v UTC. Soubory uchováváme 10 dní.

Původ: každý soubor má v hlavičce podepsaný otisk (sha256 + HMAC), takže u libovolné kopie lze i později potvrdit, že jde o pravá data nakordoni.eu, a ověřit, že s nimi nikdo nemanipuloval — i po stažení.

# 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 můžete vytvořit

Tytéž datové produkty vykreslují vizuály na nakordoni.eu — grafy týdenních předpovědí, hodinové profily front, živé stavové karty. Ukázka toho, co obsahují API předpovědí a statistik:

Uvedení zdroje

Integrace plánu Explorer musí zobrazovat viditelný odkaz „Data by nakordoni.eu“ všude, kde se data zobrazují. Díky tomu zůstává bezplatný plán bezplatný.

Přesný kód

Zkopírujte tento úryvek beze změn. Odkaz musí zůstat indexovatelný: viditelný, obyčejný HTML odkaz <a href> vedle dat, který může Google indexovat a sledovat — NEPŘIDÁVEJTE rel="nofollow", rel="sponsored" ani rel="ugc" a neskrývejte jej přes CSS. Odkaz přidaný přes JavaScript je v pořádku, pokud se zobrazí na stránce, kterou Google vykreslí (Podmínky Developer API v1.0, oddíl 8.1).

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

Kompaktní drobná varianta (např. pod grafem nebo widgetem):

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

Můžete odkazovat na svou jazykovou verzi, např. https://nakordoni.eu/cs/ — počítá se jakýkoli viditelný běžný HTML odkaz na nakordoni.eu. Text odkazu "Data by nakordoni.eu" musí zůstat anglicky.

Kam umístit

• Přímo vedle nebo pod blokem dat (tabulka, graf, widget, odpověď) — na stejné obrazovce, viditelné bez dalších kliknutí.
• Na každé stránce nebo obrazovce aplikace, kde se naše data objevují — nejen na stránce "o nás".
• Čitelná velikost a kontrast: alespoň ~11px, neskryté, nesbalené, ne v barvě pozadí.
• Nativní mobilní aplikace bez HTML odkazů: zobrazte text "Data by nakordoni.eu" na obrazovce s daty a klikatelný odkaz umístěte na informační obrazovku.

Atribuci pravidelně ověřujeme na "stránce, kde jsou data použita", kterou jste uvedli při registraci. Chybějící nebo skrytá atribuce v bezplatném plánu Explorer vede nejprve k připomínce, poté k pozastavení klíče. Zákazníci s placeným plánem mohou atribuci vynechat.

Kontrola probíhá zhruba jednou týdně prostřednictvím našeho ověřovacího robota, jehož user agent obsahuje NakordoniComplianceBot/1.0. Otevírá jen stránky uvedené ve vašem panelu vývojáře, nesleduje další odkazy a u těchto stránek ignoruje robots.txt, protože právě jejich kontrolu jste si vyžádali. Pokud ochrana proti botům nebo firewall blokuje neznámé crawlery, povolte tento user agent — pokud stránku neotevřeme, napíšeme vám v tiketu.

Licence dat a trhy

Váš API klíč uděluje licenci k použití našich dat pouze v zemích, které jste deklarovali při registraci. Každou deklaraci ověřujeme před udělením plného přístupu, protože naše data jsou náš vlastní produkt a nelicencujeme je na trhy, aniž bychom věděli, kde budou zveřejněna.

• Deklarujte každou zemi, kterou obsluhuje váš web, aplikace nebo produkt. Seznam můžete kdykoli změnit v panelu; změna vrátí váš účet do kontroly.
• Dokud vaše trhy nejsou schváleny, klíč běží se sníženými limity — polovinou limitu plánu Starter. Platí to bez ohledu na to, jaký plán máte.
• Můžeme schválit pouze některé z požadovaných zemí. Schválený seznam, nikoli ten požadovaný, určuje, které země pokrývá vaše licence.
• Zveřejnění nebo další šíření našich dat na nedeklarovaném trhu, nebo jejich další prodej jako konkurenční datový tok, porušuje tyto podmínky a může bez upozornění pozastavit váš klíč.
• Některé plány jsou dostupné pouze ve vybraných regionech. Dostupnost závisí na trzích, které deklarujete.
• Úplnou dohodou jsou Podmínky Developer API. Mají přednost před tímto shrnutím; závazná je anglická verze.

Aktuálnost dat

Aktuálnost vašich dat závisí na vašem tarifu. V samotné odpovědi není žádné označení — každý tarif vrací stejná pole, stejné typy a stejnou strukturu odpovědi.

• Placené tarify — Student, Starter, Pro a Pro MAX: živá telemetrie, bez zpoždění.
• Bezplatný tarif Explorer: snímek za posledních 15 až 30 minut. Přesný posun se liší požadavek od požadavku.

Zpožděná odpověď nikdy není chyba ani problém s limitem — je to úplná, platná odpověď se staršími čísly. Opakování požadavku novější data nevrátí.

Pokud vaše aplikace potřebuje aktuální data, jakýkoli placený tarif vrací telemetrii v reálném čase.

Získejte svůj bezplatný API klíč