API לנתוני רכב בישראל — מדריך למפתחים 2026

עודכן: אוגוסט 2026 • מדריך טכני מאת lior_Ai • רלוונטי ל-JavaScript, Python וכל שפה שיודעת לעשות HTTP GET

1. המודל: מאגרים פתוחים ולא API מוצר

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

המשמעויות המעשיות:

• שמות השדות בעברית ואינם מובטחים. עמודות נקראות למשל mispar_rechev, tozeret_nm, shnat_yitzur — בתעתיק לטיני של עברית, ולעיתים באיות לא עקבי בין מאגרים. אף אחד לא התחייב לשמור על השמות האלה, ובפועל הם משתנים מדי פעם.
• אין גרסאות. אין /v1/ שיגן עליך משינוי סכמה.
• מזהה המשאב (resource_id) יכול להתחלף. כשמפרסמים גרסה חדשה של מאגר, לפעמים נוצר משאב חדש עם מזהה חדש. קוד שמקודד את המזהה קשיח יישבר בשקט.
• אין SLA. הפורטל הוא שירות ציבורי, לא תשתית מוצר. הוא נופל, מאט, ומחזיר 502 בשעות עומס.

2. הנקודה היחידה שצריך להכיר — datastore_search

כל השליפות עוברות דרך כתובת אחת:

https://data.gov.il/api/3/action/datastore_search

זו קריאת GET רגילה עם פרמטרים ב-query string, ללא אימות וללא מפתח. הפרמטרים שבאמת חשובים:

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

איפה משיגים את ה-resource_id

לא נכתוב כאן מזהי UUID. מזהים מומצאים או מיושנים הם הדרך המהירה ביותר להישבר בייצור, והמזהים האמיתיים מתחלפים. קח אותם מהמקור:

• עמוד המאגר המרכזי: רכבים פרטיים ומסחריים — data.gov.il. בכל משאב בעמוד יש כפתור/לשונית API שמציגה את המזהה ואת כתובת השאילתה המלאה.
• רשימת המאגרים שאנחנו בפועל משתמשים בהם, מרוכזת בעברית: car.lior-ai.com/sources.html.
• סריקה פרוגרמטית של הקטלוג: https://data.gov.il/api/3/action/package_list ואז package_show?id=... לקבלת המשאבים של כל מאגר.

3. דוגמת curl

חיפוש מספר רישוי עם התאמה מדויקת, באמצעות filters. שים לב לקידוד ה-JSON ב-URL — עם curl נוח להשתמש ב---data-urlencode יחד עם -G, כדי לא לקודד ידנית:

curl -sG "https://data.gov.il/api/3/action/datastore_search" \
  --data-urlencode 'resource_id=RESOURCE_ID' \
  --data-urlencode 'filters={"mispar_rechev":"1234567"}' \
  --data-urlencode 'limit=5' \
  -H 'Accept: application/json'

וגרסת החיפוש החופשי, שימושית כשאינך בטוח בשם העמודה במאגר הספציפי:

curl -sG "https://data.gov.il/api/3/action/datastore_search" \
  --data-urlencode 'resource_id=RESOURCE_ID' \
  --data-urlencode 'q=1234567' \
  --data-urlencode 'limit=5'

אם אתה מעדיף לבנות את ה-URL בעצמך, זכור שסימני {, } ו-" חייבים להיות מקודדים. שאילתת filters שנשלחת בלי קידוד תקין תחזור עם שגיאת ולידציה, ולא עם תוצאה ריקה — מה שדווקא נוח לדיבוג.

לגלות אילו עמודות קיימות במשאב לפני שמסננים לפיהן — פשוט שלוף רשומה אחת וקרא את המפתחות:

curl -sG "https://data.gov.il/api/3/action/datastore_search" \
  --data-urlencode 'resource_id=RESOURCE_ID' \
  --data-urlencode 'limit=1' | python3 -m json.tool | head -60

4. דוגמת JavaScript fetch

אותה שליפה מצד לקוח או מ-Node. שים לב ל-URLSearchParams, שמטפל בקידוד עבורך, ולטיפול בשגיאות שמפריד בין כשל HTTP לכשל לוגי:

const BASE = 'https://data.gov.il/api/3/action/datastore_search';

async function lookupVehicle(resourceId, plate, { column = null, limit = 5 } = {}) {
  const params = new URLSearchParams({
    resource_id: resourceId,
    limit: String(limit),
  });

  if (column) {
    params.set('filters', JSON.stringify({ [column]: plate }));
  } else {
    params.set('q', plate);
  }

  const res = await fetch(BASE + '?' + params.toString(), {
    headers: { Accept: 'application/json' },
  });

  if (!res.ok) {
    throw new Error('datastore_search HTTP ' + res.status);
  }

  const json = await res.json();

  // CKAN מחזיר success:false עם קוד 200 בחלק מהמקרים
  if (!json.success) {
    throw new Error('datastore_search failed: ' + JSON.stringify(json.error));
  }

  return {
    records: json.result.records,
    total: json.result.total,
    fields: json.result.fields,
  };
}

// שימוש
const { records, total } = await lookupVehicle('RESOURCE_ID', '1234567', {
  column: 'mispar_rechev',
});

if (total === 0) {
  console.log('לא נמצאה רשומה');
} else {
  console.log(records[0]);
}

5. מבנה התשובה: result.records ו-result.total

התשובה עוטפת את התוצאה באובייקט קבוע. המפתחות שאתה צריך:

• success — בוליאני. תמיד לבדוק.
• result.records — מערך של אובייקטים, רשומה לשורה. כאן נמצא המידע.
• result.total — סך כל הרשומות שתאמו את השאילתה, ולא מספר הרשומות שהוחזרו. זה הנתון שמאפשר לבנות עימוד ולהחליט אם יש עוד עמודים.
• result.fields — תיאור העמודות והטיפוסים שלהן. שימושי מאוד לגילוי סכמה בזמן ריצה, במקום להניח שמות שדות.
• result.limit / result.offset — הדהוד של מה שביקשת.
• result._links — קישורי next/prev יחסיים, שאפשר להתעלם מהם ולנהל את העימוד לבד.

כל הערכים ברשומות מוחזרים לרוב כמחרוזות, גם כשמדובר בשנה או בנפח מנוע. אל תסמוך על טיפוסים: המר במפורש, וטפל בערכים חסרים, שיכולים להיות null, מחרוזת ריקה או מקף.

6. עימוד: limit ו-offset

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

async function* iterateAll(resourceId, pageSize = 1000) {
  let offset = 0;
  let total = Infinity;

  while (offset < total) {
    const params = new URLSearchParams({
      resource_id: resourceId,
      limit: String(pageSize),
      offset: String(offset),
    });

    const res = await fetch(BASE + '?' + params.toString());
    const json = await res.json();
    if (!json.success) throw new Error('page failed at offset ' + offset);

    total = json.result.total;
    const batch = json.result.records;
    if (batch.length === 0) break;

    yield batch;
    offset += batch.length;

    // נשימה בין עמודים — לא להציף שירות ציבורי
    await new Promise((r) => setTimeout(r, 250));
  }
}

כמה כללי אצבע: השרת עשוי לכפות תקרה על limit, ולכן קדם על בסיס batch.length בפועל ולא על בסיס pageSize שביקשת. הוסף השהיה קצרה בין עמודים. תמיד קבע תנאי עצירה על מערך ריק, כי הסתמכות על total לבדה תיכשל אם המאגר מתעדכן בזמן הסריקה. ואם אתה באמת צריך את כל המאגר — עדיף להוריד את קובץ ה-CSV המלא מעמוד המאגר במקום לעמד מאות אלפי רשומות דרך ה-API.

7. CORS ולמה כמעט תמיד תצטרך פרוקסי

זו הנקודה שמפילה את רוב הפרויקטים בשלב הראשון. קריאה ישירה מדפדפן לכתובת של data.gov.il תלויה בכותרות ה-CORS שהפורטל מחזיר, והן אינן מובטחות ואינן יציבות לאורך זמן. גם כשזה עובד היום, אין התחייבות שזה יעבוד מחר, ואין למי לפנות. בנוסף, קריאה מהדפדפן חושפת את כל הלוגיקה שלך, לא מאפשרת קאשינג משותף בין משתמשים, ומעבירה כל שגיאה של השירות הציבורי ישירות לפני המשתמש.

