Note di rilascio API

Novità: un vero server MCP all'indirizzo https://nakordoni.eu/mcp, che espone un sottoinsieme sicuro, di sola lettura, dell'API (status, checkpoints, border queue, live queue, forecast) come strumenti MCP. Stessa chiave API e stessa quota dell'API REST. Scheda del server all'indirizzo /.well-known/mcp/server-card.json. Vedi la sezione Server MCP nella documentazione.

The retitle to "Live Queue & Freshness API" below did not actually reach the docs page. The page renders each product title through a translation lookup that falls back to the endpoint's title only when no translation exists — and a translation already existed, frozen at the old name, in all 25 UI languages. It now wins over any future update to the underlying title until it is updated too.

Retitled the translation key in all 25 languages so the docs page matches. No endpoint, parameter or response change — title text only.

If you poll live queue data frequently, you may be spending heavy quota you do not need to. /update-info is standard-class and already returns the live figure:

GET /api/v1/data/update-info?ppid=id_13

It returns queue_now, freshness, age_minutes, is_realtime, status, timestamp and timezone. Use it for the frequent refresh against your standard daily quota, and keep /queue, /multi and /forecast (all heavy-class) for when you need wait_min, the trend fields or history.

Nothing changed in the endpoint itself — only its documentation. It was listed as the "Data Freshness API" and its description mentioned only the freshness rating, never queue_now, so it was easy to miss. It is now titled "Live Queue & Freshness API" with the returned fields spelled out. Thanks to the developer who raised this.

Some failed requests were returning HTTP 200 with ok: true and the error buried inside data — so the documented if (!ok) throw pattern could not detect them, and the call was still billed. Affected calls now return HTTP 400 with ok: false and a proper error.code / error.message, as documented. Seen on fuel-cities with an unsupported country and travel-matrix with malformed coordinates.

Separately, a missing required parameter returned 500 internal_error instead of 400 bad_request (an upstream 4xx body was being discarded before its status was read). It now returns 400 bad_request with the upstream message — e.g. search without ?name=.

Successful responses are byte-for-byte unchanged — same fields, same params, same quota cost. If your client already branches on ok, no change is needed. If it ignored ok and read data directly, it will now see error envelopes on calls that were always failing.

Fixed a bug where /multi could return a wrong queue count for some checkpoints — mainly Balkan and Hungary–Serbia crossings — whenever its cache was cold. The fallback read a table that, for those crossings, holds no queue data, and reported unrelated values as car counts. Measured examples: a checkpoint with 12 cars reported 6, and several with real queues reported 0.

Three changes you may notice:

• found: false now means there is genuinely no recent queue data. Previously you could receive found: true with a fabricated queue_now: 0.
• wait_status, trend_percent and trend_direction are now returned on cold requests — they were null before.
• The endpoint also falls back when its cached snapshot is stale (older than 24h), not only when it is missing.

No changes to request parameters, quota cost or response shape.

Corretto un bug per cui ogni chiamata a /multi veniva addebitata due volte — una volta da un controllo generico da 1 unità e una seconda volta dalla formula di costo variabile dell'endpoint (N PPID × sotto-prodotti). Ora una chiamata costa esattamente ⌈(N×M)/2⌉ unità come documentato, senza addebiti aggiuntivi.

È stato inoltre aggiunto un badge di classe quota (Standard/Heavy) su ogni prodotto nella pagina della documentazione, così da capire subito quale quota giornaliera utilizza un endpoint.

country e countries uniti in un unico parametro (1-15 codici separati da virgole). Nuovo parametro compare_to: confronto tra giorni festivi uguali o diversi tra i paesi, si combina con upcoming+days. lang ora accetta più lingue (aggiunge un oggetto names). days=0 o omesso ora significa nessun limite in modalità upcoming.

Giorni festivi ufficiali per ogni paese europeo — date, nomi locali e tipo. Basato sullo stesso servizio Nager.Date / OpenHolidaysAPI (con un calendario del Kosovo calcolato localmente) che alimenta la pagina del calendario dei giorni festivi di nakordoni.eu e i fattori calendariali del sistema di previsione.

• ?country=PL&year=2026 — elenco dei giorni festivi dell'intero anno per un paese
• ?upcoming=1&days=30 — elenco semplice dei prossimi giorni festivi tra i paesi
• Senza parametri — indice di un insieme di paesi principali con il prossimo giorno festivo di ciascuno

