API-Dokumentation

Authentifizierung

Jede Anfrage benötigt Ihren API-Schlüssel im Authorization-Header (empfohlen) oder als Parameter ?key=.

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

Antwortformat

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

Fehler geben ok:false mit 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) und HTTP-Status 400/401/403/404/429/500/503/504 zurück. Die Ratenbegrenzungs-Header X-Devapi-Limit und X-Devapi-Remaining werden bei jeder abgerechneten Antwort gesendet. ok:false ist maßgeblich — werten Sie data bei einem fehlgeschlagenen Aufruf niemals aus. Das usage-Objekt ist in jedem abgerechneten Produkt enthalten; /status ist öffentlich und wird nicht abgerechnet, liefert also kein usage.

Kontingente

Tägliche Zähler werden um Mitternacht UTC zurückgesetzt. Sie erhalten eine E-Mail bei 80 % und 100 % des Kontingents.

Kostenpflichtige Tarife heben jedes dieser Limits an. Aktuelle Tarife und ihre Kontingente: Pläne

Codebeispiele

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)

Holen Sie Live-Warteschlangen-, Prognose- oder LKW-Fahrverbotsdaten mit dem integrierten JSON-Connector von Power Query direkt in eine Arbeitsmappe — ohne Code, planmäßig aktualisierbar. Dasselbe Headers-Muster funktioniert für jedes Produkt dieser API — nur die URL ändern.

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

Bewahren Sie den API-Schlüssel innerhalb der M-Abfrage auf (Home → Advanced Editor), nicht in einer Arbeitsblattzelle — Power Query blockiert eine Webanfrage, die aus einer anderen Abfrage oder Zelle aufgebaut wird ("Formula.Firewall"), sofern die Datenschutzstufe nicht auf Organizational gesetzt ist.

Mehrere Grenzübergänge in einer Tabelle (Flotten-Dashboards) — 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 in Excel oder eine geplante Aktualisierung in Power BI / Excel Online hält die Zahlen aktuell — ohne Polling-Code.

ERP-Integration (BAS / BAF und Plattformen der 1C-Familie)

BAS / BAF und andere Plattformen der 1C-Familie können diese API direkt aus einem geplanten Auftrag heraus aufrufen — HTTPConnection plus ReadJSON, ohne Zwischenschicht und ohne zusätzlichen Dienst. Der häufigste Aufbau hält ein Informationsregister mit EU-Kraftstoffpreisen aktuell.

Ein Informationsregister aktualisieren (Kraftstoffpreise, alle Länder in einem Aufruf)

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

Drei Dinge müssen stimmen: New OpenSSLSecureConnection auf Port 443 übergeben, sonst scheitert die Anfrage an TLS; /api/v1/data/fuel ohne country-Parameter aufrufen, damit eine Anfrage alle Länder liefert statt eines Aufrufs pro Land; und ok prüfen, bevor Sie data anfassen — Fehler kommen als ok:false mit error.code zurück, nicht als Ausnahme. Das Beispiel nutzt den englischen Schlüsselwortsatz der Plattform; die lokalisierten Entsprechungen (HTTPСоединение, ПрочитатьJSON, РегистрыСведений) verhalten sich identisch.

Kraftstoffpreise ändern sich an der Quelle einmal täglich, ein geplanter Auftrag ein- oder zweimal am Tag genügt also und bleibt weit innerhalb des kostenlosen Explorer-Kontingents. Live-Wartedaten (queue, multi, border) ändern sich alle paar Minuten — fragen Sie diese nach eigenem Takt ab und lesen Sie mit multi bis zu 5 Grenzübergänge in einer einzigen Anfrage statt in einer Schleife.

MCP-Server

Bevorzugen Sie Tool-Aufrufe statt REST? Wir betreiben einen echten MCP-Server (Streamable-HTTP-Transport), der eine sichere, schreibgeschützte Teilmenge dieser API als MCP-Tools bereitstellt — derselbe API-Schlüssel, dasselbe Kontingent, nur ein anderer 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

Client-Konfiguration (Claude Desktop / Claude Code):

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

OAuth für Integrationen (Home Assistant und andere)

