יומן השינויים של ה־API

תכננו נסיעה חוצת גבול שלמה בקריאה אחת: /api/v2/data/route-plan מחזיר את המסלול, את מעברי הגבול שנמצאים עליו באמת עם התור החי או תחזית לשעת ההגעה שלכם, ואת העצירות שנהג באמת עושה — מנוחה, אוכל, תדלוק — הכול על ציר זמן אחד.

הגבול הוא חלק מציר הזמן הזה. תור ארוך נחשב כהפסקה שממילא הגיע זמנה ומאפס את שעון הנהיגה, ולכן שלוש שעות המתנה לעולם אינן מוצגות כשלוש שעות ועוד מערך שלם של הפסקות שאיש לא עשה. למכוניות פרטיות חל מודל נהיגה בטוחה; אוטובוסים ומשאיות מקבלים את מנוחת החובה לפי EU 561/2006, וזמן השירות של האוטובוסים מכויל על יותר מ-1000 לוחות זמנים בינלאומיים מורשים. הוסיפו stop_places=1 כדי לתת לכל עצירה חניון או תחנת דלק אמיתיים, ו-via=lat,lon כדי לעבור במעבר אחר.

New in the portal menu: Presentation — a live, always-current pitch of the nakordoni data platform personalized for your market (insurance, travel, logistics, carriers, media, navigation, fuel, fintech, public sector or personal projects). It shows real 30-day platform volumes, your own API usage, response-time and limit statistics, and a plan recommendation when your calls hit the free-tier limits. Pick or confirm your market(s) on the page, in your profile — or during signup. It opens automatically on your first visit; you can turn the auto-open off on the page itself.

If an assistant has a feed enabled but the call does not carry the context that feed needs — queue without a ppid, for example — the feed is now skipped before any request is made and is not charged. Previously it was called anyway, failed, and still cost a unit. The studio shows what each feed needs, recalculates the price as you fill the context in, and marks results ✓ ran / ⊘ skipped, not charged / ✕ failed; the API returns data.feeds_skipped telling you exactly which parameter to pass.

Answers no longer mention feeds, data sources or anything technical: a missing feed is at most one plain sentence to the end user, never an internal name. Feeds with only optional filters (such as fuel narrowed to a country we have no data for) now fall back to the broad dataset instead of returning nothing.

New: /{lang}/developers/studio. Build an AI assistant that answers from your content and our live border data. Give us your markdown, or just name the pages and we fetch and index them — you only ever maintain your own files. Pick which of our feeds it may use (queue, forecast, alternatives, day-stats, fuel, truck bans, trading Sundays, holidays, road conditions, bus carriers, POIs, currency), pick a model tier (fast / balanced / pro — that is what sets the price), write your own instructions with {{feed.slug}} placeholders saying exactly where our data lands in the answer, and add a closing sentence of your own that is appended to every reply. Ready-made blueprints: personal travel assistant, work/freight assistant, insurance & Green Card sales assistant.

Test it in the studio (30 answers/day, separate from your API quota), then call it in production at GET /api/v2/data/assistant-custom?assistant_id=N&q=…. Price per answer = model tier units + 1 unit per enabled feed, returned in X-Devapi-Units. The product is v2-only — a v1 URL returns unsupported_version. The existing assistant product is unchanged.

Every assistant runs under a platform content policy that outranks your instructions: no impersonating officials, no help evading border or customs control, no invented numbers, no profanity. Instructions and answers are both screened; blocked calls are logged.

חדש: שרת 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 להיות מחויבת פעמיים - פעם אחת בבדיקה גנרית של יחידה אחת, ופעם נוספת בנוסחת העלות המשתנה של ה-endpoint עצמו (N PPID × תת-מוצרים). כעת קריאה עולה בדיוק ⌈(N×M)/2⌉ יחידות כפי שמתועד, ללא חיוב נוסף.

בנוסף, בעמוד התיעוד נוסף תג מחלקת מכסה (Standard/Heavy) לכל מוצר, כך שברור במבט אחד באיזו מכסה יומית endpoint משתמש.

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), מסנן אופציונלי לפי מדינה וסטטוס «פעיל כעת» חי. אין צורך במפתח API. הגדירו והעתיקו את הקוד בכתובת nakordoni.eu/en/for_truck_drivers/traffic_bans/widget. מעדיפים נתונים גולמיים? מוצר ה-API בשם truck-bans וה-feed הציבורי בפורמט JSON נותרים זמינים.

שלוש תוספות, כולן תואמות לאחור — v1 ללא שינוי.

גרסאות לכל endpoint. קיימת כעת כתובת בסיס /api/v2/. היא פועלת לכל endpoint: רק endpoints שהשתנו בפועל מתנהגים אחרת תחת v2; כל endpoint אחר מגיש בשקיפות את תגובת v1 שלו (כלומר /api/v2/data/queue = אותם נתונים כמו v1, רק עם "api_version":"v2"). אין צורך להגר endpoints שעובדים.

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} וערך boolean בשם stale, ו-?max_age_min=N מחזיר רק מעברים שעודכנו לאחרונה. (v1 border עדיין מחזיר את שני צדי הגבול ללא תלות בסדר — ללא שינוי.)

