תיעוד API

אימות

כל בקשה דורשת את מפתח ה־API שלכם בכותרת Authorization (מומלץ) או כפרמטר ?key=.

curl "https://nakordoni.eu/api/v1/data/queue?ppid=id_13" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"

מבנה התגובה

{
  "ok": true,
  "api_version": "v1",
  "product": "queue",
  "attribution": "Data by nakordoni.eu",
  "terms": "https://nakordoni.eu/en/p/developer_api_terms",
  "data": { ... },
  "usage": { "limit": 1000, "used": 42, "reset": "2026-06-06T00:00:00Z" }
}

שגיאות מחזירות ok:false עם error.code (missing_api_key, invalid_api_key, qps_exceeded, quota_exceeded, unknown_product, product_unavailable, not_approved, bad_request, duplicate_request, market_not_allowed, internal_error, status_unavailable, timeout) וסטטוס HTTP 400/401/403/404/429/500/503/504. כותרות ה־rate limit — X-Devapi-Limit ו־X-Devapi-Remaining — נשלחות בכל תגובה שנספרת במכסה. ok:false הוא הקובע — לעולם אל תקראו את data בקריאה שנכשלה. אובייקט usage קיים בכל מוצר מחויב; /status ציבורי ואינו מחויב, ולכן אינו מחזיר usage.

מכסות

המונים היומיים מתאפסים בחצות לפי UTC. תקבלו אימייל בהגעה ל־80% ול־100% מהמכסה.

תוכניות בתשלום מעלות כל אחת מהמגבלות האלה. התוכניות הנוכחיות והמכסות שלהן: תוכניות

דוגמאות קוד

curl

curl "https://nakordoni.eu/api/v1/data/queue?ppid=id_13" \
  -H "Authorization: Bearer $NKD_API_KEY"

JavaScript (fetch)

const res = await fetch('https://nakordoni.eu/api/v1/data/forecast?ppid=id_13&prediction_steps=24', {
  headers: { Authorization: `Bearer ${process.env.NKD_API_KEY}` }
});
const { ok, data, error, usage } = await res.json();
if (!ok) throw new Error(error?.code ?? res.status);
console.log(`forecast points: ${data.length}, calls left today: ${usage.limit - usage.used}`);

Python (requests)

import os, requests

r = requests.get(
    "https://nakordoni.eu/api/v1/data/stats",
    params={"ppid": "id_15", "compare": 1},
    headers={"Authorization": f"Bearer {os.environ['NKD_API_KEY']}"},
    timeout=15,
)
payload = r.json()
print(payload["data"]["daily"], payload["usage"])

Excel (Power Query)

משכו נתוני תור, תחזית או איסורי משאיות ישירות לחוברת עבודה עם מחבר ה-JSON המובנה של Power Query — בלי קוד, עם רענון מתוזמן. אותה תבנית Headers עובדת עבור כל מוצר ב-API הזה — רק צריך להחליף את ה-URL.

Data → Get Data → From Other Sources → Blank Query, then Home → Advanced Editor and paste:

let
    ApiKey = "NKD-DEV-XXXX-XXXX-XXXX",
    Source = Json.Document(Web.Contents("https://nakordoni.eu/api/v1/data/queue",
        [Query = [ppid = "id_13"], Headers = [Authorization = "Bearer " & ApiKey]])),
    data = Source[data],
    AsTable = Record.ToTable(data)
in
    AsTable

שמרו את מפתח ה-API בתוך שאילתת ה-M (Home → Advanced Editor), לא בתא בגיליון — Power Query חוסם בקשת רשת שנבנתה משאילתה או תא אחר ("Formula.Firewall"), אלא אם רמת הפרטיות מוגדרת כ-Organizational.

כמה מעברי גבול בטבלה אחת (לוחות בקרה לצי רכבים) — e.g. every truck crossing UA→PL (crossing_type=9; in v3 that one code covers both freight lanes):

let
    ApiKey = "NKD-DEV-XXXX-XXXX-XXXX",
    Source = Json.Document(Web.Contents("https://nakordoni.eu/api/v4/data/border/1/2/9",
        [Headers = [Authorization = "Bearer " & ApiKey]])),
    checkpoints = Source[data],
    AsTable = Table.FromRecords(checkpoints)
in
    AsTable

Data → Refresh All ב-Excel, או רענון מתוזמן ב-Power BI / Excel Online, שומר על נתונים עדכניים — בלי קוד polling.