Integrationen, bei denen jeder Nutzer einen eigenen Schlüssel braucht (benutzerdefinierte Home-Assistant-Integrationen, Desktop- und Mobile-Apps), können den Nutzer sich anmelden lassen, statt einen Schlüssel einzufügen. Der Ablauf ist OAuth 2.0 Authorization Code für öffentliche Clients mit PKCE (S256) — es gibt kein Client Secret. Das von uns zurückgegebene Access Token ist der eigene NKD-DEV-Schlüssel des Nutzers, den du anschließend wie bisher als Bearer-Header sendest.

Clients sind keine Selbstbedienung: Beantrage sie auf der Integrationsseite, wir prüfen jede Integration manuell und stellen eine Client-ID mit den erlaubten Redirect-URIs aus. Über einen freigegebenen Client ausgestellte Schlüssel werden sofort für die für diese Integration freigegebenen Märkte aktiviert. Integrations-Client beantragen →

• Der Authorization Code ist 60 Sekunden gültig, einmalig verwendbar und an Client, Nutzer, Redirect-URI und PKCE-Challenge gebunden.
• Der Schlüssel wird nur im Body der Token-Antwort (access_token) zurückgegeben — nie in einer URL. Bewahre ihn wie ein Passwort auf.
• expires_in beträgt 30 Tage; ein Refresh liefert denselben Schlüssel zurück, solange er aktiv ist. Widerruft oder erneuert der Nutzer den Schlüssel, schlägt der Refresh mit invalid_grant fehl und API-Aufrufe liefern 401 — starte die erneute Authentifizierung.
• Anfragen sind pro IP ratenbegrenzt und pro Client täglich gedeckelt; Fehler folgen RFC 6749 (error, error_description).
• Jeder Nutzer erhält höchstens sein eigenes Länderkontingent: Listet Ihre Integration mehr Länder, als der Nutzer frei hat, wählt er sie auf der Zustimmungsseite aus (markets=DE,AT bei /oauth/authorize setzt eine Vorauswahl). Beide Token-Antworten liefern zusätzlich markets_approved (freigegebene Länder des Nutzers), markets_allowed (sein Kontingent; null = unbegrenzt), markets_available (Ihre Länder, die er noch nicht hat) und upgrade_url (wo er „Zusätzliche Länder“ hinzufügt).

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

Verwende config_entry_oauth2_flow mit LocalOAuth2ImplementationWithPkce (client_secret leer) und die Redirect-URI https://my.home-assistant.io/redirect/oauth, die für Home-Assistant-Clients vorregistriert ist. Lies den Schlüssel aus entry.data["token"]["access_token"] und rufe die API weiter mit Authorization: Bearer auf. Bei einem 401 von der API löse ConfigEntryAuthFailed aus, damit Home Assistant die erneute Authentifizierung anbietet.

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)

Integrationen: verbleibende Limits anzeigen

GET /api/v2/account/usage — Was von Ihren Limits gerade übrig ist, für den Schlüssel, mit dem Sie aufrufen: Plan, Limit pro Sekunde und für jede Tageskontingent-Klasse (cheap, heavy, route) Limit, verbraucht, verbleibend und Rücksetzzeit (Mitternacht UTC); außerdem Ihre Länder aus Sicht dieses Schlüssels und wo Sie upgraden. Nicht gezählt, 30 Aufrufe pro Minute pro Schlüssel.

Integrationsschlüssel (OAuth) dürfen GET /api/v2/account/usage immer aufrufen, unabhängig davon, welche Produkte ihre Integration erlaubt. Die Zahlen entsprechen den Headern X-Devapi-Limit und X-Devapi-Remaining; X-Devapi-Reset liefert die Rücksetzzeit als Unix-Zeitstempel.

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

Ist ein Limit erreicht, sagt der Fehler, wohin es geht: 429 quota_exceeded liefert zusätzlich error.reset_at (Mitternacht UTC) und error.upgrade_url; 403 market_not_allowed und 403 integration_product_not_allowed liefern error.upgrade_url. Integrationsschlüssel erhalten außerdem error.pass_url (Trip Pass, unten).

Home Assistant: /account/usage höchstens alle 15 Minuten abfragen und einen Sensor „verbleibende Aufrufe“ aus quotas.cheap.remaining bereitstellen. Zwischen den Abfragen X-Devapi-Remaining aus den normalen Aufrufen lesen. Bei 429 quota_exceeded oder 403 market_not_allowed ein Repair-Issue mit Link auf error.upgrade_url anlegen und Aufrufe bis reset_at pausieren.

Trip Pass

