Jurnal modificări API

Nou: un server MCP real la https://nakordoni.eu/mcp, care expune un subset sigur, doar pentru citire, al API-ului (status, checkpoints, border queue, live queue, forecast) sub formă de instrumente MCP. Aceeași cheie API și cotă ca la API-ul REST. Cardul serverului la /.well-known/mcp/server-card.json. Consultați secțiunea Server MCP din documentație.

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.

A fost corectată o eroare prin care fiecare apel /multi era facturat de două ori — o dată printr-o verificare generică de 1 unitate și încă o dată prin formula proprie de cost variabil a endpointului (N PPID-uri × subproduse). Un apel costă acum exact ⌈(N×M)/2⌉ unități, conform documentației, fără taxă suplimentară.

De asemenea, pe pagina de documentație a fost adăugată o insignă de clasă a cotei (Standard/Heavy) pentru fiecare produs, astfel încât să fie clar dintr-o privire ce cotă zilnică folosește un endpoint.

country și countries au fost unificate într-un singur parametru (1-15 coduri separate prin virgulă). Parametru nou compare_to: comparație între sărbători identice și diferite pe mai multe țări, se combină cu upcoming+days. lang acceptă acum mai multe limbi (adaugă un obiect names). days=0 sau omis înseamnă acum fără limită în modul upcoming.

Sărbători legale oficiale pentru fiecare țară europeană — date, denumiri locale și tip. Se bazează pe același serviciu Nager.Date / OpenHolidaysAPI (cu un calendar Kosovo calculat local) care alimentează pagina calendarului de sărbători de pe nakordoni.eu și factorii de calendar ai sistemului de predicție.

• ?country=PL&year=2026 — lista completă a sărbătorilor pe un an pentru o țară
• ?upcoming=1&days=30 — listă simplă a sărbătorilor apropiate din mai multe țări
• Fără parametri — index al unui set de bază de țări, cu următoarea sărbătoare pentru fiecare

Am adăugat produsul currency — cursuri de schimb bazate pe EUR pentru PLN, CZK, HUF, USD, GBP, CHF, NOK și UAH, preluate de la Frankfurter (BCE) și stocate în cache 6 ore. Fără parametri, returnează întotdeauna tabelul complet de cursuri. Consultați documentația.

Încorporați interdicțiile de circulație pentru camioane din Europa, în timp real, pe propriul site — un widget iframe gratuit cu 3 designuri (light, dark, board), 5 limbi (en, uk, pl, de, ru), un filtru opțional pe țară și status «activ acum» în timp real. Nu este necesară o cheie API. Configurați și copiați codul la nakordoni.eu/en/for_truck_drivers/traffic_bans/widget. Preferați datele brute? Produsul API truck-bans și fluxul JSON public rămân disponibile.

Trei adăugiri, toate compatibile retroactiv — v1 rămâne neschimbat.

Versionare per endpoint. Există acum un URL de bază /api/v2/. Funcționează per endpoint: doar endpoint-urile care s-au schimbat efectiv se comportă diferit sub v2; orice alt endpoint servește în mod transparent răspunsul v1 (astfel, /api/v2/data/queue = aceleași date ca v1, doar cu "api_version":"v2"). Nu este nevoie să migrați endpoint-urile care funcționează.

border v2 este direcțional. Ordinea din cale reprezintă direcția de deplasare:

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)

Fiecare checkpoint primește în plus un obiect direction {from,to} și un boolean stale, iar ?max_age_min=N returnează doar punctele de trecere actualizate recent. (v1 border returnează în continuare ambele părți ale graniței, indiferent de ordine — neschimbat.)

Sandbox interactiv. Dezvoltatorii autentificați pot încerca acum orice endpoint direct din browser la Developers → Sandbox — alegeți un endpoint, o versiune și una dintre cheile dumneavoastră, ajustați parametrii și vedeți răspunsul în timp real. Testarea în Sandbox are propriul buget zilnic separat (50 de apeluri/zi) și nu afectează niciodată cota API live.

Documentația este acum împărțită pe endpoint (Developers → API Docs), cu un selector de versiune la endpoint-urile care au mai multe versiuni.

Doi factori noi integrați în formula timpului de așteptare, alături de ajustările existente section_mode și de vreme:

• service_rate — mașini/min măsurate, procesate în prezent, față de rata de bază configurată a checkpoint-ului. Multiplicativ, limitat la 0.5x-1.5x.
• shift_change — impactul schimbului de tură al polițiștilor de frontieră la 08:00/20:00, ora locală a checkpoint-ului. Aditiv (minute), nu multiplicativ — aplicat doar în intervalul de +/-60 de minute față de un schimb, necesită un istoric minim de eșantioane, limitat la +/-120 de minute.

advanced_wait_min este acum round(base_wait × section_mode × weather × service_rate) + shift_change.adjustment_min. Ambii factori se reflectă și în driver_reported.prognosed_advanced_wait_min pentru comparații istorice.

