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",
  "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, bad_request, internal_error) a HTTP stavem 401/403/404/429/500. Hlavičky omezení rychlosti X-Devapi-Limit a X-Devapi-Remaining se odesílají u každé měřené odpovědi.

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

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

Fronty na hranici

Předpovědi a statistiky

Palivo a lokace

Cestovní plánování

Řidiči a silnice

Your Fleet (NakBus Live)

AI asistent

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ý: obyčejné HTML <a href>, které mohou vyhledávače následovat — NEPŘIDÁVEJTE rel="nofollow" ani rel="sponsored", nevykreslujte jej pouze JavaScriptem a neskrývejte přes CSS.

<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 každý indexovatelný odkaz na nakordoni.eu. Text kotvy "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 použití dat" uvedené při registraci. Chybějící nebo deindexovaná 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.

Licence dat a trhy

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.
• 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.
• 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.

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íč