Nutzer von Integrationen können auf der Abrechnungsseite einen Trip Pass kaufen (1, 3, 7 oder 14 Tage, Einmalzahlung). Solange er aktiv ist, erhält der Integrationsschlüssel jedes Land der Integration, mehr Lkw-Routen- und Datenaufrufe pro Tag und eine höhere Rate; Produkte der Integration, Prognose-Limits und Datenverzögerung ändern sich nicht. Entwicklerschlüssel desselben Kontos werden nie angehoben.

Für Integrationsschlüssel liefert account/usage pass: {active, expires_at, days_left} und pass_url (Abschnitt Trip Pass der Abrechnungsseite); 429 quota_exceeded und 403 market_not_allowed / integration_product_not_allowed enthalten dieselbe error.pass_url. Für andere Schlüssel sind beide 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.

Produkte

Wählen Sie einen Endpunkt für die vollständige Referenz, Parameter, Versionen und eine Live-Sandbox.

Standard nutzt das Standard-Datenkontingent  ·  Schwer nutzt das Kontingent für Prognosen und Statistiken — siehe Kontingente  ·  Lkw-Route nutzt ein eigenes Lkw-Routen-Kontingent — siehe Kontingente

Grenzwarteschlangen

Prognosen & Statistiken

Kraftstoff & Standorte

Wechselstuben

Reiseplanung

Logistik

Fahrer & Straßen

Your Fleet (NakBus Live)

KI-Assistent

Sonstiges

Export historischer Daten

Freigegebene Entwickler können die veröffentlichte, stündlich gemittelte Historie der Grenzwarteschlangen für bis zu 5 Grenzübergänge (rollierendes Fenster bis 90 Tage) als gzip-komprimiertes CSV, NDJSON oder JSON herunterladen. Das ist eine reine Portalfunktion — KEIN API-Endpunkt; Sie erstellen und laden Exporte im Tab „Datenexport“ in Ihrem Konto.

Der Zugang wird auf Anfrage gewährt: Öffnen Sie ein Data-Ticket und nennen Sie uns die Grenzübergänge, den Zeitraum und den geplanten Verwendungszweck. Nach der Freigabe erscheint der Tab „Datenexport“ in Ihrem Konto. Standardlimit: 1 Export/Tag mit je bis zu 5 Grenzübergängen — bitten Sie uns um eine Anhebung.

Felder — eine Zeile pro Grenzübergang und UTC-Stunde

Exportiert werden ausschließlich veröffentlichte Daten, die zuvor unsere Anomalie- und Datenqualitätsprüfungen durchlaufen haben (keine Rohdaten einzelner Meldungen). Alle Zeitstempel sind UTC. Dateien werden 10 Tage aufbewahrt.

Herkunft: Jede Datei enthält im Header einen signierten Fingerabdruck (sha256 + HMAC), sodass jede Kopie später als echte nakordoni.eu-Daten bestätigt und auf Manipulation geprüft werden kann — auch nach dem Download.

# 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

Was Sie bauen können

Dieselben Datenprodukte rendern die Visualisierungen auf nakordoni.eu — wöchentliche Prognosediagramme, stündliche Warteschlangenprofile, Live-Statuskarten. Ein Vorgeschmack darauf, was die Prognose- und Statistik-APIs enthalten:

Attribution

Integrationen im Explorer-Plan müssen einen sichtbaren Link "Data by nakordoni.eu" überall dort anzeigen, wo die Daten dargestellt werden. Das hält den kostenlosen Plan kostenlos.

Der genaue Code

Kopieren Sie dieses Snippet unverändert. Der Link muss indexierbar bleiben: ein sichtbarer, einfacher HTML-Link <a href> neben den Daten, den Google indexieren und dem er folgen kann — fügen Sie KEIN rel="nofollow", rel="sponsored" oder rel="ugc" hinzu und verstecken Sie ihn nicht per CSS. Ein per JavaScript eingefügter Link ist in Ordnung, wenn er auf der von Google gerenderten Seite erscheint (Developer API Terms v1.0, Abschnitt 8.1).

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

Kompakte Kleingedruckt-Variante (z. B. unter einem Diagramm oder Widget):

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

Sie können stattdessen auf Ihre Sprachversion verlinken, z. B. https://nakordoni.eu/de/ — jeder sichtbare, einfache HTML-Link auf nakordoni.eu zählt. Der Ankertext "Data by nakordoni.eu" muss auf Englisch bleiben.