הפתרון הנכון הוא שכבת ביניים משלך: פונקציית edge, serverless function או שרת קטן שמבצע את הקריאה מצד השרת ומחזיר JSON נקי ללקוח. היתרונות מצטברים במהירות:

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

אם אתה עובד עם Netlify Functions, Cloudflare Workers, Vercel או Supabase Edge Functions — כל אחת מהן מספיקה בהחלט לתפקיד. שים לב שהמדריך הזה מוגש מאתר עם מדיניות CSP קפדנית, ולכן כל דומיין חיצוני שאתה קורא אליו צריך להיות מוצהר במפורש ב-connect-src.

8. עומסים, אמינות וקאשינג

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

• קאש לפי שאילתה. נתוני מרשם משתנים בקצב של ימים, לא של שניות. TTL של שעות עד יום הוא סביר לחלוטין לרשומת רכב, וארוך יותר למאגרים שמתעדכנים לעיתים רחוקות.
• Timeout קצר וברור. עדיף להיכשל מהר ולהציג הודעה מאשר להשאיר משתמש מול ספינר שלושים שניות.
• נסיון חוזר עם השהיה מצטברת על 5xx בלבד. אין טעם לחזור על שגיאת ולידציה של 400 — היא לא תיפתר מעצמה.
• Circuit breaker. אם הפורטל מחזיר שגיאות רצופות, עצור את הקריאות לדקה והגש מהקאש.
• מקבילות מוגבלת. כשמאחדים כמה מאגרים בבדיקה אחת, הרץ אותם במקביל אבל בתקרה — לא עשרות קריאות במקביל מאותו לקוח.
• ניטור. תעד קודי תגובה וזמני תגובה. שינוי סכמה או החלפת מזהה משאב מתגלים כמעט תמיד כעלייה פתאומית בשיעור "לא נמצא".

9. נרמול מספרי רישוי בישראל

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

• הסר כל תו שאינו ספרה לפני השאילתה: מקפים, רווחים, נקודות ותווי כיווניות בלתי נראים שמודבקים מטקסט RTL.
• אורכים משתנים. בשימוש נפוץ תמצא שבע ספרות, אבל גם שש ושמונה קיימים — לפי גיל הרכב וסוגו. אל תקבע ולידציה נוקשה של שבע ספרות; היא תפסול רכבים חוקיים.
• אפסים מובילים. אם באיזה שלב עברת דרך המרה למספר, אפס מוביל נעלם. עבוד במחרוזות מקצה לקצה. אם ההתאמה נכשלת, שווה לנסות גם עם וגם בלי אפס מוביל.
• ספרות עבריות-ערביות ותווי Unicode דומים לספרות מוקלדים לפעמים בהדבקה. נרמל אותם.
• צמ״ה ודו-גלגלי משתמשים לעיתים בפורמטים ובעמודות שונות. אל תניח שאותו קוד נרמול תקף לכל סוגי הרכב.
• אל תמצא ולידציה של ספרת ביקורת. אם אינך משוכנע בנוסחה — עדיף לשלוח את השאילתה ולתת למאגר לענות.

10. המאגרים הנפרדים ומה יש בכל אחד

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

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

11. עדכניות הנתונים ומה זה אומר למשתמש

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

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

12. רישוי, ייחוס ומה אסור להצהיר

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

• ייחוס. ציין בבירור שהמידע מגיע מנתונים ציבוריים פתוחים של data.gov.il. זה גם דורש אמון וגם מציל אותך מטענות בעלות.
• אי-השתייכות. הצהר במפורש שהשירות שלך פרטי ואינו משויך, מאושר או קשור למשרד התחבורה או לגוף ממשלתי. שימוש בנתונים פתוחים אינו הסמכה ואינו חסות.
• ללא הבטחות עודפות. אל תצהיר על דיוק, שלמות או עדכניות שאין לך שליטה עליהם, ואל תרמוז שהשירות מחליף בדיקה מקצועית. הצג את הנתון כפי שהוא, עם המגבלות שלו.