תיעוד 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",
  "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, bad_request, internal_error) וסטטוס HTTP 401/403/404/429/500. כותרות ה־rate limit — X-Devapi-Limit ו־X-Devapi-Remaining — נשלחות בכל תגובה שנספרת במכסה.

מכסות

המונים היומיים מתאפסים בחצות לפי 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→EU (crossing_type=9):

let
    ApiKey = "NKD-DEV-XXXX-XXXX-XXXX",
    Source = Json.Document(Web.Contents("https://nakordoni.eu/api/v1/data/border/1/all/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 כדי לקרוא עד 20 מעברי גבול בבקשה אחת במקום בלולאה.

שרת 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" }
    }
  }
}

מוצרים

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

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

תורים בגבול

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

דלק ומיקומים

תכנון מסלול

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

עוזר 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" בכל מקום שבו מוצגים הנתונים. זה מה ששומר על התוכנית החינמית חינמית.

הקוד המדויק

העתיקו את הקטע הזה כמו שהוא. הקישור חייב להישאר ניתן לאינדוקס: תגית HTML רגילה <a href> שמנועי חיפוש יכולים לעקוב אחריה — אל תוסיפו rel="nofollow" או rel="sponsored", אל תרנדרו אותו רק דרך JavaScript ואל תסתירו אותו באמצעות CSS.

<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/ — כל קישור ניתן לאינדוקס אל nakordoni.eu נחשב. טקסט העוגן "Data by nakordoni.eu" חייב להישאר באנגלית.

איפה למקם

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

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

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