<!-- https://api.ibusisrael.online/docs/ru/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` в конверте прибытий - местное время Израиля со смещением, например `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 КБ JSON и около 27 КБ в сжатом виде.