<!-- https://api.ibusisrael.online/docs/he/data/ -->
# נתונים וזמן

## מקורות

| נתונים | מקור | באיזו תדירות iBus מעדכן |
|---|---|---|
| לוח זמנים: תחנות, מסלולים, נסיעות, לוח שנה | משרד התחבורה, GTFS | בכל לילה, בסביבות 04:00 שעון ישראל; `getStopsVersion` משתנה כשמתפרסם לוח זמנים חדש |
| זמן אמת: כלי רכב בדרך לתחנות | משרד התחבורה, SIRI | המקור נשאל כל כמה שניות; כלי רכב מדווח בערך כל 20 עד 60 שניות |
| הודעות על שינויים בתנועה | משרד התחבורה | בערך כל 5 דקות |

iBus מעבד את הנתונים (התאמה, עדכניות, שמות בשלוש שפות). זה אינו שירות רשמי של המשרד.

## לוח זמנים וזמן אמת הם תשובות שונות

- פעולות **לוח הזמנים** (`getStopDaySchedule`, `getLineDaySchedule`) עונות מה מתוכנן ליום שירות. הן לא יודעות על עיכובים.
- **זמן אמת** (`getStopArrivals`) עונה מה כלי הרכב מדווחים עכשיו, שורה אחר שורה, עם `freshness`.
- שורת זמן אמת שהתצפית שלה ישנה מוצגת עם זמן לפי לוח הזמנים רק אם לוח הזמנים מאשר שהנסיעה הזאת עוצרת בתחנה הזאת ביום השירות הזה (`scheduled_confirmed`). אחרת היא נשארת `stale_observation`.

## כללי עדכניות

הספים מגיעים מ-`getFreshnessContract` (גרסה 1):

| כלל | ערך |
|---|---|
| תצפית של כלי רכב היא **חיה** | לא ישנה מ-120 שניות |
| זמן הגעה לפי תצפית ישנה לא מוצג כשעה | ישנה מ-1,800 שניות (`eta_hidden`) |
| הודעות נחשבות מעוכבות | ישנות מ-900 שניות |
| לא סומכים על תצפית שתאריכה בעתיד | יותר מ-300 שניות קדימה |

הגיל מחושב לפי שעון השרת (`server_now_utc` בתשובה), ולא לפי זמן הבקשה שלכם.

## יום שירות וזמנים אחרי חצות

**יום שירות** (`date=YYYYMMDD`) הוא יום הפעילות שאליו שייכת הנסיעה. הזמנים בלוח הזמנים הם מחרוזות GTFS בתבנית `HH:MM:SS` לפי שעון ישראל של יום השירות, והם יכולים להיות **24:00:00 ואילך**: `25:04:48` ביום השירות 2026-10-21 הוא 01:04:48 ב-22 באוקטובר, והנסיעה עדיין שייכת ל-21 באוקטובר.

- מיינו את שורות לוח הזמנים לפי המחרוזת כפי שהיא: `24:10:00` בא אחרי `23:50:00`.
- כדי לקבל שעה בלוח השנה, העבירו את השעות שמעבר ל-24 ליום הבא.
- בלי `date` נלקח יום השירות של היום בישראל. תאריך בתבנית אחרת מחזיר רשימה ריקה, לא שגיאה.
- לוח הזמנים שפורסם מכסה בערך חודש קדימה. `getServiceDay` מראה אם תאריך נמצא בתוכו (`feed.from`, `feed.to`) ואם הוא שונה מיום רגיל באותו יום בשבוע (חגים).

> [!WARNING]
> מעבר שעון. המשרד רושם את הזמנים בלוח הזמנים לפי השעון גם בלילות מעבר השעון (נבדק ב-19.10.2026 על 1,534 מתוך 1,559 נסיעות לילה של 25.10.2026). זמני UTC ש-iBus מחשב מלוח הזמנים (`gtfs_scheduled_*_utc`, `freshness.scheduled_arrival_utc`, `first_departure_utc`) עדיין מחושבים לפי כלל GTFS «צהריים פחות 12 שעות»: לנסיעות לפני 02:00 ביום המעבר (25.10.2026, 26.03.2027) הם עשויים להיות שונים בשעה. בלילות כאלה הסתמכו על שורות חיות.

## שדות זמן

- שדות שמסתיימים ב-`_utc` הם UTC בתבנית ISO 8601 עם `Z`, למשל `2026-10-21T14:17:00Z`.
- `updatedAt` במעטפת ההגעות הוא שעון ישראל עם ההפרש מ-UTC, למשל `2026-10-21T17:16:22+03:00`.
- `dateRanges` של הודעות כוללים גם שניות Unix (`start`, `end`) וגם מחרוזות UTC.

## מזהים

| שדה | מה זה |
|---|---|
| `stop_code` | הקוד הציבורי של התחנה, המספר שעל השלט. משתמשים בו בנתיבים. |
| `stop_id` | המזהה הפנימי של GTFS. לא הקוד הציבורי. |
| `route_id` (`line_ref` בזמן אמת) | כיוון או חלופה אחת של קו. מוצאים אותו עם `searchLines`. |
| `route_short_name` | מספר הקו הציבורי. לא ייחודי: קו 1 קיים בערים רבות. |
| `agency_id` | המפעיל. השמות ב-`listAgencies`. |
| `makat` | מזהה הקו של המשרד, משותף לכיווני הקו. |
| `dated_vehicle_journey_ref` | מזהה הנסיעה אצל המקור. אינו `trip_id` של GTFS. |
| `gtfs_trip_id` | נסיעת GTFS, רק כשנמצאה התאמה אחת בדיוק. |
| `vehicle_ref` | כינוי יומי של כלי רכב. משתנה בכל יום UTC ולעולם אינו מספר הרישוי. |
| `direction_ref` | הכיוון אצל המקור (1 או 2). אינו `direction_id` של GTFS (0 או 1). |

## קואורדינטות ויחידות

- הקואורדינטות ב-WGS 84 במעלות עשרוניות. `coords` של תוואי מסלול הם זוגות `[lon, lat]` (בסדר של GeoJSON); `shape` חוזר על הנקודות כ-`{lat, lon}`.
- מרחקים במטרים (`dist_m`, `distance_from_stop_m`), מהירות בקמ״ש (`velocity`), כיוון במעלות מהצפון (`bearing`).
- גיל בשניות (`age_sec`), זמן המתנה בדקות שלמות (`expected_in_min`), תעריפים בשקלים (`tariff`).

## שפות השמות

הפרמטר `lang` בוחר את שפת שמות התחנות והיעדים: `en` (וגם `ru`) נותנים את השמות באנגלית מלוח הזמנים של המשרד, `ar` נותן ערבית, וכל ערך אחר נותן את העברית של המקור. במקור אין שמות ברוסית. השדות `names` ו-`dest_names` כוללים עברית, אנגלית וערבית יחד. את טקסטי ההודעות מפרסם המשרד, לרוב בעברית.

## שמירה במטמון

כל תשובה מציינת ב-`Cache-Control` כמה זמן מותר לשמור אותה: זמן אמת ולוחות זמנים הם `no-store`, נתונים כלליים `public` לזמן של 60 שניות עד שעה. עם `Accept-Encoding: gzip` התשובות נדחסות: לוח הזמנים היומי של תחנה עמוסה הוא כ-580 KB של JSON וכ-27 KB דחוס.