# FR24 API — Особенности и ограничения

Исследовано: 2026-04-24. Тариф: **Explorer**.

---

## Endpoint: `/api/flight-summary/full`

### Explorer tier — жёсткий лимит 20 результатов на запрос

Независимо от значения параметра `limit` (даже `limit=20000`) — Explorer всегда возвращает
**максимум 20 записей** за один запрос. Это hard limit тарифа, не баг.

### Параметр `offset` не существует

В документации FR24 API нет параметра `offset`. Если его передать — он молча игнорируется,
и каждый запрос возвращает одни и те же первые 20 рейсов.

❌ **Неправильно** (так мы сожгли все кредиты первый раз):
```
?airports=both:SVO&limit=20&offset=0   → 20 рейсов
?airports=both:SVO&limit=20&offset=20  → те же 20 рейсов (offset игнорируется)
?airports=both:SVO&limit=20&offset=40  → те же 20 рейсов
```

### Правильная пагинация — временны́е окна

Данные отсортированы по `first_seen`. Для получения всех рейсов за сутки нужно
разбить день на часовые окна:

✅ **Правильно**:
```
?airports=inbound:SVO&flight_datetime_from=2026-04-23T00:00:00&flight_datetime_to=2026-04-23T01:00:00
?airports=inbound:SVO&flight_datetime_from=2026-04-23T01:00:00&flight_datetime_to=2026-04-23T02:00:00
...и т.д.
```

Если в окне >20 рейсов — нужно уменьшать окно (30 мин) или разделять на `inbound:` + `outbound:`.

---

## Параметр `airports` — правильные prefixes

| Prefix | Значение | Работает |
|--------|----------|---------|
| `both:SVO` | прилёты + вылеты SVO | ✅ |
| `inbound:SVO` | только прилёты | ✅ |
| `outbound:SVO` | только вылеты | ✅ |
| `departure:SVO` | — | ❌ не существует |
| `arrival:SVO` | — | ❌ не существует |

Принимает IATA (`SVO`), ICAO (`UUEE`) и ISO коды стран (`RU`). До 15 аэропортов через запятую.

---

## Стоимость

| Endpoint | Данные | Кредитов/запись |
|----------|--------|-----------------|
| `/flight-summary/light` | Live | 1 |
| `/flight-summary/light` | История < 30 дней | 2 |
| `/flight-summary/light` | История > 30 дней | 3 |
| `/flight-summary/full` | Live | 2 |
| `/flight-summary/full` | История < 30 дней | **3** |
| `/flight-summary/full` | История > 30 дней | **6** |
| `/flight-tracks` | любые | 40 |

Стоимость считается за каждую **возвращённую** запись, не за запрос.

---

## Поля ответа `/full`

Все поля `light` плюс:
- `orig_iata` / `dest_iata` / `dest_iata_actual`
- `orig_icao` / `dest_icao` / `dest_icao_actual`
- `flight_time` (секунды)
- `runway_takeoff` / `runway_landed`
- `circle_distance` / `actual_distance` (км)
- `category` (Passenger, Cargo, ...)

Поля могут быть `null` если рейс ещё в воздухе или данные не обнаружены.

---

## Оценка объёма SVO (23.04.2026)

| Окно | `inbound:SVO` | `outbound:SVO` | `both:SVO` |
|------|---------------|----------------|------------|
| 00:00–01:00 | 17 рейсов | 2 рейса | 19 рейсов |

Типичный день SVO: ~400 рейсов (прилёты + вылеты).

---

## Рекомендуемая стратегия загрузки

```
Для 4 аэропортов (SVO, DME, VKO, ZIA) за 1 день:
  24 окна × inbound: × 4 аэропорта  = 96 запросов
  24 окна × outbound: × 4 аэропорта = 96 запросов
  Итого: 192 запроса × ~10 рейсов × 3 кредита ≈ 5 760 кредитов/день
  
При остатке 51 000 кредитов: ~9 дней данных
```

> **Важно**: дедупликация по `fr24_id` обязательна — один рейс может попасть
> в два смежных временных окна.