Aggiunto il prodotto currency — tassi di cambio basati sull'EUR per PLN, CZK, HUF, USD, GBP, CHF, NOK e UAH, forniti da Frankfurter (ECB) e memorizzati in cache per 6 ore. Nessun parametro, restituisce sempre la tabella completa dei tassi. Vedi la documentazione.

Integra i divieti di circolazione dei camion in Europa in tempo reale sul tuo sito web — un widget iframe gratuito con 3 design (light, dark, board), 5 lingue (en, uk, pl, de, ru), un filtro opzionale per paese e uno stato «attivo ora» in tempo reale. Nessuna chiave API necessaria. Configura e copia il codice su nakordoni.eu/en/for_truck_drivers/traffic_bans/widget. Preferisci i dati grezzi? Il prodotto API truck-bans e il feed JSON pubblico restano disponibili.

Tre aggiunte, tutte retrocompatibili — v1 è invariata.

Versionamento per endpoint. Ora esiste un URL di base /api/v2/. È per endpoint: solo gli endpoint che sono effettivamente cambiati si comportano diversamente in v2; ogni altro endpoint serve in modo trasparente la sua risposta v1 (quindi /api/v2/data/queue = gli stessi dati di v1, solo con "api_version":"v2"). Non è necessario migrare gli endpoint che funzionano.

border v2 è direzionale. L'ordine del percorso è la direzione di viaggio:

GET /api/v2/data/border/1/2/6   → buses UA→PL (Ukrainian-side crossings)
GET /api/v2/data/border/2/1/6   → buses PL→UA (Polish-side crossings)

