Historiku i ndryshimeve të API

E re: një server i vërtetë MCP në https://nakordoni.eu/mcp, që ekspozon një nënbashkësi të sigurt, vetëm-lexim, të API-së (status, checkpoints, border queue, live queue, forecast) si mjete MCP. E njëjta çelës API dhe kuotë si te API-ja REST. Karta e serverit në /.well-known/mcp/server-card.json. Shihni seksionin Server MCP në dokumentacion.

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.

U rregullua një gabim për shkak të të cilit çdo thirrje /multi faturohej dy herë — një herë nga një kontroll gjenerik i 1 njësie dhe përsëri nga formula e vet e kostos së ndryshueshme të endpoint-it (N PPID × nënprodukte). Një thirrje tani kushton saktësisht ⌈(N×M)/2⌉ njësi siç është dokumentuar, pa ngarkesë shtesë.

Gjithashtu u shtua një distinktiv i klasës së kuotës (Standard/Heavy) për çdo produkt në faqen e dokumentacionit, që të jetë e qartë me një shikim se cilën kuotë ditore përdor një endpoint.

country dhe countries u bashkuan në një parametër të vetëm (1-15 kode të ndara me presje). Parametër i ri compare_to: krahasim i festave të njëjta ose të ndryshme midis vendeve, kombinohet me upcoming+days. lang tani pranon disa gjuhë (shton një objekt names). days=0 ose i lënë jashtë tani do të thotë pa kufi në modalitetin upcoming.

Festat zyrtare publike për çdo vend evropian — datat, emrat vendorë dhe lloji. Mbështetur nga i njëjti shërbim Nager.Date / OpenHolidaysAPI (me një kalendar të Kosovës të llogaritur në nivel vendor) që fuqizon faqen e kalendarit të festave të nakordoni.eu dhe faktorët kalendarikë të sistemit të parashikimit.

• ?country=PL&year=2026 — lista e festave për të gjithë vitin për një vend
• ?upcoming=1&days=30 — listë e thjeshtë e festave të ardhshme ndër vende
• Pa parametra — indeks i një grupi kryesor vendesh me festën e radhës për secilin

U shtua produkti currency — kurse këmbimi të bazuara në EUR për PLN, CZK, HUF, USD, GBP, CHF, NOK dhe UAH, të marra nga Frankfurter (ECB) dhe të ruajtura në cache për 6 orë. Pa parametra, gjithmonë kthen tabelën e plotë të kurseve. Shih dokumentacionin.

Integroni ndalimet e qarkullimit të kamionëve në Evropë në kohë reale në faqen tuaj të internetit — një widget iframe falas me 3 dizajne (light, dark, board), 5 gjuhë (en, uk, pl, de, ru), një filtër opsional sipas vendit dhe një status «aktiv tani» në kohë reale. Nuk nevojitet çelës API. Konfiguroni dhe kopjoni kodin te nakordoni.eu/en/for_truck_drivers/traffic_bans/widget. Preferoni të dhënat e papërpunuara? Produkti API truck-bans dhe feed-i publik JSON mbeten të disponueshëm.

Tri shtesa, të gjitha të pajtueshme me versionet e mëparshme — v1 është e pandryshuar.

Versionim për çdo endpoint. Tani ekziston një URL bazë /api/v2/. Është për çdo endpoint: vetëm endpoint-et që kanë ndryshuar vërtet sillen ndryshe në v2; çdo endpoint tjetër shërben në mënyrë transparente përgjigjen e vet v1 (pra /api/v2/data/queue = të njëjtat të dhëna si v1, thjesht me "api_version":"v2"). Nuk ka nevojë të migroni endpoint-et që funksionojnë.

border v2 është me drejtim. Rendi i shtegut është drejtimi i udhëtimit:

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)

Çdo checkpoint fiton gjithashtu një objekt direction {from,to} dhe një boolean stale, dhe ?max_age_min=N kthen vetëm kalimet e përditësuara së fundmi. (Në v1, border vazhdon të kthejë të dyja anët e kufirit pavarësisht nga rendi — i pandryshuar.)

Sandbox interaktiv. Zhvilluesit e kyçur tani mund të provojnë çdo endpoint nga shfletuesi te Zhvilluesit → Sandbox — zgjidhni një endpoint, një version dhe një nga çelësat tuaj, ndryshoni parametrat dhe shihni përgjigjen në kohë reale. Testimi në Sandbox ka buxhetin e vet ditor të veçantë (50 thirrje/ditë) dhe nuk prek kurrë kuotën tuaj reale të API-t.

Dokumentacioni tani është i ndarë sipas endpoint-it (Zhvilluesit → Dokumentacioni i API-t) me një përzgjedhës versioni te endpoint-et që kanë më shumë se një version.

Dy faktorë të rinj të integruar në formulën e kohës së pritjes, krahas rregullimeve ekzistuese section_mode dhe atyre të motit:

• service_rate — makina/min që po përpunohen aktualisht, të matura kundrejt normës bazë të konfiguruar të checkpoint-it. Shumëzues, i kufizuar midis 0.5x dhe 1.5x.
• shift_change — ndikimi i ndërrimit të turnit të rojeve kufitare në 08:00/20:00, specifik për çdo checkpoint. Mbledhës (minuta), jo shumëzues — zbatohet vetëm brenda +/-60 minutash nga një ndërrim turni, kërkon një histori minimale mostrash, i kufizuar në +/-120 minuta.

advanced_wait_min tani është round(base_wait × section_mode × weather × service_rate) + shift_change.adjustment_min. Të dy faktorët pasqyrohen gjithashtu në driver_reported.prognosed_advanced_wait_min për krahasimet historike.

Si pjesë e një rishikimi sigurie dhe privatësie, fushat e mëposhtme janë hequr — ato ekspozonin detaje të brendshme të implementimit (taksonomia jonë e burimeve të të dhënave në rrjedhën e sipërme, ID-të e rreshtave të DB-së, shënime të brendshme të pipeline-it, fusha të papërdorura ose të vdekura) pa vlerë reale për produktin:

• id dhe corrected — hequr nga objektet e rreshtit të queue
• tmin/tpercar — hequr nga queue, border dhe multi (konstantet e formulës së kohës së pritjes; vlerat tashmë të llogaritura wait_min/wait_time nuk preken)
• source (varg i papërpunuar, p.sh. "line") — hequr nga queue, multi dhe update-info. Blloku update_info i update-info dhe i multi ende përmban source_category/source_label_en (një fjalor i vogël publik); blloku queue i queue dhe i multi nuk përmban më asnjë fushë source
• traffic_status — hequr nga border; ishte gjithmonë null dhe nuk mbushej kurrë nga asnjë pjesë e sistemit

Nëse integrimi juaj lexon ndonjë nga këto fusha, ju lutemi përditësojeni — shihni listën aktuale të fushave në faqen e dokumentacionit të produktit përkatës.

Përdorimi i kuotës ditore (usage.used në çdo përgjigje) tani mund të jetë një vlerë dhjetore (p.sh. 67.5) në vend që të jetë gjithmonë një numër i plotë. Kjo është një efekt anësor i faturimit të queue-advanced me një normë thyesore — shih më poshtë. usage.limit nuk preket dhe është gjithmonë një numër i plotë. Nëse klienti juaj e tipizon rreptësisht usage.used si numër të plotë, ju lutemi zgjeroni atë për të pranuar një dhjetor / float.

Këto tre produkte tani kthejnë të njëjtat fusha të statusit në kohë reale që shfaq faqja e internetit: wait_status (green/yellow/red, bazuar në historinë e fundit të vetë këtij checkpoint-i) dhe trend_percent/trend_direction (up/up-slight/down/down-slight/stable, duke krahasuar 3 orët e fundit). Thjesht shtesë.

Rreshtat data[] të /api/v1/data/queue më parë kishin wait_time: null për shumicën e burimeve — vetëm disa feed-e në rrjedhën e sipërme raportojnë drejtpërdrejt një kohë pritjeje. Rreshtat pa një të tillë tani marrin vlerësimin standard tmin + queue×tpercar, të shënuar me një boolean të ri wait_time_estimated që të mund të dallosh një shifër të raportuar realisht nga një e llogaritur.

queue-advanced tani kushton 1.5 units për thirrje në vend të 1 (duke pasqyruar kërkimet shtesë të trafikut, motit dhe raporteve të shoferëve që kryen) — shih usage.used më sipër. Përgjigja gjithashtu nuk përfshin më tmin, tpercar ose total_crossing_time, dhe driver_reported tani është vetëm {wait_min, ts, age_min} — fushat e mëparshme të krahasimit parashikim/realitet (prognosed_wait_min, diff_min, historical_section_mode, historical_weather, etj.) janë hequr. section_mode, weather, advanced_wait_min dhe exceeds_crossing_time janë të pandryshuara.

/api/v1/data/truck-bans tani kthen, për çdo vend në bans_by_country, një status (active/clear) plus active_window, next_window, local_time dhe tz — të llogaritura në zonën kohore të vetë atij vendi, kështu që nuk keni më nevojë të vlerësoni vetë dritaret e papërpunuara të ndalimit kundrejt një ore. Përgjigja shton gjithashtu një listë covered_countries të nivelit të lartë dhe një vulë kohore UTC as_of.

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

Thjesht shtesë — fushat ekzistuese current_bans/upcoming_bans/bans_by_country janë të pandryshuara. Një ?country= i panjohur tani kthen një rezultat bosh me countries_not_covered në vend të ndalimeve të çdo vendi.

Një produkt i ri opsional që rregullon kohën standarde të pritjes sipas fluksit të trafikut në kohë reale dhe motit. Kthen zbërthimin e plotë të çdo rregullimi.

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

Jepet me kërkesë — hapni një tiket Data nga paneli juaj për ta aktivizuar.

/api/v1/data/border tani llogarit saktë wait_min (dhe kthen tmin/tpercar) për çdo checkpoint në përgjigje, njësoj si produktet queue dhe multi. Më parë kjo fushë ishte gjithmonë null.

/api/v1/data/forecast tani përdor në mënyrë të besueshme modelin ensemble v4 për çdo vlerë të prediction_steps (më parë disa horizonte jostandarde mund të riktheheshin në heshtje te një model më i vjetër). Faktori i motit që ushqen ensemble-in është gjithashtu i korrigjuar dhe tani pasqyron vërtet kushtet në kohë reale (shi, borë, erë, mjegull) në vend që të raportojë gjithmonë si të padisponueshëm.

Zhvilluesit e miratuar tani mund të shkarkojnë të dhëna historike të radhëve në kufi, të mesatarizuara për orë, për deri në 5 checkpoint (dritare rrotulluese deri në 90 ditë) në formatin CSV ose NDJSON nga skeda e re Data export. Të dhënat janë vetëm të publikuara dhe të kontrolluara për cilësi; vulat kohore janë në UTC. Ju nevojitet qasje? Hapni një tiket Data.

Ende nuk keni faqe interneti? Tani mund të krijoni një llogari zhvilluesi duke përshkruar ku dhe si planifikoni të përdorni të dhënat tona, në vend që të detyroheni të vendosni URL-në e një faqeje aktive. Shtoni URL-në reale më vonë nga paneli juaj (Llogaria & të dhënat → Projekti juaj) sapo faqja ose aplikacioni juaj të jetë online — një link i dukshëm që kthehet te nakordoni.eu në atë faqe kërkohet nga Kushtet tona.

Zhvilluesit tani mund të dërgojnë lajmet e tyre të lidhura me kufirin te linja e lajmeve të Nakordoni. Nëse redaktorët tanë e publikojnë, ju merrni një backlink dofollow të indeksueshëm drejt shërbimit tuaj (firma e botuesit + rreshti i burimit) dhe ne e përkthejmë artikullin në të gjitha 24 gjuhët falas.

Një artikull në javë është falas; artikujt shtesë janë një shtesë me pagesë. Zgjidhni 'mund ta redaktojmë lehtë + të shtojmë lidhje të brendshme' ose 'publikoje siç është'. Dërgoni dhe ndiqni statusin e rishikimit te Zhvilluesit → Dërgo lajm.

Multi-Checkpoint API (/api/v1/data/multi) tani fatura kuotën me ⌈(N PPIDs × nën-produkte) / 2⌉ — gjysma e kostos së thirrjeve individuale ekuivalente. Një kërkesë për 10 checkpoint me të dy nën-produktet tani kushton 10 units në vend të 20. Header-i X-Devapi-Units dhe meta.units_consumed në përgjigje pasqyrojnë shumën e zbritur.

Merrni statusin e radhëve në kohë reale dhe freskinë e të dhënave për deri në 20 checkpoint në një thirrje të vetme API — projektuar për ndërtuesit e paneleve që aktualisht kontrollojnë shumë PPIDs në një cikël.

Kuota numërohet në mënyrë të drejtë si N PPIDs × nën-produkte të kërkuara, kështu që përdorimi total është identik me thirrjet individuale — por me një udhëtim vajtje-ardhje në vend të shumëve. Modelet e tipit GreenTravel bien nga mbi 24 thirrje/orë në 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 aktual, wait_min i vlerësuar, mosha e të dhënave dhe emri i checkpoint-it
• include=update-info — freskia e të dhënave, klasifikimi i burimit, mosha në sekonda/minuta
• Maksimumi 20 PPIDs për kërkesë; kombinoni të dy nën-produktet në një thirrje të vetme për të gjitha të dhënat e panelit
• Përgjigja përfshin meta.units_consumed që të mund të ndiqni me saktësi përdorimin e kuotës

Përgjigja e produktit queue tani përfshin një objekt snapshot të nivelit të lartë me të dhënat më të fundit në kohë reale dhe një kohë pritjeje të parashikuar e të llogaritur — të njëjtën formulë të përdorur në seksionin hero të 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

Vargu data (hyrjet historike) është i pandryshuar — kjo është një shtesë thjesht shtuese. Klientët që nuk lexojnë snapshot nuk preken.

Kërkoni të gjitha checkpoint-et në një kufi + lloj automjeti të dhënë në një thirrje të vetme në vend që të bëni një kërkesë për çdo PPID.

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

• Mbështet një vend të vetëm destinacioni, një listë të ndarë me presje, ose all për ta zgjeruar te çdo fqinj i monitoruar njëherësh.
• Rezultatet të renditura sipas queue_now në rritje (radha më e shkurtër e para).
• Plotësisht i lokalizuar: shtoni ?lang=uk (ose ndonjë nga 22 gjuhët tona të mbështetura) për të marrë emrat e checkpoint-eve në atë gjuhë.

Zbuloni vlerat PPID të checkpoint-eve sipas emrit pa shfletuar të gjithë direktorinë.

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

• Pranon një emër të vetëm ose një listë të ndarë me presje (deri në 20).
• Kërkon në të gjitha 24 gjuhët e përkthimit — jepni një emër në ukrainisht, polonisht, gjermanisht ose çdo gjuhë të mbështetur dhe do të përputhet.
• Kthen të gjitha PPIDs në atë vendndodhje të grupuara sipas llojit të automjetit (makinë / autobus / këmbësor / kamion).

Produkti alternatives tani pranon ?lang= në të gjitha 22 gjuhët e mbështetura (më parë ishin vetëm 12).

Parametri i ri crossing_type ju lejon të mbivendosni filtrin e llojit të automjetit — p.sh. jepni crossing_type=4 për të marrë alternativa makine edhe kur kërkoni nga një PPID autobusi.

Fusha crossing_type_label në përgjigjet e checkpoints, border dhe search tani përkthehet në gjuhën e kërkuar, në të gjitha 22 gjuhët e mbështetura. Fushat e emrit të vendit (origin_name, destination_name) ndjekin të njëjtën locale.

Portali API i zhvilluesve i Nakordoni është online në adresën /en/developers. Regjistrohuni për një çelës Explorer falas (200 kërkesa/ditë) për të aksesuar të dhënat e radhëve në kufi, parashikimet, çmimet e karburantit, POIs për shoferët dhe më shumë.

Produktet e disponueshme në lançim: checkpoints, queue, stats, day-stats, forecast, alternatives, update_info, fuel, pois, truck_bans, trading_sundays, bus_carriers, road_conditions, assistant.