<!-- https://api.ibusisrael.online/docs/he/quickstart/ -->
# בקשה ראשונה

שלושה צעדים, משם התחנה ועד כלי הרכב שבדרך אליה. ל-curl לא צריך להתקין דבר; ל-JavaScript נדרש Node.js 18 ומעלה, ול-Python מספיקה הספרייה הסטנדרטית.

## 0. לקבל מפתח

אחרי שה[בקשה](/he/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/he/data/): ימי שירות, זמנים אחרי חצות, מזהים.
- [מגבלות ושגיאות](/docs/he/limits/): מה לעשות עם `429` ו-`5xx`.
- [מדריך ה-API](/docs/he/reference/): כל הפעולות עם דוגמאות.