Ogni checkpoint ottiene inoltre un oggetto direction {from,to} e un booleano stale, e ?max_age_min=N restituisce solo i passaggi aggiornati di recente. (In v1 border restituisce comunque entrambi i lati del confine indipendentemente dall'ordine — invariato.)

Sandbox interattivo. Gli sviluppatori autenticati possono ora provare qualsiasi endpoint dal browser su Sviluppatori → Sandbox — scegli un endpoint, una versione e una delle tue chiavi, modifica i parametri e vedi la risposta in tempo reale. I test nel Sandbox hanno un proprio budget giornaliero separato (50 chiamate/giorno) e non intaccano mai la tua quota API reale.

La documentazione è ora suddivisa per endpoint (Sviluppatori → Documentazione API) con un selettore di versione sugli endpoint che ne hanno più di una.

Due nuovi fattori integrati nella formula del tempo di attesa, oltre agli aggiustamenti esistenti section_mode e meteo:

• service_rate — auto/min attualmente in elaborazione, misurate rispetto alla velocità di riferimento configurata del checkpoint. Moltiplicativo, limitato tra 0.5x e 1.5x.
• shift_change — impatto del cambio turno delle guardie di frontiera alle 08:00/20:00, proprio di ciascun checkpoint. Additivo (minuti), non moltiplicativo — applicato solo entro +/-60 minuti da un cambio turno, richiede una cronologia minima di campioni, limitato a +/-120 minuti.

advanced_wait_min è ora round(base_wait × section_mode × weather × service_rate) + shift_change.adjustment_min. Entrambi i fattori si riflettono anche in driver_reported.prognosed_advanced_wait_min per i confronti storici.

Nell'ambito di una revisione di sicurezza e privacy, i seguenti campi sono stati rimossi — esponevano dettagli implementativi interni (la tassonomia delle nostre fonti dati a monte, gli ID delle righe del DB, annotazioni interne della pipeline, campi inutilizzati o morti) senza reale valore per il prodotto:

• id e corrected — rimossi dagli oggetti riga di queue
• tmin/tpercar — rimossi da queue, border e multi (le costanti della formula del tempo di attesa; i valori già calcolati wait_min/wait_time non sono interessati)
• source (stringa grezza, ad es. "line") — rimosso da queue, multi e update-info. Il blocco update_info di update-info e di multi mantiene comunque source_category/source_label_en (un piccolo vocabolario pubblico); il blocco queue di queue e di multi non contiene più alcun campo source
• traffic_status — rimosso da border; era sempre null e non veniva mai popolato da nessuna parte del sistema

Se la tua integrazione legge uno di questi campi, aggiornala — consulta l'elenco attuale dei campi nella pagina di documentazione del prodotto pertinente.

L'utilizzo della quota giornaliera (usage.used in ogni risposta) ora può essere un valore decimale (ad es. 67.5) invece di essere sempre un numero intero. Si tratta di un effetto collaterale della fatturazione di queue-advanced a una tariffa frazionaria — vedi sotto. usage.limit non è interessato ed è sempre un numero intero. Se il tuo client tipizza rigorosamente usage.used come intero, allargalo per accettare un decimale / float.

Questi tre prodotti ora restituiscono gli stessi campi di stato in tempo reale mostrati dal sito web: wait_status (green/yellow/red, basato sulla cronologia recente di questo checkpoint) e trend_percent/trend_direction (up/up-slight/down/down-slight/stable, confrontando le ultime 3 ore). Puramente additivo.

Le righe data[] di /api/v1/data/queue avevano in precedenza wait_time: null per la maggior parte delle fonti — solo alcuni feed a monte riportano direttamente un tempo di attesa. Le righe che non ne hanno uno ora ricevono la stima standard tmin + queue×tpercar, contrassegnata da un nuovo booleano wait_time_estimated così puoi distinguere un valore realmente riportato da uno calcolato.

queue-advanced ora costa 1.5 units per chiamata invece di 1 (a riflettere le ulteriori ricerche di traffico, meteo e segnalazioni dei conducenti che effettua) — vedi usage.used sopra. La risposta inoltre non include più tmin, tpercar o total_crossing_time, e driver_reported ora è solo {wait_min, ts, age_min} — i precedenti campi di confronto previsione/realtà (prognosed_wait_min, diff_min, historical_section_mode, historical_weather, ecc.) sono stati rimossi. section_mode, weather, advanced_wait_min ed exceeds_crossing_time sono invariati.

/api/v1/data/truck-bans ora restituisce, per ogni paese in bans_by_country, uno status (active/clear) più active_window, next_window, local_time e tz — calcolati nel fuso orario proprio di quel paese, così non devi più valutare tu stesso le finestre di divieto grezze rispetto a un orologio. La risposta aggiunge inoltre una lista covered_countries di livello superiore e un timestamp UTC as_of.

GET /api/v1/data/truck-bans?country=PL

Puramente additivo — i campi esistenti current_bans/upcoming_bans/bans_by_country sono invariati. Un ?country= sconosciuto ora restituisce un risultato vuoto con countries_not_covered invece dei divieti di ogni paese.

Un nuovo prodotto opzionale che regola il tempo di attesa standard in base al flusso di traffico in tempo reale e al meteo. Restituisce il dettaglio completo di ogni aggiustamento.

GET /api/v1/data/queue-advanced?ppid=id_13

Concesso su richiesta — apri un ticket Data dalla tua dashboard per attivarlo.

/api/v1/data/border ora calcola correttamente wait_min (e restituisce tmin/tpercar) per ogni checkpoint nella risposta, in linea con i prodotti queue e multi. In precedenza questo campo era sempre null.

/api/v1/data/forecast ora utilizza in modo affidabile il modello ensemble v4 per qualsiasi valore di prediction_steps (in precedenza alcuni orizzonti non standard potevano ricadere silenziosamente su un modello più vecchio). Anche il fattore meteo che alimenta l'ensemble è stato corretto e ora riflette realmente le condizioni in tempo reale (pioggia, neve, vento, nebbia) invece di segnalare sempre non disponibile.

Gli sviluppatori approvati possono ora scaricare i dati storici delle code alle frontiere, mediati su base oraria, per un massimo di 5 checkpoint (finestra mobile fino a 90 giorni) in formato CSV o NDJSON dalla nuova scheda Data export. I dati sono solo pubblicati e verificati nella qualità; i timestamp sono in UTC. Ti serve l'accesso? Apri un ticket Data.

Non hai ancora un sito web? Ora puoi creare un account sviluppatore descrivendo dove e come intendi utilizzare i nostri dati, invece di essere obbligato a inserire l'URL di una pagina online. Aggiungi l'URL reale in seguito dalla tua dashboard (Account & dati → Il tuo progetto) non appena il tuo sito o la tua app è online — un link visibile verso nakordoni.eu su quella pagina è richiesto dai nostri Termini.

Gli sviluppatori possono ora inviare le proprie notizie legate alle frontiere al feed di notizie di Nakordoni. Se i nostri redattori la pubblicano, ottieni un backlink dofollow indicizzabile verso il tuo servizio (firma dell'editore + riga della fonte) e traduciamo l'articolo in tutte le 24 lingue gratuitamente.

Un articolo a settimana è gratuito; gli articoli aggiuntivi sono un componente a pagamento. Scegli 'possiamo modificare leggermente + aggiungere link interni' oppure 'pubblica così com'è'. Invia e monitora lo stato di revisione in Sviluppatori → Invia notizia.

La Multi-Checkpoint API (/api/v1/data/multi) ora fattura la quota a ⌈(N PPIDs × sotto-prodotti) / 2⌉ — metà del costo di chiamate individuali equivalenti. Una richiesta per 10 checkpoint con entrambi i sotto-prodotti ora costa 10 units invece di 20. L'header X-Devapi-Units e meta.units_consumed nella risposta riflettono l'importo scontato.

Recupera lo stato delle code in tempo reale e la freschezza dei dati per un massimo di 20 checkpoint in un'unica chiamata API — pensato per chi crea dashboard e che attualmente interroga molti PPIDs in un loop.

La quota viene conteggiata in modo equo come N PPIDs × sotto-prodotti richiesti, quindi l'utilizzo totale è identico a quello delle chiamate individuali — ma con un solo round-trip invece di molti. Gli schemi in stile GreenTravel passano da oltre 24 chiamate/ora a 2.

GET /api/v1/data/multi?ppids=id_2,id_13,id_15,id_59&include=queue,update-info&lang=en

• include=queue — queue_now attuale, wait_min stimato, età dei dati e nome del checkpoint
• include=update-info — freschezza dei dati, classificazione della fonte, età in secondi/minuti
• Massimo 20 PPIDs per richiesta; combina entrambi i sotto-prodotti in un'unica chiamata per ottenere tutti i dati della dashboard
• La risposta include meta.units_consumed così puoi monitorare con precisione l'utilizzo della quota

La risposta del prodotto queue ora include un oggetto snapshot di livello superiore con i dati in tempo reale più recenti e un tempo di attesa previsto e calcolato — la stessa formula usata nella sezione hero di nakordoni.eu:

snapshot.queue_now  — current cars in queue
snapshot.wait_min   — tmin + queue_now × tpercar (minutes)
snapshot.tmin       — minimum crossing time (minutes)
snapshot.tpercar    — added time per vehicle (minutes)
snapshot.updated_at — when the queue data was recorded
snapshot.age_min    — minutes since last update
snapshot.source     — data source identifier

L'array data (voci storiche) è invariato — si tratta di un'aggiunta puramente additiva. I client che non leggono snapshot non sono interessati.

Interroga tutti i checkpoint su una determinata frontiera + tipo di veicolo in un'unica chiamata invece di fare una richiesta per ogni PPID.

GET /api/v1/data/border/{origin}/{destination}/{crossing_type}

• Supporta un singolo paese di destinazione, un elenco separato da virgole, oppure all per estenderlo a tutti i vicini monitorati in una volta.
• Risultati ordinati per queue_now crescente (la coda più corta per prima).
• Completamente localizzato: aggiungi ?lang=uk (o una delle nostre 22 lingue supportate) per ottenere i nomi dei checkpoint in quella lingua.

Scopri i valori PPID dei checkpoint per nome senza sfogliare l'intera directory.

GET /api/v1/data/search?name=Krakovets,Shehyni&lang=en

• Accetta un singolo nome o un elenco separato da virgole (fino a 20).
• Cerca in tutte le 24 lingue di traduzione — inserisci un nome in ucraino, polacco, tedesco o qualsiasi lingua supportata e verrà trovato.
• Restituisce tutti i PPIDs di quella località raggruppati per tipo di veicolo (auto / bus / pedone / camion).

Il prodotto alternatives ora accetta ?lang= in tutte le 22 lingue supportate (prima erano solo 12).

Il nuovo parametro crossing_type ti permette di sovrascrivere il filtro del tipo di veicolo — ad es. passa crossing_type=4 per ottenere alternative per auto anche interrogando da un PPID bus.

Il campo crossing_type_label nelle risposte di checkpoints, border e search è ora tradotto nella lingua richiesta, in tutte le 22 lingue supportate. I campi del nome del paese (origin_name, destination_name) seguono la stessa locale.

Il portale API per sviluppatori di Nakordoni è online all'indirizzo /en/developers. Registrati per una chiave Explorer gratuita (200 richieste/giorno) per accedere ai dati sulle code alle frontiere, alle previsioni, ai prezzi dei carburanti, ai POIs per i conducenti e altro ancora.

Prodotti disponibili al lancio: checkpoints, queue, stats, day-stats, forecast, alternatives, update_info, fuel, pois, truck_bans, trading_sundays, bus_carriers, road_conditions, assistant.