# Flightradar24 API — Справочник

## Доступ

- **Документация:** https://fr24api.flightradar24.com/docs
- **Base URL:** `https://fr24api.flightradar24.com/api`
- **Тариф:** Explorer
- **Лимит:** 60 000 кредитов/месяц (промо 120 000 до 31.05.2026)
- **Ключи:** в файле `.env` (sandbox и production)

### Заголовки запросов

```python
headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Accept': 'application/json',
    'Accept-Version': 'v1',
}
```

---

## Используемые endpoints

### 1. `/historic/flight-positions/light`

Позиции самолётов в исторический момент времени (лёгкая версия).

```
GET /historic/flight-positions/light
    ?bounds=57.0,54.0,35.5,40.5
    &timestamp=1742558400
    &limit=500
```

**⚠️ ВАЖНО — формат bounds:** `lat_max,lat_min,lon_min,lon_max`
(НЕ lat_min,lon_min,lat_max,lon_max!)

Поля ответа: `fr24_id, hex, callsign, lat, lon, track, alt, gspeed, vspeed, squawk, timestamp, source`

Стоимость: **1 кредит = 1 позиция**

---

### 2. `/historic/flight-positions/full`

То же + дополнительные поля рейса.

```
GET /historic/flight-positions/full
    ?bounds=57.0,54.0,35.5,40.5
    &timestamp=1742558400
    &limit=500
```

Дополнительные поля: `flight, type, reg, painted_as, operating_as, orig_iata, orig_icao, dest_iata, dest_icao, eta`

Стоимость: **1 кредит = 1 позиция**

Используется для фильтрации по аэропорту через `orig_icao`/`dest_icao`.

---

### 3. `/flight-tracks`

Полный трек рейса по fr24_id.

```
GET /flight-tracks?flight_id=3ed756a5
```

Ответ: массив `[{ fr24_id, tracks: [{timestamp, lat, lon, alt, gspeed, vspeed, track, squawk, callsign, source}] }]`

**Важные характеристики:**
- Интервал между точками: **~10 секунд**
- Типичная длина трека: **600–900 точек** (полный маршрут)
- Параметры `from`/`to` для временного фильтра **не поддерживаются** — всегда весь трек
- Стоимость: **~74 кредита** за запрос (пропорционально кол-ву точек)

---

### 4. `/live/flight-positions/light`

Текущие позиции самолётов.

```
GET /live/flight-positions/light?bounds=57.0,54.0,35.5,40.5&limit=100
```

Стоимость: **1 кредит = 1 позиция**

---

### 5. `/live/flight-positions/full`

То же + поля рейса. Используется для поиска fr24_id по callsign.

---

### 6. `/usage`

Отчёт об использовании кредитов.

```
GET /usage
```

Ответ: `{ data: [{ endpoint, request_count, results, credits }] }`

---

## Rate Limiting

- **429** — слишком много запросов
- Рекомендуемая пауза при 429: **30 секунд**
- Рекомендуемая пауза между обычными запросами: **1–1.2 секунды**

Все скрипты загрузки обрабатывают 429 автоматически.

---

## ICAO коды аэропортов МО

| Аэропорт | ICAO | IATA |
|----------|------|------|
| Шереметьево | UUEE | SVO |
| Домодедово | UUDD | DME |
| Внуково | UUWW | VKO |
| Жуковский | UUBW | ZIA |

---

## Расход кредитов (накопленный, на 22.03.2026)

| Endpoint | Кредитов | Запросов | Назначение |
|----------|----------|----------|------------|
| `historic/.../light` | 1 717 | 18 | Ранние тесты (неверный bounds) |
| `historic/.../full` | 5 564 | ~32 | Снимки за 20–21.03 |
| `flight-tracks` | 8 880 | ~120 | Треки рейсов |
| **Итого** | **~16 161** | | **13.5% промо-лимита** |
| **Остаток** | **~103 839** | | |

---

## Структура файлов кэша

```
data/
├── cache_SVO/track_{fr24_id}.json    # кэш треков SVO
├── cache_DME/track_{fr24_id}.json    # кэш треков DME
├── cache_VKO/track_{fr24_id}.json    # кэш треков VKO
├── cache_ZIA/track_{fr24_id}.json    # кэш треков ZIA
├── raw_SVO_2026-03-21.json           # сырые снимки (до загрузки треков)
└── raw_SVO_2026-03-20.json           # и т.д.
```

Кэш треков не имеет срока истечения — треки исторических рейсов не меняются.
Повторная загрузка одного и того же fr24_id не тратит кредиты.