În cadrul unei revizuiri de securitate/confidențialitate, următoarele câmpuri au fost eliminate — expuneau detalii interne de implementare (taxonomia surselor noastre de date din amonte, ID-uri de rânduri din baza de date, adnotări interne de pipeline, câmpuri neutilizate/moarte) fără o valoare reală pentru produs:

• id și corrected — eliminate din obiectele de rând ale queue
• tmin/tpercar — eliminate din queue, border și multi (constantele formulei timpului de așteptare; wait_min/wait_time deja calculat nu este afectat)
• source (șir brut, de ex. "line") — eliminat din queue, multi și update-info. update-info și blocul update_info al multi conțin în continuare source_category/source_label_en (un mic vocabular public); blocul queue al queue și al multi nu mai conține niciun câmp source
• traffic_status — eliminat din border; era mereu null și nu a fost niciodată populat de vreo parte a sistemului

Dacă integrarea dumneavoastră citește vreunul dintre aceste câmpuri, vă rugăm să o actualizați — consultați lista curentă de câmpuri pe pagina de documentație a produsului respectiv.

Consumul zilnic al cotei (usage.used în fiecare răspuns) poate fi acum o valoare zecimală (de ex. 67.5) în loc să fie mereu un număr întreg. Acesta este un efect secundar al faptului că queue-advanced este taxat la o rată fracționară — vedeți mai jos. usage.limit nu este afectat și este întotdeauna un număr întreg. Dacă clientul dumneavoastră tratează strict usage.used ca număr întreg, vă rugăm să îl extindeți pentru a accepta o valoare zecimală/float.

Aceste trei produse returnează acum aceleași câmpuri de status live pe care le afișează site-ul: wait_status (green/yellow/red, pe baza istoricului recent al acestui checkpoint) și trend_percent/trend_direction (up/up-slight/down/down-slight/stable, comparând ultimele 3 ore). Pur aditiv.

Rândurile data[] din /api/v1/data/queue aveau anterior wait_time: null pentru majoritatea surselor — doar câteva fluxuri din amonte raportează direct un timp de așteptare. Rândurile fără acesta primesc acum estimarea standard tmin + queue×tpercar, marcată cu un nou boolean wait_time_estimated, astfel încât să puteți distinge o valoare raportată real de una calculată.

queue-advanced costă acum 1.5 units pe apel în loc de 1 (reflectând căutările suplimentare de trafic/vreme/rapoarte ale șoferilor pe care le efectuează) — vedeți usage.used mai sus. Răspunsul nu mai include nici tmin, tpercar sau total_crossing_time, iar driver_reported este acum doar {wait_min, ts, age_min} — câmpurile anterioare de comparație prognoză-realitate (prognosed_wait_min, diff_min, historical_section_mode, historical_weather etc.) au fost eliminate. section_mode, weather, advanced_wait_min și exceeds_crossing_time rămân neschimbate.

/api/v1/data/truck-bans returnează acum, pentru fiecare țară din bans_by_country, un status (active/clear) plus active_window, next_window, local_time și tz — calculate în fusul orar propriu al țării respective, astfel încât nu mai trebuie să evaluați dumneavoastră intervalele brute de interdicție în raport cu un ceas. Răspunsul adaugă și o listă covered_countries la nivel superior și un marcaj temporal as_of în UTC.

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

Pur aditiv — câmpurile existente current_bans/upcoming_bans/bans_by_country rămân neschimbate. Un ?country= necunoscut returnează acum un rezultat gol cu countries_not_covered în loc de interdicțiile fiecărei țări.

Un produs nou, opțional, care ajustează timpul de așteptare standard în funcție de fluxul de trafic în timp real și de vreme. Returnează detalierea completă a fiecărei ajustări.

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

Acordat la cerere — deschideți un tichet Data din panoul dumneavoastră pentru a-l activa.

/api/v1/data/border calculează acum corect wait_min (și returnează tmin/tpercar) pentru fiecare checkpoint din răspuns, la fel ca produsele queue și multi. Anterior, acest câmp era mereu null.

/api/v1/data/forecast utilizează acum în mod fiabil modelul ensemble v4 pentru orice valoare prediction_steps (anterior, unele orizonturi nestandard puteau reveni în tăcere la un model mai vechi). Factorul meteo care alimentează ensemble-ul a fost de asemenea corectat și reflectă acum cu adevărat condițiile în timp real (ploaie, ninsoare, vânt, ceață) în loc să raporteze mereu indisponibil.

Dezvoltatorii aprobați pot descărca acum date istorice ale cozilor de la frontieră, mediate orar, pentru până la 5 checkpoint-uri (fereastră glisantă de până la 90 de zile), în format CSV sau NDJSON, din noul tab Data export. Sunt disponibile doar date publicate și verificate calitativ; marcajele temporale sunt în UTC. Aveți nevoie de acces? Deschideți un tichet Data.