Sandbox אינטראקטיבי. מפתחים מחוברים יכולים כעת לנסות כל endpoint מהדפדפן בכתובת Developers → Sandbox — בחרו endpoint, גרסה ואחד מהמפתחות שלכם, כווננו פרמטרים וראו את התגובה החיה. לבדיקות Sandbox יש תקציב יומי נפרד משלהן (50 קריאות ליום) והן לעולם אינן נוגעות במכסת ה-API החיה שלכם.

התיעוד מפוצל כעת לכל endpoint (Developers → API Docs) עם בורר גרסה על endpoints שיש להם יותר מגרסה אחת.

שני גורמים חדשים שולבו בנוסחת זמן ההמתנה, לצד כיווני 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, הערות pipeline פנימיות, שדות לא בשימוש/מתים) ללא ערך מוצרי אמיתי:

• id ו-corrected — הוסרו מאובייקטי השורה של queue
• tmin/tpercar — הוסרו מ-queue, border ו-multi (קבועי נוסחת זמן ההמתנה; wait_min/wait_time שכבר חושבו אינם מושפעים)
• source (מחרוזת גולמית, למשל "line") — הוסר מ-queue, multi ו-update-info. בלוק ה-update_info של update-info ו-multi עדיין נושא source_category/source_label_en (אוצר מילים ציבורי קטן); בלוק ה-queue של queue ו-multi כבר אינו נושא שום שדה 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 השעות האחרונות). תוספתי בלבד.

בשורות data[] של /api/v1/data/queue היה בעבר wait_time: null עבור רוב המקורות — רק כמה הזנות upstream מדווחות זמן המתנה ישירות. שורות ללא זמן כזה מקבלות כעת את ההערכה הסטנדרטית tmin + queue×tpercar, מסומנות ב-boolean חדש בשם wait_time_estimated כדי שתוכלו להבחין בין נתון מדווח אמיתי לבין מחושב.

queue-advanced עולה כעת 1.5 יחידות לכל קריאה במקום 1 (משקף את חיפושי התנועה/מזג האוויר/דיווחי הנהגים הנוספים שהוא מבצע) — ראו 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 משתמש כעת באופן אמין במודל ה-ensemble v4 עבור כל ערך prediction_steps (בעבר חלק מהאופקים הלא-סטנדרטיים היו יכולים לחזור בשקט למודל ישן יותר). גם גורם מזג האוויר המזין את ה-ensemble תוקן וכעת משקף באמת תנאים חיים (גשם, שלג, רוח, ערפל) במקום לדווח תמיד שאינו זמין.

מפתחים מאושרים יכולים כעת להוריד נתוני תור גבול היסטוריים בממוצע שעתי עבור עד 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 × מוצרי-משנה) / 2⌉ — מחצית מהעלות של קריאות בודדות שוות ערך. בקשה ל-10 מעברי גבול עם שני מוצרי-המשנה עולה כעת 10 יחידות במקום 20. הכותרת X-Devapi-Units ו-meta.units_consumed בתגובה משקפים את הסכום המוזל.

קבלו סטטוס תור חי ורעננות נתונים עבור עד 20 מעברי גבול בקריאת API אחת — מיועד לבוני לוחות בקרה שכיום סוקרים PPIDs רבים בלולאה.

המכסה נספרת בהוגנות כ-N PPIDs × מוצרי-משנה שהתבקשו, כך שהשימוש הכולל זהה לקריאות בודדות — אך עם הלוך-ושוב אחד במקום רבים. דפוסים בסגנון 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 PPIDs לכל בקשה; שלבו את שני מוצרי-המשנה בקריאה אחת לקבלת נתוני לוח בקרה מלאים
• התגובה כוללת meta.units_consumed כדי שתוכלו לעקוב אחר ניצול המכסה בדיוק

תגובת המוצר queue כוללת כעת אובייקט snapshot ברמה העליונה עם הנתונים העדכניים ביותר בזמן אמת וזמן המתנה חזוי מחושב — אותה נוסחה המשמשת בקטע ה-hero של 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

מערך ה-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 שפות התרגום — העבירו שם באוקראינית, פולנית, גרמנית או כל שפה נתמכת והוא יתאים.
• מחזיר את כל ה-PPIDs באותו מיקום מקובצים לפי סוג רכב (מכונית / אוטובוס / הולך רגל / משאית).

המוצר alternatives מקבל כעת ?lang= בכל 22 השפות הנתמכות (בעבר רק 12).

פרמטר crossing_type חדש מאפשר לכם לדרוס את מסנן סוג הרכב — למשל העבירו crossing_type=4 כדי לקבל חלופות למכוניות גם בעת שאילתה מ-PPID של אוטובוס.

שדה crossing_type_label בתגובות checkpoints, border ו-search מתורגם כעת לשפה המבוקשת בכל 22 השפות הנתמכות. שדות שם המדינה (origin_name, destination_name) עוקבים אחר אותה שפה.

פורטל ה-Nakordoni Developer API פעיל בכתובת /en/developers. הירשמו למפתח Explorer חינמי (200 בקשות ליום) כדי לגשת לנתוני תור גבול, תחזיות, מחירי דלק, נקודות עניין לנהגים ועוד.

מוצרים זמינים בהשקה: checkpoints, queue, stats, day-stats, forecast, alternatives, update_info, fuel, pois, truck_bans, trading_sundays, bus_carriers, road_conditions, assistant.