# Data and time ## Sources | Data | Source | How often iBus refreshes it | |---|---|---| | Timetable: stops, routes, trips, calendar | Ministry of Transport, GTFS | Nightly, around 04:00 Israel time; `getStopsVersion` changes when a new timetable is published | | Realtime: vehicles approaching stops | Ministry of Transport, SIRI | The source is asked every few seconds; a vehicle reports roughly every 20–60 seconds | | Service alerts | Ministry of Transport | About every 5 minutes | iBus processes the data (matching, freshness, names in three languages). It is not an official service of the Ministry. ## Timetable and realtime are different answers - **Timetable** operations (`getStopDaySchedule`, `getLineDaySchedule`) answer what is planned for a service date. They do not know about delays. - **Realtime** (`getStopArrivals`) answers what the vehicles report now, row by row, with `freshness`. - A realtime row whose observation is old is shown with the timetable time only when the timetable confirms that this trip calls at this stop on this service day (`scheduled_confirmed`). Otherwise it stays `stale_observation`. ## Freshness rules The thresholds come from `getFreshnessContract` (version 1): | Rule | Value | |---|---| | A vehicle observation is **live** | not older than 120 seconds | | An old observation's ETA must not be shown as a time | older than 1,800 seconds (`eta_hidden`) | | Alerts are considered delayed | older than 900 seconds | | An observation dated in the future is not trusted | more than 300 seconds ahead | Ages are computed on the server clock (`server_now_utc` in the answer), never by the age of your request. ## Service date and times after midnight A **service date** (`date=YYYYMMDD`) is the operating day a trip belongs to. Timetable times are GTFS strings `HH:MM:SS` on the Israel clock of that service date, and they can be **24:00:00 or later**: `25:04:48` on service date 2026-10-21 is 01:04:48 on 22 October, and the trip still belongs to 21 October. - Sort timetable rows by the string as given: `24:10:00` comes after `23:50:00`. - To get a calendar time, add the hours beyond 24 to the next day. - Without `date`, today's service date in Israel is used. A date in another format returns an empty list, not an error. - The published timetable covers about a month ahead. `getServiceDay` tells whether a date is inside it (`feed.from`, `feed.to`) and whether it differs from a usual same weekday (holidays). > [!WARNING] > Clock changes. The Ministry writes timetable times on the wall clock also on the nights when clocks change (checked on 19.10.2026 on 1,534 of 1,559 night trips of 25.10.2026). UTC times that iBus computes from the timetable (`gtfs_scheduled_*_utc`, `freshness.scheduled_arrival_utc`, `first_departure_utc`) still use the GTFS rule «noon minus 12 hours»: for trips before 02:00 on the day of a change (25.10.2026, 26.03.2027) they can differ by one hour. Prefer live rows on those nights. ## Time fields - Fields ending in `_utc` are UTC in ISO 8601 with `Z`, for example `2026-10-21T14:17:00Z`. - `updatedAt` of the arrivals envelope is Israel local time with its offset, for example `2026-10-21T17:16:22+03:00`. - Alert `dateRanges` carry both Unix seconds (`start`, `end`) and UTC strings. ## Identifiers | Field | What it is | |---|---| | `stop_code` | The public stop code, the number on the stop sign. Use it in paths. | | `stop_id` | The internal GTFS id of a stop. Not the public code. | | `route_id` (`line_ref` in realtime) | One direction or variant of a line. Find it with `searchLines`. | | `route_short_name` | The public line number. Not unique: many cities have a line 1. | | `agency_id` | The operator. Names come from `listAgencies`. | | `makat` | The Ministry's line id shared by the directions of one line. | | `dated_vehicle_journey_ref` | The source's journey id. It is not a GTFS `trip_id`. | | `gtfs_trip_id` | The GTFS trip, present only when exactly one trip matches. | | `vehicle_ref` | A daily pseudonym of a vehicle. It changes every UTC day and is never the licence plate. | | `direction_ref` | The source's direction (1 or 2). It is not the GTFS `direction_id` (0 or 1). | ## Coordinates and units - Coordinates are WGS 84 decimal degrees. `coords` of a route shape are `[lon, lat]` pairs (GeoJSON order); `shape` repeats the points as `{lat, lon}`. - Distances in metres (`dist_m`, `distance_from_stop_m`), speed in km/h (`velocity`), direction in degrees from north (`bearing`). - Ages in seconds (`age_sec`), waiting time in whole minutes (`expected_in_min`), fares in ILS (`tariff`). ## Languages of names The `lang` parameter selects the language of stop names and headsigns: `en` (and `ru`) give the English names of the Ministry's timetable, `ar` gives Arabic, anything else gives the source Hebrew. The source has no Russian names. Fields `names` and `dest_names` carry Hebrew, English and Arabic at once. Alert texts are published by the Ministry, usually in Hebrew. ## Caching Each answer says how long it may be kept in `Cache-Control`: realtime and timetable answers are `no-store`, reference data `public` for 60 seconds to an hour. Answers are compressed with gzip when you send `Accept-Encoding: gzip`; a busy stop's day timetable is about 580 KB as JSON and about 27 KB compressed.