Documentazione dell'API

Autenticazione

Ogni richiesta necessita della tua chiave API nell'header Authorization (consigliato) o come parametro ?key=.

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

Envelope di risposta

{
  "ok": true,
  "api_version": "v1",
  "product": "queue",
  "attribution": "Data by nakordoni.eu",
  "data": { ... },
  "usage": { "limit": 1000, "used": 42, "reset": "2026-06-06T00:00:00Z" }
}

Gli errori restituiscono ok:false con error.code (missing_api_key, invalid_api_key, qps_exceeded, quota_exceeded, unknown_product, product_unavailable, bad_request, internal_error) e stato HTTP 401/403/404/429/500. Gli header di rate-limit X-Devapi-Limit e X-Devapi-Remaining vengono inviati a ogni risposta conteggiata.

Quote

I contatori giornalieri si azzerano a mezzanotte UTC. Ricevi un'e-mail all'80% e al 100% della quota.

Esempi di codice

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"])

Server MCP

Preferisci le chiamate agli strumenti invece di REST? Gestiamo un vero server MCP (trasporto Streamable HTTP) che espone un sottoinsieme sicuro, di sola lettura, di questa API come strumenti MCP — stessa chiave API, stessa quota, solo un trasporto diverso.

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

Configurazione client (Claude Desktop / Claude Code):

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

Prodotti

Pick an endpoint for its full reference, parameters, versions and a live sandbox.

Standard utilizza la quota dati standard  ·  Pesante utilizza la quota di previsioni e statistiche — vedi Quote

Code di frontiera

Previsioni e statistiche

Carburante e luoghi

Pianificazione del viaggio

Autisti e strade

Assistente AI

Other

History data export

Approved developers can download hourly-averaged, published border-queue history for up to 5 checkpoints (rolling window up to 90 days) as gzipped CSV, NDJSON, or JSON. This is a portal-only feature — NOT an API endpoint; you build and download exports from the "Data export" tab in your account.

Access is granted on request: open a Data ticket telling us which checkpoints, the time window, and your intended use. Once approved, the Data export tab appears in your account. Default limit: 1 export/day, up to 5 checkpoints each — ask us to raise it.

Fields — one row per checkpoint per UTC hour

Data is published-only and passes our anomaly / data-quality checks before export (no raw per-report data). All timestamps are UTC. Files are kept for 10 days.

Provenance: every file embeds a signed fingerprint (sha256 + HMAC) in its header, so any copy can later be confirmed as genuine nakordoni.eu data and checked for tampering — even after 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

Cosa puoi creare

Gli stessi prodotti di dati generano gli elementi visivi di nakordoni.eu — grafici di previsione settimanali, profili orari delle code, schede di stato in tempo reale. Un assaggio di ciò che contengono le API di previsioni e statistiche:

Attribuzione

Le integrazioni del piano Explorer devono mostrare un link visibile "Data by nakordoni.eu" ovunque vengano visualizzati i dati. È ciò che mantiene gratuito il piano gratuito.

Il codice esatto

Copia questo frammento così com'è. Il link deve restare indicizzabile: un semplice <a href> HTML che i motori di ricerca possono seguire — NON aggiungere rel="nofollow" o rel="sponsored", non renderizzarlo solo via JavaScript e non nasconderlo con CSS.

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

Variante compatta in piccolo (es. sotto un grafico o widget):

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

Puoi linkare la tua versione linguistica, es. https://nakordoni.eu/it/ — conta qualsiasi link indicizzabile a nakordoni.eu. Il testo àncora "Data by nakordoni.eu" deve restare in inglese.

Dove posizionarlo

• Direttamente accanto o sotto il blocco dati (tabella, grafico, widget, risposta) — sulla stessa schermata, visibile senza clic aggiuntivi.
• Su ogni pagina o schermata dell'app dove compaiono i nostri dati — non solo su una pagina "chi siamo".
• Dimensione e contrasto leggibili: almeno ~11px, non nascosto, non compresso, non del colore dello sfondo.
• App mobili native senza link HTML: mostra il testo "Data by nakordoni.eu" nella schermata dei dati e metti il link cliccabile nella schermata informazioni.

Verifichiamo periodicamente l'attribuzione sulla "pagina di utilizzo dei dati" indicata alla registrazione. Attribuzione mancante o deindicizzata nel piano Explorer porta prima a un promemoria, poi alla sospensione della chiave. I clienti Pay As You Grow possono ometterla.

Ottieni la tua chiave API gratuita