אינטגרציה עם ERP (‏BAS / BAF ופלטפורמות ממשפחת 1C)

BAS / BAF ופלטפורמות אחרות ממשפחת 1C יכולות לקרוא ל-API הזה ישירות ממשימה מתוזמנת — HTTPConnection יחד עם ReadJSON, בלי שכבת ביניים ובלי שירות נוסף לתחזק. התצורה הנפוצה ביותר מחזיקה מרשם מידע מעודכן של מחירי דלק באיחוד האירופי.

רענון מרשם מידע (מחירי דלק, כל המדינות בקריאה אחת)

// Scheduled job — runs once a day
Connection = New HTTPConnection("nakordoni.eu", 443, , , , 30, New OpenSSLSecureConnection);

Headers = New Map;
Headers.Insert("Authorization", "Bearer NKD-DEV-XXXX-XXXX-XXXX");

Request  = New HTTPRequest("/api/v1/data/fuel", Headers);
Response = Connection.Get(Request);

Reader = New JSONReader;
Reader.SetString(Response.GetBodyAsString("UTF-8"));
Answer = ReadJSON(Reader, True);
Reader.Close();

If Answer["ok"] <> True Then
    // Answer["error"]["code"] says why; Answer["usage"] holds your quota state
    Return;
EndIf;

For Each Row In Answer["data"] Do
    Record = InformationRegisters.FuelPrices.CreateRecordManager();
    Record.Period   = CurrentSessionDate();
    Record.Country  = Row["country"];    // "PL", "DE", "SK", "RO", ...
    Record.Diesel   = Row["diesel"];
    Record.Petrol   = Row["petrol"];
    Record.LPG      = Row["lpg"];
    Record.Currency = Row["currency"];
    Record.Write();
EndDo;

שלושה דברים שחשוב לדייק בהם: העבירו New OpenSSLSecureConnection דרך פורט 443, אחרת הבקשה תיפול על TLS; קראו ל-/api/v1/data/fuel בלי הפרמטר country כדי שבקשה אחת תחזיר את כל המדינות במקום קריאה לכל מדינה; ובדקו את ok לפני שנוגעים ב-data — כשלים חוזרים כ-ok:false עם error.code, לא כחריגה. הדוגמה משתמשת בסט מילות המפתח האנגלי של הפלטפורמה; המקבילות המתורגמות (HTTPСоединение, ПрочитатьJSON, РегистрыСведений) פועלות באופן זהה.

מחירי הדלק במקור משתנים פעם ביום, ולכן משימה מתוזמנת פעם או פעמיים ביום מספיקה ונשארת הרחק בתוך המכסה החינמית של Explorer. נתוני התורים החיים (queue, multi, border) משתנים כל כמה דקות — תשאלו אותם בקצב משלכם והשתמשו ב-multi כדי לקרוא עד 5 מעברי גבול בבקשה אחת במקום בלולאה.

שרת MCP

מעדיפים קריאה לכלים במקום REST? אנחנו מפעילים שרת MCP אמיתי (תעבורת Streamable HTTP) שחושף תת-קבוצה בטוחה וניתנת לקריאה בלבד של ה-API הזה ככלי MCP — אותו מפתח API, אותה מכסה, רק תעבורה שונה.

Endpoint: https://nakordoni.eu/mcp · Server card: /.well-known/mcp/server-card.json

get_api_status      — no key required
list_checkpoints     — country, lang
get_border_queue     — origin, destination, crossing_type, lang
get_live_queue       — ppid, lang
get_queue_forecast   — ppid, prediction_steps

הגדרת לקוח (Claude Desktop / Claude Code):

{
  "mcpServers": {
    "nakordoni": {
      "url": "https://nakordoni.eu/mcp",
      "headers": { "Authorization": "Bearer NKD-DEV-XXXX-XXXX-XXXX" }
    }
  }
}

Country and vehicle-type codes

Border endpoints address countries and vehicle types by numeric id: /api/v1/data/border/{origin}/{destination}/{crossing_type}. destination also accepts a comma-separated list or the word all. The ids are stable and are the same in every product that takes an origin, a destination or a crossing_type.

Country ids

The border products accept the ids marked as origins below; the neighbours column is what destination=all expands to for that origin. Ids without neighbours are countries we name in responses but hold no crossings for yet. The Checkpoints Directory returns the origin, destination and crossing_type of every crossing we actually serve, so it stays the authoritative list.

Vehicle types (crossing_type)

