<!-- https://api.ibusisrael.online/docs/ar/quickstart/ -->
# الطلب الأول

ثلاث خطوات من اسم المحطة إلى المركبات المتجهة إليها. لا تحتاج إلى تثبيت شيء لـ curl؛ تحتاج JavaScript إلى Node.js 18 أو أحدث، وتكفي Python مكتبتها القياسية.

## 0. احصل على مفتاح

بعد قبول [طلبك](/ar/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/ar/data/): أيام الخدمة، والأوقات بعد منتصف الليل، والمعرّفات.
- [الحدود والأخطاء](/docs/ar/limits/): ماذا تفعل مع `429` و`5xx`.
- [مرجع الواجهة](/docs/ar/reference/): كل العمليات مع أمثلة.