<!-- https://api.ibusisrael.online/docs/ru/quickstart/ -->
# Первый запрос

Три шага - от названия остановки до транспорта, который к ней едет. Для curl ничего ставить не нужно; для JavaScript нужен Node.js 18 или новее, для Python хватает стандартной библиотеки.

## 0. Получить ключ

После одобрения [заявки](/ru/access/) создайте ключ в [кабинете разработчика](https://app.ibusisrael.online/developers). Он показывается один раз. Храните его на сервере, например в переменной окружения:

```bash
export IBUS_API_KEY='ibk_live_k_…'
```

Все примеры ниже передают его в заголовке `Authorization`. Никогда не помещайте ключ в адрес запроса, на веб-страницу или в пакет приложения.

## 1. Найти остановку

Ищите по названию на иврите, английском или арабском либо по коду с таблички остановки.

**curl**

```bash
curl -H "Authorization: Bearer $IBUS_API_KEY" "https://api.ibusisrael.online/api/transport/stops/search?q=Azrieli&limit=3&lang=en"
```

**JavaScript**

```js
const base = "https://api.ibusisrael.online/api/transport";
const res = await fetch(`${base}/stops/search?q=Azrieli&limit=3&lang=en`, { headers: { Authorization: `Bearer ${process.env.IBUS_API_KEY}` } });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(await res.json());
```

**Python**

```python
import json, os, urllib.request

url = "https://api.ibusisrael.online/api/transport/stops/search?q=Azrieli&limit=3&lang=en"
req = urllib.request.Request(url, headers={"Authorization": "Bearer " + os.environ["IBUS_API_KEY"]})
with urllib.request.urlopen(req, timeout=15) as r:
    print(json.load(r))
```

```json
[
  {"stop_code": "34219", "stop_name": "Azrieli Mall", "stop_lat": 31.899117, "stop_lon": 35.007414},
  {"stop_code": "21472", "stop_name": "Azrieli Mall/Menahem Begin Road", "stop_lat": 32.074584, "stop_lon": 34.790607}
]
```

`stop_code` - публичный код. У нескольких остановок может быть одно название: сверьтесь с координатами или ищите по коду.

## 2. Запросить прибытия

**curl**

```bash
curl -H "Authorization: Bearer $IBUS_API_KEY" "https://api.ibusisrael.online/api/transport/v2/stop/21472/arrivals?limit=5&lang=en"
```

**JavaScript**

```js
const base = "https://api.ibusisrael.online/api/transport";
const res = await fetch(`${base}/v2/stop/21472/arrivals?limit=5&lang=en`, { headers: { Authorization: `Bearer ${process.env.IBUS_API_KEY}` } });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
for (const a of data.arrivals) {
  const when = a.freshness.state === "live" ? `${a.expected_in_min} min` : a.freshness.state;
  console.log(a.route_short_name, a.dest_names?.en ?? a.destination_name, when);
}
```

**Python**

```python
import json, os, urllib.request

url = "https://api.ibusisrael.online/api/transport/v2/stop/21472/arrivals?limit=5&lang=en"
req = urllib.request.Request(url, headers={"Authorization": "Bearer " + os.environ["IBUS_API_KEY"]})
with urllib.request.urlopen(req, timeout=15) as r:
    data = json.load(r)
for a in data["arrivals"]:
    state = a["freshness"]["state"]
    when = f'{a["expected_in_min"]} min' if state == "live" else state
    print(a["route_short_name"], a.get("dest_names", {}).get("en"), when)
```

## 3. Прочитать свежесть каждой строки

| `freshness.state` | Как показывать |
|---|---|
| `live` | Прогноз в реальном времени: `expected_in_min`, `expected_arrival_utc`. |
| `scheduled_confirmed` | Время по расписанию: `freshness.scheduled_arrival_utc`. Сообщение самой машины устарело, расписание подтверждает рейс. |
| `stale_observation` | Машину видели `age_sec` секунд назад; это не живой прогноз. Если `eta_hidden` = true, время не показывайте совсем. |
| `unknown_age` | Источник не дал пригодного времени; не выдавайте строку за живую. |

Поле конверта `source_state` говорит, ответил ли источник: `ok`, `no_data` (ответил, но пусто) или `unavailable`.

> [!NOTE]
> Ключи - для серверов. Веб-страница или мобильное приложение обращается к вашему серверу, а сервер - к iBus с ключом; кросс-доменные запросы из браузера разрешены только приложению iBus.

## Дальше

- [Данные и время](/docs/ru/data/): служебные даты, время после полуночи, идентификаторы.
- [Ограничения и ошибки](/docs/ru/limits/): что делать с `429` и `5xx`.
- [Справочник API](/docs/ru/reference/): все операции с примерами.