The label in this table is the crossing_type_label the API returns with every response, in the language you request. Types outside the accepted list belong to crossings the directory carries but the border products do not answer for — ferry (10-13), freight up to 3.5 t (14) and rail (15) — and asking for one returns 400, not an empty result. Read crossing_type from the Checkpoints Directory rather than assuming: a crossing returns data only for the types it actually has.

מוצרים

בחרו נקודת קצה כדי לראות את המדריך המלא שלה, הפרמטרים, הגרסאות ו־Sandbox חי.

סטנדרטי נשען על מכסת הנתונים הסטנדרטית  ·  כבד נשען על מכסת התחזיות והסטטיסטיקות — ראה מכסות  ·  מסלול משאיות נגרע ממכסת מסלול המשאיות הייעודית שלו — ראה מכסות

תורים בגבול

תחזיות וסטטיסטיקה

דלק ומיקומים

תכנון מסלול

לוגיסטיקה

נהגים וכבישים

Your Fleet (NakBus Live)

עוזר AI

אחר

ייצוא נתונים היסטוריים

מפתחים מאושרים יכולים להוריד היסטוריית תורים בגבול שפורסמה, בממוצעים שעתיים, עבור עד 5 מעברי גבול (חלון נע של עד 90 יום) בפורמט CSV מכווץ ב־gzip, NDJSON או JSON. זו יכולת של הפורטל בלבד — ולא נקודת קצה של ה־API; את הייצוא בונים ומורידים מלשונית "ייצוא נתונים" בחשבון שלכם.

הגישה ניתנת לפי בקשה: פתחו פנייה מסוג Data וציינו אילו מעברי גבול, איזה טווח זמן ולאיזה שימוש. לאחר האישור מופיעה בחשבונכם לשונית "ייצוא נתונים". מגבלת ברירת מחדל: ייצוא אחד ביום, עד 5 מעברי גבול בכל אחד — בקשו מאיתנו להגדיל אותה.

שדות — שורה אחת לכל מעבר גבול לכל שעת UTC

מיוצאים רק נתונים שפורסמו, והם עוברים את בדיקות החריגות ואיכות הנתונים שלנו לפני הייצוא (בלי נתוני דיווח גולמיים). כל חותמות הזמן ב־UTC. הקבצים נשמרים 10 ימים.

מקוריות: בכותרת של כל קובץ מוטבעת חתימה חתומה (sha256 + HMAC), כך שאפשר לאמת בהמשך שכל עותק הוא נתון אותנטי של nakordoni.eu ולבדוק שלא בוצע בו שינוי — גם אחרי ההורדה.

# sha256: 3f9c…   # signature: e87b…
ppid,checkpoint_name,hour_utc,direction,vehicle_type,avg_queue_length,avg_wait_minutes,sample_count
id_10,Hrushiv,2026-06-12T02:00:00Z,UA->PL,car,11,,4

מה אפשר לבנות

אותם מוצרי נתונים מייצרים את התצוגות ב־nakordoni.eu — גרפי תחזית שבועיים, פרופילי תור לפי שעה, כרטיסי סטטוס בזמן אמת. טעימה ממה שיש ב־API התחזיות והסטטיסטיקה:

מתן קרדיט

אינטגרציות בתוכנית Explorer חייבות להציג קישור גלוי "Data by nakordoni.eu" בכל מקום שבו מוצגים הנתונים. זה מה ששומר על התוכנית החינמית חינמית.

הקוד המדויק

העתיקו את קטע הקוד כפי שהוא. הקישור חייב להישאר ניתן לאינדוקס: <a href> HTML גלוי ופשוט ליד הנתונים, ש-Google יכול לאנדקס ולעקוב אחריו — אין להוסיף rel="nofollow", rel="sponsored" או rel="ugc" ואין להסתיר אותו באמצעות CSS. קישור שנוסף באמצעות JavaScript תקין אם הוא מופיע בדף ש-Google מרנדר (תנאי Developer API v1.0, סעיף 8.1).

<a href="https://nakordoni.eu/" title="Border queues, forecasts &amp; statistics">Data by nakordoni.eu</a>

גרסה קומפקטית באותיות קטנות (למשל מתחת לגרף או לווידג׳ט):

<p style="font-size:12px;margin:4px 0">
  Data by <a href="https://nakordoni.eu/">nakordoni.eu</a>
</p>

