Documentazione dell'API

REST + JSON su HTTPS. Un URL di base, una chiave, envelope prevedibili.

URL di base	`https://nakordoni.eu/api/v1/data/`
Formato	JSON, UTF-8
Auth	`Authorization: Bearer NKD-DEV-…`
Versionamento	Versionato nel percorso (v1). Modifiche non retrocompatibili solo con una nuova versione; le risposte v1 restano stabili.

In questa pagina

Autenticazione · Envelope di risposta · Quote · Esempi di codice · Prodotti · Attribuzione · Cosa puoi creare

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

	Explorer	Pay As You Grow
chiamate/giorno sulle API di dati standard	1,000	50,000
chiamate/giorno sulle API di previsioni e statistiche	200	10,000
QPS	2	20

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, usage } = await res.json();
if (!ok) throw new Error(data?.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"])

Prodotti

Stato API

Stato in tempo reale di ogni prodotto Developer API: online / degradato / offline, latenza di risposta e ora dell'ultima verifica. Pubblico — non richiede chiave API.

GET https://nakordoni.eu/api/v1/data/status — classe di quota: cheap

curl "https://nakordoni.eu/api/v1/data/status" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

API Elenco Valichi di Frontiera Online

Elenco di tutti i valichi di frontiera monitorati: ID, nomi, paesi, coordinate e stato. Usalo per scoprire i valori ppid per le altre API.

GET https://nakordoni.eu/api/v1/data/checkpoints — classe di quota: cheap

Parametro	Descrizione
`country`	Filtra per codice paese numerico (1=UA, 2=PL, 3=SK, 4=HU, 5=RO, 6=MD, 7=BY, 8=LT, 9=LV, …)
`lang`	Lingua dei nomi dei valichi (predefinito en)

curl "https://nakordoni.eu/api/v1/data/checkpoints" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

API code al confine Online

Tutti i valichi su un confine dato + tipo di veicolo in una sola chiamata. Supporta destinazione singola, elenco separato da virgole o "all". Risultati ordinati per lunghezza della coda.

GET https://nakordoni.eu/api/v1/data/border/1/all/4 — classe di quota: heavy

Parametro	Descrizione
`origin`	Codice paese di origine (segmento URL): 1=Ucraina, 2=Polonia, 3=Slovacchia, 4=Ungheria, 5=Romania…
`destination`	Destinazione: codice singolo, elenco separato da virgole o "all" per tutti i vicini
`crossing_type`	Tipo veicolo: 4=auto, 5=auto (esenzione), 6=autobus, 7=pedoni, 8=autocarro <7.5t, 9=autocarro
`lang`	Lingua per i nomi dei valichi nella risposta (predefinito en)

curl "https://nakordoni.eu/api/v1/data/border/1/all/4" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

API ricerca valichi di frontiera Online

Trova i PPID dei valichi per nome in qualsiasi lingua. Restituisce tutti i PPID per quella posizione raggruppati per tipo di veicolo. Fino a 20 nomi per richiesta.

GET https://nakordoni.eu/api/v1/data/search — classe di quota: cheap

Parametro	Descrizione
`name`	Nome o elenco separato da virgole (max 20), in qualsiasi lingua
`lang`	Lingua dei nomi restituiti (predefinito en)

curl "https://nakordoni.eu/api/v1/data/search?name=Krakovets,Shehyni&lang=en" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

API Coda di Frontiera in Tempo Reale Online

Code in tempo reale, stima del tempo di attesa e stato per qualsiasi valico monitorato. Include un blocco snapshot: coda attuale (queue_now), tempo di attesa stimato wait_min = tmin + coda × tpercar, anzianità dei dati e fonte.

GET https://nakordoni.eu/api/v1/data/queue — classe di quota: heavy

Parametro	Descrizione
`ppid`	ID del valico, ad es. id_13 (vedi /api/v1/data/checkpoints)
`section`	Sezione dati (opzionale)
`origin`	Codice paese di origine (opzionale)
`destination`	Codice paese di destinazione (opzionale)

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

API Statistiche Orarie dei Valichi Online

Statistiche storiche orarie della coda per valico e data: 24 valori orari, media/min/max giornaliere, ore di punta e ore più tranquille, confronto giorno su giorno.

GET https://nakordoni.eu/api/v1/data/stats — classe di quota: heavy

Parametro	Descrizione
`ppid`	ID del valico
`date`	YYYY-MM-DD (predefinito: ieri)
`compare`	1 = includi il giorno precedente + delta
`lang`	Codice lingua (predefinito uk)

curl "https://nakordoni.eu/api/v1/data/stats?ppid=id_15&date=2026-06-01&compare=1" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

API "Momento migliore per attraversare" Online

Statistiche settimana tipica per checkpoint: matrice 7×24 giorno-settimana×ora (mediana + banda p25/p75), giorno più tranquillo/trafficato, migliori/peggiori finestre da 2 ore.

GET https://nakordoni.eu/api/v1/data/day-stats — classe di quota: cheap

Parametro	Descrizione
`ppid`	ID checkpoint
`lang`	Codice lingua

curl "https://nakordoni.eu/api/v1/data/day-stats?ppid=id_13&lang=en" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

API Previsione delle Code Online

Previsione tramite ensemble ML dei livelli di coda: orizzonti di 24 ore e 7 giorni (168h) con intervalli di confidenza. Lo stesso modello che alimenta le previsioni di nakordoni.eu.

GET https://nakordoni.eu/api/v1/data/forecast — classe di quota: heavy

Parametro	Descrizione
`ppid`	ID del valico
`prediction_steps`	24 (predefinito) o 168 per 7 giorni

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

API Valichi Alternativi Online

Valichi alternativi nelle vicinanze sullo stesso confine con le code attuali e gli scarti di distanza.

GET https://nakordoni.eu/api/v1/data/alternatives — classe di quota: cheap

Parametro	Descrizione
`ppid`	ID del valico
`lang`	Codice lingua
`crossing_type`	Sostituire il filtro tipo veicolo — es. 4=auto, 6=bus, 7=pedone, 9=camion
`limit`	Max risultati da restituire (predefinito 5)

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

API Freschezza dei Dati Online

Quando un valico è stato aggiornato l'ultima volta, da quale fonte, e una valutazione della freschezza.

GET https://nakordoni.eu/api/v1/data/update-info — classe di quota: cheap

Parametro	Descrizione
`ppid`	ID del valico
`lang`	Codice lingua

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

API Prezzi dei Carburanti UE Online

Prezzi medi di benzina/diesel/GPL nei paesi dell'UE oltre alle stazioni più vicine, aggregati da fonti nazionali ufficiali.

GET https://nakordoni.eu/api/v1/data/fuel — classe di quota: cheap

Parametro	Descrizione
`country`	Codice paese ISO (opzionale)
`lat`	Latitudine (opzionale)
`lon`	Longitudine (opzionale)
`lang`	Codice lingua

curl "https://nakordoni.eu/api/v1/data/fuel?country=PL" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

API Punti di Interesse per Conducenti Online

Parcheggi per camion (14k+), docce gratuite, servizi e supermercati in tutta Europa con coordinate.

GET https://nakordoni.eu/api/v1/data/pois — classe di quota: cheap

Parametro	Descrizione
`type`	parking\|shower\|supermarket\|industrial
`lat`	Latitudine
`lon`	Longitudine
`radius`	Raggio km

curl "https://nakordoni.eu/api/v1/data/pois?type=parking&lat=50.7&lon=23.9&radius=50" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

API Divieti di Circolazione per Camion Online

Restrizioni europee alla circolazione dei camion per paese e data, inclusi divieti stagionali e festivi.

GET https://nakordoni.eu/api/v1/data/truck-bans — classe di quota: cheap

Parametro	Descrizione
`country`	Codice paese ISO (opzionale)
`date`	YYYY-MM-DD (opzionale)

curl "https://nakordoni.eu/api/v1/data/truck-bans?country=PL" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

API Domeniche di Apertura Online

Normative sull'apertura domenicale dei negozi e prossime domeniche di apertura per paese UE regolamentato.

GET https://nakordoni.eu/api/v1/data/trading-sundays — classe di quota: cheap

Parametro	Descrizione
`country`	Codice paese ISO (opzionale)

curl "https://nakordoni.eu/api/v1/data/trading-sundays?country=PL" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

API Meteo di Frontiera Coming soon

Condizioni attuali e allerte stradali ai valichi di frontiera. (Prossimamente)

GET https://nakordoni.eu/api/v1/data/weather — classe di quota: cheap

Parametro	Descrizione
`ppid`	ID del valico

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

API Statistiche di Frontiera dei Vettori di Autobus Online

Prestazioni di attraversamento della frontiera per vettore di autobus: attraversamenti, minuti di attesa medi/mediani/min/max — costruite a partire dai nostri registri di attraversamento abbinati alle targhe.

GET https://nakordoni.eu/api/v1/data/bus-carriers — classe di quota: cheap

Parametro	Descrizione
`ppid`	ID del valico o "all" per aggregato
`days`	Periodo 1-90 (predefinito 30)
`min_crossings`	Numero minimo di attraversamenti per includere un vettore (predefinito 3)
`limit`	Numero massimo di vettori restituiti (predefinito 20)

curl "https://nakordoni.eu/api/v1/data/bus-carriers?ppid=all&days=30" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

API Condizioni Stradali Online

Segnalazioni approvate sulle condizioni stradali vicino ai confini e sui principali corridoi: buche, lavori in corso, chiusure, ghiaccio, pericoli — combinando le segnalazioni dei conducenti con le rilevazioni automatiche dell'accelerometro della nostra app di navigazione.

GET https://nakordoni.eu/api/v1/data/road-conditions — classe di quota: cheap

Parametro	Descrizione
`country`	Codice paese ISO (opzionale)
`condition_type`	pothole\|speed_bump\|roadwork\|closure\|hazard\|ice\|… (opzionale)
`severity`	low\|moderate\|major\|critical (opzionale)
`lat`	Latitudine (opzionale)
`lng`	Longitudine (opzionale)
`radius`	Raggio km (predefinito 50)
`limit`	Risultati massimi (predefinito 100, limite 500)

curl "https://nakordoni.eu/api/v1/data/road-conditions?country=UA&severity=major" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

API Assistente IA di Frontiera Online

Poni al nostro assistente IA di produzione qualsiasi domanda sull'attraversamento delle frontiere (code, previsioni, regole, carburante, itinerari) e ottieni la stessa risposta fondata che alimenta il widget di nakordoni.eu — in 24 lingue. Già usato in produzione da yaknakordoni.com.ua.

GET https://nakordoni.eu/api/v1/data/assistant — classe di quota: heavy

Parametro	Descrizione
`q`	La domanda (testo semplice)
`lang`	Lingua della risposta (predefinito en)
`ppid`	Contesto del valico, ad es. id_13 (opzionale)

curl "https://nakordoni.eu/api/v1/data/assistant?q=How long is the queue at Krakovets now?&lang=en&ppid=id_13" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

API Qualità delle Strade Coming soon

Punteggi di irregolarità stradale per corridoio calcolati da telemetria dell'accelerometro anonimizzata di percorsi reali: indice di irregolarità 0-100, densità di buche per km, raggruppamenti di corridoi dissestati con coordinate. (Prossimamente)

GET https://nakordoni.eu/api/v1/data/road-quality — classe di quota: heavy

Parametro	Descrizione
`bbox`	Riquadro di delimitazione
`corridor`	Corridoio dell'itinerario

curl "https://nakordoni.eu/api/v1/data/road-quality?bbox=22.5,48.2,24.5,50.5" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

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:

7-day border queue forecast chart built from the Forecast API — Previsione settimanale + profilo orario del giorno più trafficato — Forecast API (prediction_steps=168 / 24)

Hourly queue statistics chart built from the Statistics API — Grafico orario delle code per valico — Statistics API (stats?ppid=…&compare=1)

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