Wo platzieren

• Direkt neben oder unter dem Datenblock (Tabelle, Diagramm, Widget, Antwort) — auf demselben Bildschirm, sichtbar ohne zusätzliche Klicks.
• Auf jeder Seite bzw. jedem App-Screen, wo unsere Daten erscheinen — nicht nur auf einer "Über uns"-Seite.
• Lesbare Größe und Kontrast: mindestens ~11px, nicht versteckt, nicht eingeklappt, nicht in Hintergrundfarbe.
• Native Mobile-Apps ohne HTML-Links: Text "Data by nakordoni.eu" auf dem Datenbildschirm anzeigen und den antippbaren Link auf dem Info-Screen platzieren.

Wir prüfen die Attribution regelmäßig auf der bei der Registrierung angegebenen "Seite, auf der die Daten verwendet werden". Fehlende oder versteckte Attribution im kostenlosen Explorer-Plan führt zunächst zu einer Erinnerung, danach zur Sperrung des Schlüssels. Kunden mit kostenpflichtigem Plan dürfen auf die Attribution verzichten.

Die Prüfung erfolgt etwa einmal pro Woche durch unseren Prüfdienst, dessen User-Agent NakordoniComplianceBot/1.0 enthält. Er ruft nur die in Ihrem Entwickler-Dashboard eingetragenen Seiten auf, folgt keinen weiteren Links und beachtet für diese Seiten keine robots.txt, da Sie genau diese Seiten zur Prüfung angegeben haben. Sperrt ein Bot-Schutz oder eine Firewall unbekannte Crawler, lassen Sie diesen User-Agent zu — können wir eine Seite nicht öffnen, melden wir uns per Ticket.

Datenlizenz und Märkte

Ihr API-Schlüssel gewährt eine Lizenz zur Nutzung unserer Daten ausschließlich in den Ländern, die Sie bei der Anmeldung angegeben haben. Wir prüfen jede Angabe, bevor wir vollen Zugriff gewähren, denn unsere Daten sind unser eigenes Produkt, und wir lizenzieren es nicht in Märkte, ohne zu wissen, wo es veröffentlicht wird.

• Geben Sie jedes Land an, das Ihre Website, App oder Ihr Produkt bedient. Sie können die Liste jederzeit über Ihr Dashboard ändern; eine Änderung stellt Ihr Konto erneut zur Prüfung.
• Bis Ihre Märkte genehmigt sind, läuft Ihr Schlüssel mit reduzierten Limits – der Hälfte des Starter-Kontingents. Dies gilt unabhängig davon, welchen Plan Sie gebucht haben.
• Wir können nur einige der von Ihnen angeforderten Länder genehmigen. Die genehmigte Liste – nicht die angeforderte – definiert, welche Länder Ihre Lizenz abdeckt.
• Die Veröffentlichung oder Weiterverbreitung unserer Daten in einem nicht deklarierten Markt oder deren Weiterverkauf als konkurrierender Datenfeed verstößt gegen diese Bedingungen und kann Ihren Schlüssel ohne Vorankündigung sperren.
• Einige Pläne sind nur in ausgewählten Regionen verfügbar. Die Verfügbarkeit hängt von den von Ihnen deklarierten Märkten ab.
• Die vollständige Vereinbarung sind die Developer-API-Bedingungen. Sie haben Vorrang vor dieser Zusammenfassung; verbindlich ist die englische Fassung.

Datenaktualität

Wie aktuell Ihre Daten sind, hängt von Ihrem Tarif ab. In der Antwort selbst gibt es keine Kennzeichnung — jeder Tarif liefert dieselben Felder, dieselben Typen und dieselbe Antwortstruktur.

• Bezahltarife — Student, Starter, Pro und Pro MAX: Live-Telemetrie, ohne Verzögerung.
• Kostenloser Explorer-Tarif: eine Momentaufnahme der letzten 15 bis 30 Minuten. Der genaue Versatz ist von Anfrage zu Anfrage unterschiedlich.

Eine verzögerte Antwort ist niemals ein Fehler und niemals ein Kontingentproblem — sie ist eine vollständige, gültige Antwort mit älteren Zahlen. Ein erneuter Aufruf liefert keine neueren Daten.

Wenn Ihre Anwendung aktuelle Daten benötigt, liefert jeder Bezahltarif Echtzeit-Telemetrie.

Kostenlosen API-Schlüssel erhalten