אפשר לקשר גם לגרסת השפה שלך, למשל https://nakordoni.eu/he/ — כל קישור HTML רגיל וגלוי אל nakordoni.eu נחשב. טקסט העוגן "Data by nakordoni.eu" חייב להישאר באנגלית.

איפה למקם

• ממש לצד בלוק הנתונים או מתחתיו (טבלה, גרף, ווידג׳ט, תשובה) — באותו מסך, גלוי בלי קליקים נוספים.
• בכל עמוד או מסך באפליקציה שבו מופיעים הנתונים שלנו — לא רק בעמוד "אודות".
• גודל וניגודיות קריאים: לפחות ~11px, לא מוסתר, לא מקופל, ולא בצבע הרקע.
• אפליקציות מובייל נייטיביות ללא קישורי HTML: הציגו את הטקסט "Data by nakordoni.eu" במסך הנתונים, ומקמו קישור לחיץ במסך המידע/אודות.

אנו בודקים מדי פעם את הקרדיט ב"עמוד שבו נעשה שימוש בנתונים" שציינת בהרשמה. קרדיט חסר או מוסתר בתוכנית Explorer החינמית מוביל תחילה לתזכורת ולאחר מכן להשעיית המפתח. לקוחות בתוכנית בתשלום רשאים לוותר על הקרדיט.

הבדיקות מתבצעות בערך פעם בשבוע על ידי הבודק שלנו, שה-user agent שלו מכיל NakordoniComplianceBot/1.0. הוא פותח רק את הדפים שרשומים בלוח הבקרה למפתחים שלכם, אינו עוקב אחרי קישורים אחרים ומתעלם מ-robots.txt עבור הדפים האלה, כי אלה בדיוק הדפים שביקשתם שנבדוק. אם הגנה מפני בוטים או חומת אש חוסמת סורקים לא מוכרים, אפשרו את ה-user agent הזה — אם לא נצליח לפתוח דף, נכתוב לכם בפנייה.

רישיון נתונים ושווקים

מפתח ה-API שלכם מעניק רישיון לשימוש בנתונים שלנו רק במדינות שהצהרתם עליהן בעת ההרשמה. אנו בודקים כל הצהרה לפני הענקת גישה מלאה, מכיוון שהנתונים שלנו הם המוצר שלנו, ואיננו מעניקים עליהם רישיון לשווקים מבלי לדעת היכן הם יפורסמו.

• הצהירו על כל מדינה שהאתר, האפליקציה או המוצר שלכם משרתים. תוכלו לשנות את הרשימה בכל עת מהדשבורד שלכם; שינוי מחזיר את החשבון שלכם לבדיקה.
• עד לאישור השווקים שלכם, המפתח שלכם פועל במגבלות מופחתות - מחצית ממכסת תוכנית ה-Starter. זה חל ללא קשר לתוכנית שבה אתם נמצאים.
• אנו עשויים לאשר רק חלק מהמדינות שביקשת. הרשימה המאושרת, ולא זו שביקשת, היא זו המכסה את המדינות שברישיון שלך.
• פרסום או הפצה מחדש של הנתונים שלנו בשוק שלא הצהרתם עליו, או מכירתם מחדש כפיד נתונים מתחרה, מהווים הפרה של תנאים אלה ועלולים להשעות את המפתח שלכם ללא התראה.
• חלק מהתוכניות מוצעות רק באזורים נבחרים. הזמינות תלויה בשווקים שאתם מצהירים עליהם.
• ההסכם המלא הוא תנאי ה-Developer API. הם גוברים על התקציר הזה; הנוסח המחייב הוא האנגלי.

טריות הנתונים

עדכניות הנתונים תלויה בתוכנית שלך. בתגובה עצמה אין שום סימון — כל התוכניות מחזירות את אותם שדות, אותם טיפוסים ואותו מבנה תגובה.

• תוכניות בתשלום — Student, Starter, Pro ו-Pro MAX: טלמטריה חיה, ללא השהיה.
• תוכנית Explorer החינמית: תמונת מצב מ-15 עד 30 הדקות האחרונות. הפער המדויק משתנה מבקשה לבקשה.

תגובה מושהית אינה שגיאה ואינה בעיית מכסה — זו תגובה מלאה ותקפה עם מספרים ישנים יותר. שליחה חוזרת של הבקשה לא תחזיר נתונים עדכניים יותר.

אם היישום שלך זקוק לנתונים עדכניים, כל תוכנית בתשלום מחזירה טלמטריה בזמן אמת.

קבלו מפתח API בחינם