auto-sync: 2026-04-24 17:50:01

tasks/flightradar24/docs/FR24_API_NOTES.md

@@ -0,0 +1,108 @@
+# 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` обязательна — один рейс может попасть
+> в два смежных временных окна.

tasks/flightradar24/docs/INDEX.md

@@ -5,6 +5,9 @@
 ## 🔑 Главный документ
 - **`SYSTEM_OVERVIEW.md`** — полное актуальное описание системы: контейнеры, БД, ETL, UI, статус данных
 
+## API
+- **`FR24_API_NOTES.md`** — особенности FR24 API Explorer: лимиты, пагинация через временны́е окна, правильные prefixes, стоимость
+
 ## Основные документы
 - `tasks/flightradar24/PROJECT.md` — общий статус и границы проекта
 - `tasks/flightradar24/docs/ARCHITECTURE.md` — контейнерная архитектура (базовая, устарела частично)