Încă nu aveți un site? Puteți crea acum un cont de dezvoltator descriind unde și cum intenționați să folosiți datele noastre, în loc să fiți obligat să introduceți URL-ul unei pagini live. Adăugați URL-ul real mai târziu din panoul dumneavoastră (Account & data → Proiectul dumneavoastră), imediat ce site-ul sau aplicația este live — un link vizibil către nakordoni.eu pe acea pagină este obligatoriu conform Termenilor noștri.

Dezvoltatorii pot trimite acum propriile știri legate de frontieră către fluxul de știri Nakordoni. Dacă editorii noștri le publică, primiți un backlink dofollow indexabil către serviciul dumneavoastră (semnătura editorului + rândul sursei) și traducem articolul în toate cele 24 de limbi gratuit.

Un articol pe săptămână este gratuit; articolele suplimentare sunt un supliment plătit. Alegeți 'putem edita ușor + adăuga linkuri interne' sau 'publicăm ca atare'. Trimiteți și urmăriți starea verificării la Developers → Submit news.

Multi-Checkpoint API (/api/v1/data/multi) taxează acum cota la ⌈(N PPIDs × sub-products) / 2⌉ — jumătate din costul apelurilor individuale echivalente. O cerere pentru 10 checkpoint-uri cu ambele sub-products costă acum 10 units în loc de 20. Antetul X-Devapi-Units și meta.units_consumed din răspuns reflectă suma redusă.

Obțineți statusul cozii în timp real și prospețimea datelor pentru până la 20 de checkpoint-uri într-un singur apel API — conceput pentru dezvoltatorii de dashboard-uri care interoghează în prezent multe PPID-uri într-o buclă.

Cota se contorizează echitabil ca N PPIDs × sub-products solicitate, astfel încât utilizarea totală este identică cu apelurile individuale — dar cu o singură comunicare dus-întors în loc de mai multe. Tiparele de tip GreenTravel scad de la 24+ apeluri/oră la 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 curent, wait_min estimat, vechimea datelor și numele checkpoint-ului
• include=update-info — prospețimea datelor, clasificarea sursei, vechimea în secunde/minute
• Maximum 20 de PPID-uri per cerere; combinați ambele sub-products într-un singur apel pentru date complete de dashboard
• Răspunsul include meta.units_consumed, astfel încât să puteți urmări cu precizie utilizarea cotei

Răspunsul produsului queue include acum un obiect snapshot la nivel superior, cu cele mai recente date în timp real și un timp de așteptare prognozat calculat — aceeași formulă folosită în secțiunea hero de pe 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

Tabloul data (intrări istorice) rămâne neschimbat — aceasta este o adăugire pur aditivă. Clienții care nu citesc snapshot nu sunt afectați.

Interogați toate checkpoint-urile de la o anumită graniță + un tip de vehicul într-un singur apel, în loc să faceți o cerere per PPID.

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

• Acceptă o singură țară de destinație, o listă separată prin virgulă sau all pentru a se extinde deodată la fiecare vecin monitorizat.
• Rezultate sortate după queue_now crescător (cea mai scurtă coadă prima).
• Complet localizat: adăugați ?lang=uk (sau oricare dintre cele 22 de limbi acceptate) pentru a obține numele checkpoint-urilor în acea limbă.

Descoperiți valorile PPID ale checkpoint-urilor după nume, fără a răsfoi întregul director.

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

• Acceptă un singur nume sau o listă separată prin virgulă (până la 20).
• Caută în toate cele 24 de limbi de traducere — introduceți un nume în ucraineană, poloneză, germană sau orice limbă acceptată și îl va găsi.
• Returnează toate PPID-urile din acea locație, grupate după tipul de vehicul (mașină / autobuz / pieton / camion).

Produsul alternatives acceptă acum ?lang= în toate cele 22 de limbi acceptate (anterior doar 12).

Noul parametru crossing_type vă permite să suprascrieți filtrul tipului de vehicul — de ex. introduceți crossing_type=4 pentru a obține alternative pentru mașini chiar și atunci când interogați de la un PPID de autobuz.

Câmpul crossing_type_label din răspunsurile checkpoints, border și search este acum tradus în limba solicitată, în toate cele 22 de limbi acceptate. Câmpurile cu numele țărilor (origin_name, destination_name) urmează aceeași setare regională.

Portalul Nakordoni Developer API este activ la /en/developers. Înscrieți-vă pentru o cheie Explorer gratuită (200 de cereri/zi) pentru a accesa datele cozilor de la frontieră, prognoze, prețuri la carburanți, POI-uri pentru șoferi și multe altele.

Produse disponibile la lansare: checkpoints, queue, stats, day-stats, forecast, alternatives, update_info, fuel, pois, truck_bans, trading_sundays, bus_carriers, road_conditions, assistant.