# Поиск в истории полётов

Поиск архивных полётов ADS-B по бортовому номеру, ICAO24 hex, позывному или маршруту — возвращает UUID flight_id для запросов деталей и трека.



Ищите архивные полёты по бортовому номеру, **позывному** (позывной рейса, транслируемый по [ADS-B](https://www.faa.gov/air_traffic/technology/adsb), например `BAW178`), маршруту или hex-коду и получайте список полётов с UUID `flight_id`. Требуется хотя бы один фильтр. Это обязательный первый шаг в любом сценарии работы с историческими данными [ADS-B](https://www.faa.gov/air_traffic/technology/adsb): без `flight_id`, полученного из поиска, эндпоинты [деталей](/docs/v31/historical-adsb-flight-detail#flight-detail) и [трека](/docs/v31/historical-adsb-flight-detail#flight-track) вызвать невозможно.

Уровни тарифов и правила префиксов пути: [раздел «Исторические данные ADS-B»](/docs/v31/historical-adsb).

<DocRequirements>
  <DocRequirementAuth />

  <DocRequirement label="Тариф" href="/docs/rate-limits#historical-adsb-path-tiers">
    <strong>Pro</strong>, <strong>Ultra</strong> или <strong>Mega</strong> — используйте префикс пути, соответствующий нужному вам временному окну (см. [сравнительную таблицу в обзорном разделе](/docs/v31/historical-adsb)).
  </DocRequirement>
</DocRequirements>

## Запрос [#request]

<DocApiPath method="GET" path="/ultra/history/flights" />

| Параметр         | Тип     | Обязательный              | По умолчанию | Описание                                                                                   |
| ---------------- | ------- | ------------------------- | ------------ | ------------------------------------------------------------------------------------------ |
| `start`          | string  | Нет                       | 24 ч назад   | Начало окна запроса — дата и время в ISO 8601                                              |
| `end`            | string  | Нет                       | сейчас       | Конец окна запроса — дата и время в ISO 8601                                               |
| `icao24`         | string  | Нужен хотя бы один фильтр | -            | Hex-адрес ICAO24 (6 символов)                                                              |
| `registration`   | string  | Нужен хотя бы один фильтр | -            | Бортовой номер (например, `N12345`, `G-XWBA`). Преобразуется в `icao24` на стороне сервера |
| `callsign`       | string  | Нужен хотя бы один фильтр | -            | Точное совпадение позывного (например, `BAW117`)                                           |
| `departure_icao` | string  | Нужен хотя бы один фильтр | -            | ICAO аэропорта вылета (4 символа)                                                          |
| `arrival_icao`   | string  | Нужен хотя бы один фильтр | -            | ICAO аэропорта прилёта (4 символа)                                                         |
| `limit`          | integer | Нет                       | `100`        | Максимальное число возвращаемых полётов (не более **1000** на пути ULTRA)                  |

Если переданы и `registration`, и `icao24`, они должны относиться к одному и тому же воздушному судну. На пути ULTRA окно запроса не может превышать **90 дней**.

<DocDetails title="Путь MEGA (`/mega/history/...`)">
  <DocApiPath method="GET" path="/mega/history/flights" />

  | Параметр         | Тип     | Обязательный              | По умолчанию | Описание                                                          |
  | ---------------- | ------- | ------------------------- | ------------ | ----------------------------------------------------------------- |
  | `start`          | string  | Нет                       | 24 ч назад   | Начало окна — ISO 8601 (на пути MEGA охват не более **365 дней**) |
  | `end`            | string  | Нет                       | сейчас       | Конец окна — ISO 8601                                             |
  | `icao24`         | string  | Нужен хотя бы один фильтр | -            | ICAO24 hex (6 символов)                                           |
  | `registration`   | string  | Нужен хотя бы один фильтр | -            | Бортовой номер                                                    |
  | `callsign`       | string  | Нужен хотя бы один фильтр | -            | Точный позывной                                                   |
  | `departure_icao` | string  | Нужен хотя бы один фильтр | -            | ICAO аэропорта вылета                                             |
  | `arrival_icao`   | string  | Нужен хотя бы один фильтр | -            | ICAO аэропорта прилёта                                            |
  | `limit`          | integer | Нет                       | `200`        | Максимальное число полётов (не более **2000** на пути MEGA)       |

  Требуется тариф RapidAPI **Ultra** или **Mega**. Параметры и формат ответа такие же, как у ULTRA, — различаются только ограничения окна и лимита. См. [сравнительную таблицу в обзорном разделе](/docs/v31/historical-adsb).
</DocDetails>

## Ответ [#response]

```json
{
  "filters": {
    "icao24": null,
    "registration": null,
    "resolved_icao24": null,
    "callsign": null,
    "departure_icao": "EGLL",
    "arrival_icao": null
  },
  "count": 1,
  "flights": [
    {
      "flight_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "icao24": "40621d",
      "callsign": "BAW178",
      "flight_number": "BAW178",
      "tail_number": "G-XWBA",
      "aircraft_type_icao": "B77W",
      "aircraft_type_name": "Boeing 777-300ER",
      "airline_icao": "BAW",
      "airline_iata": "BA",
      "airline_name": "British Airways",
      "departure_airport_icao": "EGLL",
      "departure_airport_iata": "LHR",
      "departure_airport_name": "London Heathrow Airport",
      "arrival_airport_icao": "KJFK",
      "arrival_airport_iata": "JFK",
      "arrival_airport_name": "John F Kennedy International Airport",
      "flight_state": "ARCHIVED",
      "flight_start": "2026-05-12T19:42:05Z",
      "flight_end": "2026-05-13T03:11:10Z",
      "takeoff_time": "2026-05-12T19:45:00Z",
      "landing_time": "2026-05-13T03:08:00Z",
      "flight_duration_min": 443.0,
      "distance_nm": 2998.4,
      "confidence": 1.0,
      "route_source": "vrs_confirmed",
      "gps_spoofing_suspected": false,
      "diversion_suspected": false
    }
  ]
}
```

| Поле      | Тип     | Обязательный | Описание                                      |
| --------- | ------- | ------------ | --------------------------------------------- |
| `filters` | object  | **Да**       | Повтор применённых фильтров поиска (см. ниже) |
| `count`   | integer | **Да**       | Количество элементов в `flights`              |
| `flights` | array   | **Да**       | Сводки подходящих полётов (может быть пустым) |

### Применённые фильтры (`filters`) [#applied-filters-filters]

| Поле              | Тип            | Обязательный | Может быть null? | Описание                                                |
| ----------------- | -------------- | ------------ | ---------------- | ------------------------------------------------------- |
| `icao24`          | string \| null | **Да**       | **Да**           | Запрошенный ICAO24 hex, если указан                     |
| `registration`    | string \| null | **Да**       | **Да**           | Запрошенный бортовой номер, если указан                 |
| `resolved_icao24` | string \| null | **Да**       | **Да**           | ICAO24, определённый по `registration`, если он передан |
| `callsign`        | string \| null | **Да**       | **Да**           | Запрошенный позывной, если указан                       |
| `departure_icao`  | string \| null | **Да**       | **Да**           | Запрошенный аэропорт вылета, если указан                |
| `arrival_icao`    | string \| null | **Да**       | **Да**           | Запрошенный аэропорт прилёта, если указан               |

<a id="flight-summary-flights" />

### Сводка полёта (`flights[]`) [#flight-summary-flights]

| Поле                     | Тип             | Обязательный | Может быть null? | Описание                                                                                                                             |
| ------------------------ | --------------- | ------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `flight_id`              | string          | **Да**       | Никогда          | UUID для запросов деталей и трека                                                                                                    |
| `icao24`                 | string \| null  | Нет          | **Да**           | Hex-адрес воздушного судна, если известен                                                                                            |
| `callsign`               | string \| null  | Нет          | **Да**           | Позывной ADS-B во время полёта                                                                                                       |
| `flight_number`          | string \| null  | Нет          | **Да**           | Нормализованный номер рейса, если определён                                                                                          |
| `tail_number`            | string \| null  | Нет          | **Да**           | Бортовой номер, если известен                                                                                                        |
| `aircraft_type_icao`     | string \| null  | Нет          | **Да**           | Код типа ВС по ICAO (например, `B77W`)                                                                                               |
| `aircraft_type_name`     | string \| null  | Нет          | **Да**           | Тип ВС в удобочитаемом виде                                                                                                          |
| `airline_icao`           | string \| null  | Нет          | **Да**           | Код авиакомпании ICAO                                                                                                                |
| `airline_iata`           | string \| null  | Нет          | **Да**           | Код авиакомпании IATA                                                                                                                |
| `airline_name`           | string \| null  | Нет          | **Да**           | Отображаемое название авиакомпании                                                                                                   |
| `departure_airport_icao` | string \| null  | Нет          | **Да**           | ICAO аэропорта вылета, если определён                                                                                                |
| `departure_airport_iata` | string \| null  | Нет          | **Да**           | IATA аэропорта вылета                                                                                                                |
| `departure_airport_name` | string \| null  | Нет          | **Да**           | Название аэропорта вылета                                                                                                            |
| `arrival_airport_icao`   | string \| null  | Нет          | **Да**           | ICAO аэропорта прилёта, если определён                                                                                               |
| `arrival_airport_iata`   | string \| null  | Нет          | **Да**           | IATA аэропорта прилёта                                                                                                               |
| `arrival_airport_name`   | string \| null  | Нет          | **Да**           | Название аэропорта прилёта                                                                                                           |
| `flight_state`           | string \| null  | Нет          | **Да**           | Состояние в архиве (например, `ARCHIVED`)                                                                                            |
| `flight_start`           | string          | **Да**       | Никогда          | Первое наблюдение в архиве (ISO 8601)                                                                                                |
| `flight_end`             | string          | **Да**       | Никогда          | Последнее наблюдение в архиве (ISO 8601)                                                                                             |
| `takeoff_time`           | string \| null  | Нет          | **Да**           | Расчётное или зафиксированное время взлёта (ISO 8601)                                                                                |
| `landing_time`           | string \| null  | Нет          | **Да**           | Расчётное или зафиксированное время посадки (ISO 8601)                                                                               |
| `flight_duration_min`    | number \| null  | Нет          | **Да**           | Продолжительность от выхода до выхода (gate-to-gate) в минутах                                                                       |
| `distance_nm`            | number \| null  | Нет          | **Да**           | Расстояние по ортодромии в морских милях                                                                                             |
| `confidence`             | number \| null  | Нет          | **Да**           | Оценка достоверности маршрута (0–1)                                                                                                  |
| `route_source`           | string \| null  | Нет          | **Да**           | Непрозрачный enum, описывающий способ определения маршрута, — используйте как отображаемое значение, а не как ключ для сопоставления |
| `gps_spoofing_suspected` | boolean \| null | Нет          | **Да**           | Был ли для этого полёта отмечен подмен сигнала GPS (спуфинг)                                                                         |
| `diversion_suspected`    | boolean \| null | Нет          | **Да**           | Было ли для этого полёта отмечено отклонение от маршрута                                                                             |

## Клиентские типы [#client-types]

<DocClientTypes id="v31/historical-adsb/history-types" />

## Интеграция [#integration]

Типичный сценарий — **поиск → детали** (метаданные) или **поиск → трек** (воспроизведение на карте). Выполните поиск хотя бы с одним фильтром, возьмите `flight_id` из результатов, затем вызовите [детали](/docs/v31/historical-adsb-flight-detail#flight-detail) или [трек](/docs/v31/historical-adsb-flight-detail#flight-track).

Пример ниже выполняет поиск по аэропорту вылета, получает полные метаданные для первого совпадения и использует таймауты подключения и чтения, чтобы пакетные задания не могли зависнуть на неопределённое время. На тарифах без доступа к историческим данным [ADS-B](https://www.faa.gov/air_traffic/technology/adsb) обрабатывайте `401`/`403` от шлюза до разбора JSON — см. [обзорный раздел → Ответы с ошибками](/docs/v31/historical-adsb#error-responses).

<DocExample id="v31/historical-adsb/history-fetch" />

### Примечания по реализации [#implementation-notes]

**Выбирайте правильный префикс пути.** Используйте `/ultra/history/...` на Pro и выше, когда достаточно окна в 90 дней. Используйте `/mega/history/...` на Ultra/Mega, когда нужно до 365 дней или более высокие лимиты на запрос.

**Связывайте запросы через `flight_id`.** Никогда не угадывайте временные окна для воспроизведения трека — сначала выполните поиск, затем вызовите `/history/flight/{flight_id}/track`, чтобы получить путь с автоматически определёнными границами.

**Разбивайте большие окна на страницы.** Если `count` равен запрошенному `limit`, сузьте окно `start`/`end` или увеличьте `limit` (в пределах ограничений уровня) и объединяйте результаты на стороне клиента.

**Регистрационный номер или hex.** Предпочитайте `registration`, если ваши пользователи знают бортовые номера; используйте `icao24` при приёме «сырых» потоков [ADS-B](https://www.faa.gov/air_traffic/technology/adsb).

## Ответы с ошибками [#error-responses]

Ограничения тарифа `401`/`403`: [раздел «Исторические данные ADS-B»](/docs/v31/historical-adsb#error-responses). Ошибки, специфичные для эндпоинта:

### 422 — нет фильтра поиска [#422--no-search-filter]

Требуется хотя бы один из параметров `icao24`, `registration`, `callsign`, `departure_icao` или `arrival_icao`:

```json
{
  "detail": [
    {
      "type": "value_error",
      "loc": ["query"],
      "msg": "At least one filter (icao24, registration, callsign, departure_icao, arrival_icao) is required"
    }
  ]
}
```

### 422 — слишком широкое окно [#422--window-too-wide]

Возвращается, когда охват `start`/`end` превышает максимум для пути — **90 дней** на `/ultra/history/...` или **365 дней** на `/mega/history/...`:

```json
{
  "detail": "Query window exceeds maximum of 90 days for your plan on /ultra/history/..."
}
```

### 422 — несоответствие регистрационного номера и ICAO24 [#422--registration-and-icao24-mismatch]

Когда переданы оба идентификатора, но они относятся к разным воздушным судам:

```json
{
  "detail": "registration and icao24 refer to different aircraft"
}
```

<APIPage document="&#x22;https://api.skylinkapi.com/v3.1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/ultra/history/flights&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/mega/history/flights&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />