API-ის ცვლილებების ჟურნალი

ახალი: ნამდვილი MCP სერვერი მისამართზე https://nakordoni.eu/mcp, რომელიც API-ის უსაფრთხო, მხოლოდ წაკითხვად ქვეჯგუფს (status, checkpoints, border queue, live queue, forecast) აწვდის როგორც MCP ხელსაწყოებს. იგივე API გასაღები და კვოტა, რაც REST API-ში. სერვერის ბარათი მისამართზე /.well-known/mcp/server-card.json. იხილეთ განყოფილება MCP სერვერი დოკუმენტაციაში.

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.

გასწორდა ხარვეზი, რომლის გამოც ყოველი /multi გამოძახება ორჯერ ირიცხებოდა — ჯერ ზოგადი 1-ერთეულიანი შემოწმებით, შემდეგ კი ბოლოწერტილის საკუთარი ცვლადი ღირებულების ფორმულით (N PPID × ქვე-პროდუქტები). ახლა გამოძახება ზუსტად ⌈(N×M)/2⌉ ერთეული ღირს, დოკუმენტაციის მიხედვით, დამატებითი დარიცხვის გარეშე.

ასევე, დოკუმენტაციის გვერდზე თითოეულ პროდუქტს დაემატა კვოტის კლასის ნიშანი (Standard/Heavy), რომ ერთი შეხედვით ნათელი იყოს, რომელ დღიურ კვოტას იყენებს ბოლოწერტილი.

country და countries გაერთიანდა ერთ პარამეტრში (1-15 მძიმით გამოყოფილი კოდი). ახალი compare_to პარამეტრი: ერთი და იმავე ან განსხვავებული დღესასწაულების შედარება ქვეყნებს შორის, ეთავსება upcoming+days-ს. lang ახლა იღებს რამდენიმე ენას (ამატებს names ობიექტს). days=0 ან გამოტოვებული ახლა ნიშნავს ლიმიტის გარეშეს upcoming რეჟიმში.

ოფიციალური სახელმწიფო დღესასწაულები ევროპის თითოეული ქვეყნისთვის — თარიღები, ადგილობრივი სახელები და ტიპი. ეფუძნება იმავე Nager.Date / OpenHolidaysAPI სერვისს (ლოკალურად გამოთვლილი კოსოვოს კალენდრით), რომელიც კვებავს nakordoni.eu-ს დღესასწაულების კალენდრის გვერდს და პროგნოზირების სისტემის კალენდარულ ფაქტორებს.

• ?country=PL&year=2026 — სრული წლიური დღესასწაულების სია ერთი ქვეყნისთვის
• ?upcoming=1&days=30 — მომავალი დღესასწაულების ბრტყელი სია ქვეყნების მიხედვით
• პარამეტრების გარეშე — ძირითადი ქვეყნების ნაკრების ინდექსი, თითოეულის უახლოესი დღესასწაულით

დაემატა currency პროდუქტი — EUR-ზე დაფუძნებული გაცვლის კურსები PLN, CZK, HUF, USD, GBP, CHF, NOK და UAH-ისთვის, აღებული Frankfurter-იდან (ECB) და დაქეშილი 6 საათით. პარამეტრების გარეშე, ყოველთვის აბრუნებს კურსების სრულ ცხრილს. იხილეთ დოკუმენტაცია.

ჩააშენეთ ევროპული სატვირთოების მოძრაობის აკრძალვები რეალურ დროში თქვენს საკუთარ ვებსაიტზე — უფასო iframe ვიჯეტი 3 დიზაინით (light, dark, board), 5 ენით (en, uk, pl, de, ru), არასავალდებულო ქვეყნების ფილტრით და «active now» ცოცხალი სტატუსით. API გასაღები საჭირო არ არის. მოირგეთ და დააკოპირეთ კოდი აქ: nakordoni.eu/en/for_truck_drivers/traffic_bans/widget. გირჩევნიათ ნედლი მონაცემები? truck-bans API პროდუქტი და საჯარო JSON ფიდი კვლავ ხელმისაწვდომია.

სამი დამატება, ყველა უკუთავსებადი — v1 უცვლელია.

თითო endpoint-ის ვერსირება. ახლა არსებობს /api/v2/ საბაზისო URL. ის თითო endpoint-ისაა: მხოლოდ ის endpoint-ები, რომლებიც რეალურად შეიცვალა, იქცევა განსხვავებულად v2-ში; ყველა სხვა endpoint გამჭვირვალედ ემსახურება თავის v1 პასუხს (ასე რომ /api/v2/data/queue = იგივე მონაცემები, რაც v1-ში, უბრალოდ "api_version":"v2"-ით). endpoint-ების მიგრაცია, რომლებიც მუშაობს, საჭირო არ არის.

border v2 მიმართულებითია. გზის რიგითობა არის მოგზაურობის მიმართულება:

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)

თითოეული საკონტროლო პუნქტი ასევე იღებს direction {from,to} ობიექტს და stale ლოგიკურ მნიშვნელობას, ხოლო ?max_age_min=N აბრუნებს მხოლოდ ახლახან განახლებულ გადაკვეთებს. (v1 border კვლავ აბრუნებს საზღვრის ორივე მხარეს რიგითობის მიუხედავად — უცვლელი.)

ინტერაქტიული Sandbox. ავტორიზებულ დეველოპერებს ახლა შეუძლიათ სცადონ ნებისმიერი endpoint ბრაუზერიდან აქ: Developers → Sandbox — აირჩიეთ endpoint, ვერსია და ერთ-ერთი თქვენი გასაღები, შეასწორეთ პარამეტრები და იხილეთ ცოცხალი პასუხი. Sandbox-ის ტესტირებას აქვს საკუთარი ცალკე დღიური ბიუჯეტი (50 calls/day) და არასოდეს ეხება თქვენს ცოცხალ API კვოტას.

დოკუმენტაცია ახლა გაყოფილია თითო endpoint-ის მიხედვით (Developers → API Docs), ვერსიის ამომრჩევით იმ endpoint-ებზე, რომლებსაც ერთზე მეტი ვერსია აქვთ.

ორი ახალი ფაქტორი ჩართულია მოცდის დროის ფორმულაში, არსებული section_mode-ისა და ამინდის კორექტირებების გვერდით:

• service_rate — გაზომილი ავტომობილი/წუთში, რომელიც ამჟამად მუშავდება, საკონტროლო პუნქტის კონფიგურირებულ საბაზისო მაჩვენებელთან შედარებით. მამრავლობითი, შემოსაზღვრული 0.5x-1.5x.
• shift_change — საკონტროლო პუნქტის საკუთარი ადგილობრივი 08:00/20:00 მესაზღვრეთა ცვლის შეცვლის გავლენა. ჯამური (წუთები), არა მამრავლობითი — გამოიყენება მხოლოდ ცვლის +/-60 წუთის ფარგლებში, საჭიროებს მინიმალურ ისტორიულ ნიმუშს, შემოსაზღვრულია +/-120 წუთამდე.

advanced_wait_min ახლა არის round(base_wait × section_mode × weather × service_rate) + shift_change.adjustment_min. ორივე ფაქტორი ასევე აისახება driver_reported.prognosed_advanced_wait_min-ში ისტორიული შედარებებისთვის.

უსაფრთხოების/კონფიდენციალურობის მიმოხილვის ფარგლებში, შემდეგი ველები ამოღებულია — ისინი ავლენდნენ შიდა იმპლემენტაციის დეტალებს (ჩვენი წყაროს მონაცემთა ტაქსონომია, DB row ID-ები, შიდა pipeline-ის ანოტაციები, გამოუყენებელი/მკვდარი ველები) რეალური პროდუქტული ღირებულების გარეშე:

• id და corrected — ამოღებულია queue row ობიექტებიდან
• tmin/tpercar — ამოღებულია queue, border და multi-დან (მოცდის დროის ფორმულის კონსტანტები; უკვე გამოთვლილი wait_min/wait_time ხელუხლებელია)
• source (ნედლი სტრიქონი, მაგ. "line") — ამოღებულია queue, multi და update-info-დან. update-info და multi-ს update_info ბლოკი კვლავ ატარებს source_category/source_label_en-ს (მცირე საჯარო ლექსიკონი); queue და multi-ს queue ბლოკი აღარ ატარებს არანაირ source ველს
• traffic_status — ამოღებულია border-დან; ის ყოველთვის იყო null და არასოდეს ივსებოდა სისტემის არცერთი ნაწილის მიერ

თუ თქვენი ინტეგრაცია კითხულობს რომელიმე ამ ველს, გთხოვთ განაახლოთ იგი — იხილეთ მიმდინარე ველების სია შესაბამისი პროდუქტის დოკუმენტაციის გვერდზე.

დღიური კვოტის მოხმარება (usage.used ყოველ პასუხში) ახლა შეიძლება იყოს ათწილადი მნიშვნელობა (მაგ. 67.5) ყოველთვის მთელი რიცხვის ნაცვლად. ეს არის queue-advanced-ის წილადი ტარიფით დაანგარიშების გვერდითი ეფექტი — იხილეთ ქვემოთ. usage.limit ხელუხლებელია და ყოველთვის მთელი რიცხვია. თუ თქვენი კლიენტი მკაცრად ტიპავს usage.used-ს როგორც მთელ რიცხვს, გთხოვთ გააფართოვოთ იგი ათწილადის/float-ის მისაღებად.

ეს სამი პროდუქტი ახლა აბრუნებს იმავე ცოცხალი-სტატუსის ველებს, რომლებსაც ვებსაიტი აჩვენებს: wait_status (green/yellow/red, ამ საკონტროლო პუნქტის საკუთარ უახლეს ისტორიაზე დაფუძნებით) და trend_percent/trend_direction (up/up-slight/down/down-slight/stable, ბოლო 3 საათის შედარებით). წმინდა დამატებითი.

/api/v1/data/queue-ს data[] row-ებს ადრე ჰქონდათ wait_time: null წყაროების უმეტესობისთვის — მხოლოდ რამდენიმე წყარო აცხადებს მოცდის დროს პირდაპირ. row-ები მის გარეშე ახლა იღებენ სტანდარტულ tmin + queue×tpercar შეფასებას, მონიშნულს ახალი wait_time_estimated ლოგიკური მნიშვნელობით, ასე რომ შეგიძლიათ განასხვავოთ რეალურად მოხსენებული მაჩვენებელი გამოთვლილისგან.

queue-advanced ახლა ღირს 1.5 ერთეული ზარზე 1-ის ნაცვლად (რაც ასახავს დამატებით traffic/weather/driver-report ძებნებს, რომლებსაც ის ასრულებს) — იხილეთ usage.used ზემოთ. პასუხი ასევე აღარ შეიცავს tmin-ს, tpercar-ს ან total_crossing_time-ს, ხოლო driver_reported ახლა უბრალოდ {wait_min, ts, age_min}-ია — წინა პროგნოზი-რეალობასთან შედარების ველები (prognosed_wait_min, diff_min, historical_section_mode, historical_weather და ა.შ.) ამოღებულია. section_mode, weather, advanced_wait_min და exceeds_crossing_time უცვლელია.

/api/v1/data/truck-bans ახლა აბრუნებს, bans_by_country-ში თითოეული ქვეყნისთვის, status-ს (active/clear) პლუს active_window, next_window, local_time და tz — გამოთვლილს ამ ქვეყნის საკუთარ დროის სარტყელში, ასე რომ აღარ გჭირდებათ ნედლი აკრძალვის ფანჯრების საათთან შედარება საკუთარი ხელით. პასუხს ასევე ემატება ზედა დონის covered_countries სია და as_of UTC დროის აღნიშვნა.

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

წმინდა დამატებითი — არსებული current_bans/upcoming_bans/bans_by_country ველები უცვლელია. უცნობი ?country= ახლა აბრუნებს ცარიელ შედეგს countries_not_covered-ით ყოველი ქვეყნის აკრძალვების ნაცვლად.

ახალი არჩევითი პროდუქტი, რომელიც არეგულირებს სტანდარტულ მოცდის დროს ცოცხალი ტრანსპორტის ნაკადისა და ამინდის მიხედვით. აბრუნებს თითოეული კორექტირების სრულ დაშლას.

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

ენიჭება მოთხოვნით — გახსენით Data ტიკეტი თქვენი დაფიდან მის გასააქტიურებლად.

/api/v1/data/border ახლა სწორად ითვლის wait_min-ს (და აბრუნებს tmin/tpercar-ს) პასუხში ყოველი საკონტროლო პუნქტისთვის, რაც ემთხვევა queue და multi პროდუქტებს. ადრე ეს ველი ყოველთვის იყო null.

/api/v1/data/forecast ახლა საიმედოდ იყენებს v4 ანსამბლურ მოდელს ნებისმიერი prediction_steps მნიშვნელობისთვის (ადრე ზოგიერთი არასტანდარტული ჰორიზონტი შეიძლება ჩუმად დაბრუნებულიყო ძველ მოდელზე). ამინდის ფაქტორი, რომელიც კვებავს ანსამბლს, ასევე გასწორებულია და ახლა ნამდვილად ასახავს ცოცხალ პირობებს (წვიმა, თოვლი, ქარი, ნისლი) ყოველთვის მიუწვდომლის მოხსენების ნაცვლად.

დამტკიცებულ დეველოპერებს ახლა შეუძლიათ ჩამოტვირთონ საათობრივად გასაშუალოებული ისტორიული სასაზღვრო რიგის მონაცემები 5-მდე საკონტროლო პუნქტისთვის (მოძრავი ფანჯარა 90 დღემდე) CSV ან NDJSON ფორმატში ახალი Data export ჩანართიდან. მონაცემები მხოლოდ გამოქვეყნებულია და ხარისხზე შემოწმებული; დროის აღნიშვნები UTC-შია. გჭირდებათ წვდომა? გახსენით Data ტიკეტი.

ჯერ არ გაქვთ ვებსაიტი? ახლა შეგიძლიათ შექმნათ დეველოპერის ანგარიში იმის აღწერით, სად და როგორ აპირებთ ჩვენი მონაცემების გამოყენებას, ცოცხალი გვერდის URL-ის შეყვანის იძულების ნაცვლად. დაამატეთ რეალური URL მოგვიანებით თქვენი დაფიდან (Account & data → Your project) როგორც კი თქვენი საიტი ან აპლიკაცია ცოცხალი გახდება — ამ გვერდზე nakordoni.eu-ზე ხილული უკუბმული აუცილებელია ჩვენი პირობებით.

დეველოპერებს ახლა შეუძლიათ გამოაგზავნონ საკუთარი სასაზღვრო სიახლეები Nakordoni-ს ახალი ამბების ხაზზე. თუ ჩვენი რედაქტორები გამოაქვეყნებენ მას, თქვენ იღებთ ინდექსირებად dofollow უკუბმულს თქვენს სერვისზე (გამომქვეყნებლის ხელმოწერა + წყაროს ხაზი) და ჩვენ ვთარგმნით სტატიას ყველა 24 ენაზე უფასოდ.

ერთი სტატია კვირაში უფასოა; დამატებითი სტატიები ფასიანი დანამატია. აირჩიეთ 'შესაძლოა მსუბუქად დავარედაქტიროთ + დავამატოთ შიდა ბმულები' ან 'გამოქვეყნება უცვლელად'. გამოაგზავნეთ და თვალი ადევნეთ განხილვის სტატუსს აქ: Developers → Submit news.

Multi-Checkpoint API (/api/v1/data/multi) ახლა კვოტას ანგარიშობს როგორც ⌈(N PPIDs × sub-products) / 2⌉ — ეკვივალენტური ინდივიდუალური ზარების ნახევარი ღირებულება. მოთხოვნა 10 საკონტროლო პუნქტისთვის ორივე sub-product-ით ახლა ღირს 10 ერთეული 20-ის ნაცვლად. X-Devapi-Units ჰედერი და meta.units_consumed პასუხში ასახავს ფასდაკლებულ ოდენობას.

მიიღეთ ცოცხალი რიგის სტატუსი და მონაცემთა სიახლე 20-მდე საკონტროლო პუნქტისთვის ერთ API ზარში — შექმნილია დაფის შემქმნელებისთვის, რომლებიც ამჟამად ბევრ PPID-ს ითხოვენ ციკლში.

კვოტა სამართლიანად ითვლება როგორც N PPIDs × sub-products მოთხოვნილი, ასე რომ საერთო მოხმარება იდენტურია ინდივიდუალური ზარებისა — მაგრამ ერთი მიმოცვლით ბევრის ნაცვლად. GreenTravel-ის სტილის შაბლონები 24+ ზარიდან/საათში 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, სავარაუდო wait_min, მონაცემთა ასაკი და საკონტროლო პუნქტის სახელი
• include=update-info — მონაცემთა სიახლე, წყაროს კლასიფიკაცია, ასაკი წამებში/წუთებში
• მაქსიმუმ 20 PPID მოთხოვნაზე; დააკომბინირეთ ორივე sub-product ერთ ზარში დაფის სრული მონაცემებისთვის
• პასუხი შეიცავს meta.units_consumed-ს, რათა ზუსტად აკონტროლოთ კვოტის მოხმარება

queue პროდუქტის პასუხი ახლა შეიცავს ზედა დონის snapshot ობიექტს უახლესი რეალურ დროის მონაცემებით და გამოთვლილი პროგნოზირებული მოცდის დროით — იგივე ფორმულა, რომელიც გამოიყენება nakordoni.eu-ს hero სექციაზე:

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

data მასივი (ისტორიული ჩანაწერები) უცვლელია — ეს არის წმინდა დამატებითი დამატება. კლიენტები, რომლებიც არ კითხულობენ snapshot-ს, ხელუხლებელნი არიან.

მოითხოვეთ ყველა საკონტროლო პუნქტი მოცემულ საზღვარზე + ტრანსპორტის ტიპი ერთ ზარში, თითო PPID-ზე თითო მოთხოვნის გაკეთების ნაცვლად.

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

• მხარს უჭერს ერთ დანიშნულების ქვეყანას, მძიმით გამოყოფილ სიას ან all-ს ყოველ მონიტორინგირებულ მეზობელზე ერთბაშად გასაფართოებლად.
• შედეგები დალაგებულია queue_now-ის ზრდადობით (ყველაზე მოკლე რიგი პირველი).
• სრულად ლოკალიზებული: დაამატეთ ?lang=uk (ან ჩვენი 22 მხარდაჭერილი ენიდან ნებისმიერი), რომ მიიღოთ საკონტროლო პუნქტების სახელები იმ ენაზე.

აღმოაჩინეთ საკონტროლო პუნქტის PPID მნიშვნელობები სახელით, სრული დირექტორიის დათვალიერების გარეშე.

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

• იღებს ერთ სახელს ან მძიმით გამოყოფილ სიას (20-მდე).
• ეძებს ყველა 24 თარგმანის ენაში — გადაეცით სახელი უკრაინულად, პოლონურად, გერმანულად ან ნებისმიერ მხარდაჭერილ ენაზე და ის დაემთხვევა.
• აბრუნებს ყველა PPID-ს ამ ლოკაციაზე ტრანსპორტის ტიპის მიხედვით დაჯგუფებულს (car / bus / pedestrian / truck).

alternatives პროდუქტი ახლა იღებს ?lang=-ს ყველა 22 მხარდაჭერილ ენაზე (იყო მხოლოდ 12).

ახალი crossing_type პარამეტრი გაძლევთ ტრანსპორტის ტიპის ფილტრის გადაფარვის შესაძლებლობას — მაგ. გადაეცით crossing_type=4, რომ მიიღოთ ავტომობილის ალტერნატივები მაშინაც კი, როცა ითხოვთ bus PPID-დან.

crossing_type_label ველი checkpoints, border და search პასუხებში ახლა თარგმნილია მოთხოვნილ ენაზე ყველა 22 მხარდაჭერილ ენაზე. ქვეყნის სახელის ველები (origin_name, destination_name) იგივე ლოკალს მიჰყვება.

Nakordoni Developer API პორტალი ცოცხალია აქ: /en/developers. დარეგისტრირდით უფასო Explorer გასაღებისთვის (200 requests/day), რომ მიიღოთ წვდომა სასაზღვრო რიგის მონაცემებზე, პროგნოზებზე, საწვავის ფასებზე, მძღოლების POI-ებზე და სხვა.

ამოქმედებისას ხელმისაწვდომი პროდუქტები: checkpoints, queue, stats, day-stats, forecast, alternatives, update_info, fuel, pois, truck_bans, trading_sundays, bus_carriers, road_conditions, assistant.