# Отслеживание воздушных судов по ADS-B

Позиции ВС по ADS-B в реальном времени: географические фильтры, статистика парка и состояние приёма данных для интеграций онлайн-отслеживания.



Получайте позиции воздушных судов в реальном времени, фильтруйте их по области просмотра карты и проверяйте состояние потока [ADS-B](https://www.faa.gov/air_traffic/technology/adsb). **[ADS-B](https://www.faa.gov/air_traffic/technology/adsb)** (Automatic Dependent Surveillance–Broadcast, автоматическое зависимое наблюдение — вещание) — это сигнал транспондера, передающий идентификатор и позицию воздушного судна. Каждая запись в реальном времени содержит **[ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address)** (6-символьный шестнадцатеричный код, однозначно идентифицирующий транспондер ВС, например `0A0022`), позицию, **барометрическую высоту** (высоту, измеренную барометрическим высотомером ВС, в футах над MSL), путевую скорость, **путевой угол** (track — направление движения ВС относительно земли в градусах от истинного меридиана) и **вертикальную скорость** (скорость набора высоты или снижения в футах в минуту).

Данные обновляются каждые несколько секунд. Пагинация необязательна: не указывайте `limit`, чтобы получить весь набор совпадений (ограничивайте объём фильтрами), или передайте `limit` и `offset`, чтобы постранично просматривать большие наборы результатов. Статические регистрационные сведения по hex-адресу можно получить, передав его в [Поиск воздушных судов](/docs/v31/aircraft-lookup#lookup-by-icao24). Исторические треки см. в разделе [Исторические данные ADS-B](/docs/v31/historical-adsb).

<DocJumpNav>
  <DocJumpLink href="#live-aircraft" icon="solar:radar-2-bold-duotone">
    ВС в реальном времени
  </DocJumpLink>

  <DocJumpLink href="#tracking-statistics" icon="solar:chart-2-bold-duotone">
    Статистика
  </DocJumpLink>

  <DocJumpLink href="#service-health" icon="solar:heart-pulse-bold-duotone">
    Состояние
  </DocJumpLink>
</DocJumpNav>

<DocRequirements>
  <DocRequirementAuth />
</DocRequirements>

| Эндпоинт                        | Когда использовать                                                                           |
| ------------------------------- | -------------------------------------------------------------------------------------------- |
| `GET /adsb/aircraft`            | Позиции в реальном времени — тайлы карты, табло воздушной обстановки, отфильтрованные потоки |
| `GET /adsb/aircraft/statistics` | Агрегаты по всему парку — в воздухе и на земле, статистика высот                             |
| `GET /adsb/health`              | Состояние потока — статус подключения и число активных ВС перед запуском цикла опроса        |

## Воздушные суда в реальном времени [#live-aircraft]

Возвращает отслеживаемые в данный момент воздушные суда с последней позицией и данными полёта. Каждая запись содержит позицию, высоту, путевую скорость, путевой угол, вертикальную скорость и, при наличии, поля обогащения.

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

<DocApiPath method="GET" path="/adsb/aircraft" />

| Параметр       | Тип     | Обязательный | По умолчанию | Описание                                                                                                                              |
| -------------- | ------- | ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `icao24`       | string  | Нет          | -            | Фильтр по 6-символьному hex-адресу транспондера (в нижнем или верхнем регистре; ведущие нули сохраняются, например `0A0022`)          |
| `callsign`     | string  | Нет          | -            | Частичное совпадение позывного (без учёта регистра), например `DAH` совпадает с `DAH2055`                                             |
| `lat`          | number  | Нет          | -            | Широта центра для поиска по радиусу (от `-90` до `90`)                                                                                |
| `lon`          | number  | Нет          | -            | Долгота центра для поиска по радиусу (от `-180` до `180`)                                                                             |
| `radius`       | number  | Нет          | -            | Радиус поиска в **километрах** (максимум 1000)                                                                                        |
| `bbox`         | string  | Нет          | -            | Ограничивающий прямоугольник `lat1,lon1,lat2,lon2` — сначала юго-западный угол, затем северо-восточный. Пример: `51.2,-0.8,51.6,-0.2` |
| `min_alt`      | number  | Нет          | -            | Минимальная высота в футах                                                                                                            |
| `max_alt`      | number  | Нет          | -            | Максимальная высота в футах                                                                                                           |
| `min_speed`    | number  | Нет          | -            | Минимальная путевая скорость в узлах                                                                                                  |
| `max_speed`    | number  | Нет          | -            | Максимальная путевая скорость в узлах                                                                                                 |
| `registration` | string  | Нет          | -            | Фильтр по регистрационному номеру (бортовому номеру)                                                                                  |
| `airline`      | string  | Нет          | -            | Фильтр по названию авиакомпании-эксплуатанта                                                                                          |
| `photos`       | boolean | Нет          | `false`      | Загружать миниатюры фотографий (медленнее; не более 50 ВС на страницу)                                                                |
| `limit`        | integer | Нет          | весь набор   | Размер страницы — не указывайте, чтобы вернуть все совпадения                                                                         |
| `offset`       | integer | Нет          | `0`          | Число пропускаемых записей для пагинации                                                                                              |

**Правила сочетания фильтров** — самая частая причина ошибок `422`:

| Режим поиска          | Обязательные параметры   | Примечания                                        |
| --------------------- | ------------------------ | ------------------------------------------------- |
| Круг                  | `lat` + `lon` + `radius` | Все три вместе                                    |
| Прямоугольник         | `bbox`                   | Сначала юго-западный угол, затем северо-восточный |
| Ни то ни другое       | —                        | **Не** смешивайте параметры круга и bbox          |
| Частичная геопривязка | —                        | `lat` без `lon` (и наоборот) отклоняется          |

Сочетайте фильтры высоты и скорости, чтобы выделить трафик на маршруте.

**Важно:** по умолчанию `photos&#x60; равен &#x2A;*`false`**. Значение `photos=true` замедляет запрос и ограничивает выдачу 50 ВС на страницу — включайте его только для детальных представлений, а не для тайлов карты или частого опроса.

### Ответ [#response]

```json
{
  "aircraft": [
    {
      "icao24": "0A0022",
      "callsign": "DAH2055",
      "latitude": 51.274109,
      "longitude": -0.675964,
      "altitude": 9075.0,
      "ground_speed": 298.3,
      "track": 153.09,
      "vertical_rate": 2880.0,
      "is_on_ground": false,
      "last_seen": "2026-06-16T14:21:45.674566",
      "first_seen": "2026-06-16T14:17:09.312068",
      "registration": "7T-VJP",
      "aircraft_type": "Boeing B738",
      "airline": "Air Algerie",
      "photo_url": null
    }
  ],
  "total_count": 67,
  "timestamp": "2026-06-16T14:21:49.178448"
}
```

| Поле          | Тип               | Обязательный | Может быть null? | Описание                                            |
| ------------- | ----------------- | ------------ | ---------------- | --------------------------------------------------- |
| `aircraft`    | array             | **Да**       | Никогда          | Найденные воздушные суда (массив может быть пустым) |
| `total_count` | integer           | **Да**       | Никогда          | Число воздушных судов в этом ответе                 |
| `timestamp`   | string (ISO 8601) | Нет          | Никогда          | Когда был сформирован снимок                        |

#### Элемент воздушного судна (`aircraft[]`) [#aircraft-item-aircraft]

| Поле            | Тип               | Обязательный | Может быть null? | Описание                                                |
| --------------- | ----------------- | ------------ | ---------------- | ------------------------------------------------------- |
| `icao24`        | string            | **Да**       | Никогда          | 24-битный шестнадцатеричный идентификатор ICAO          |
| `callsign`      | string \| null    | Нет          | **Да**           | Позывной рейса, если он передаётся                      |
| `latitude`      | number \| null    | Нет          | **Да**           | Широта WGS-84                                           |
| `longitude`     | number \| null    | Нет          | **Да**           | Долгота WGS-84                                          |
| `altitude`      | number \| null    | Нет          | **Да**           | Барометрическая высота в футах над MSL                  |
| `ground_speed`  | number \| null    | Нет          | **Да**           | Путевая скорость в узлах                                |
| `track`         | number \| null    | Нет          | **Да**           | Путевой угол в градусах (0–360)                         |
| `vertical_rate` | number \| null    | Нет          | **Да**           | Вертикальная скорость в футах в минуту                  |
| `is_on_ground`  | boolean \| null   | Нет          | **Да**           | `true`, когда ВС находится на земле                     |
| `last_seen`     | string (ISO 8601) | **Да**       | Никогда          | Время последнего наблюдения                             |
| `first_seen`    | string (ISO 8601) | **Да**       | Никогда          | Время первого обнаружения в текущем сеансе отслеживания |
| `registration`  | string \| null    | Нет          | **Да**           | Регистрационный номер, если он определён                |
| `aircraft_type` | string \| null    | Нет          | **Да**           | Описание типа или обозначение типа ICAO                 |
| `airline`       | string \| null    | Нет          | **Да**           | Авиакомпания-эксплуатант, если она определена           |
| `photo_url`     | string \| null    | Нет          | **Да**           | URL миниатюры при `photos=true`                         |

Поля обогащения (`registration`, `aircraft_type`, `airline`) могут быть `null`, если hex-адреса нет в реестре или в потоке отсутствует связь с позывным.

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

## Статистика отслеживания [#tracking-statistics]

Агрегированная статистика по отслеживаемому в данный момент парку: общее число ВС, число ВС на земле и в воздухе, сводка по высотам. Параметры не требуются. Полезно для дашбордов мониторинга.

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

<DocApiPath method="GET" path="/adsb/aircraft/statistics" />

Query-параметров и параметров пути нет.

### Ответ [#response-1]

```json
{
  "total_aircraft": 9889,
  "positioned_aircraft": 9889,
  "on_ground": 412,
  "airborne": 9477,
  "altitude_stats": {
    "min_altitude": 100.0,
    "max_altitude": 56600.0,
    "avg_altitude": 21338.04
  },
  "timestamp": "2026-06-16T14:21:50.116343"
}
```

| Поле                          | Тип               | Обязательный | Может быть null? | Описание                                         |
| ----------------------------- | ----------------- | ------------ | ---------------- | ------------------------------------------------ |
| `total_aircraft`              | integer           | **Да**       | Никогда          | Общее число отслеживаемых ВС                     |
| `positioned_aircraft`         | integer           | **Да**       | Никогда          | ВС с известной позицией                          |
| `on_ground`                   | integer           | **Да**       | Никогда          | ВС с отметкой «на земле»                         |
| `airborne`                    | integer           | **Да**       | Никогда          | ВС с отметкой «в воздухе»                        |
| `altitude_stats`              | object            | **Да**       | Никогда          | Сводка по высотам парка                          |
| `altitude_stats.min_altitude` | number            | **Да**       | Никогда          | Минимальная зарегистрированная высота (в футах)  |
| `altitude_stats.max_altitude` | number            | **Да**       | Никогда          | Максимальная зарегистрированная высота (в футах) |
| `altitude_stats.avg_altitude` | number            | **Да**       | Никогда          | Средняя высота по парку (в футах)                |
| `timestamp`                   | string (ISO 8601) | **Да**       | Никогда          | Время снимка                                     |

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

## Состояние сервиса [#service-health]

Возвращает статус подключения [ADS-B](https://www.faa.gov/air_traffic/technology/adsb) и число активных ВС. Используйте для мониторинга доступности и предварительных проверок перед опросом потока в реальном времени.

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

<DocApiPath method="GET" path="/adsb/health" />

Query-параметров и параметров пути нет.

### Ответ [#response-2]

```json
{
  "status": "healthy",
  "connected": true,
  "active_aircraft_count": 9889,
  "connection_uptime": null,
  "last_message_received": "2026-06-16T14:21:46.212802"
}
```

| Поле                    | Тип                       | Обязательный | Может быть null? | Описание                                           |
| ----------------------- | ------------------------- | ------------ | ---------------- | -------------------------------------------------- |
| `status`                | string                    | **Да**       | Никогда          | Метка статуса сервиса, например `healthy`          |
| `connected`             | boolean                   | **Да**       | Никогда          | Активно ли подключение к хабу ADS-B                |
| `active_aircraft_count` | integer                   | **Да**       | Никогда          | Число отслеживаемых в данный момент ВС             |
| `connection_uptime`     | number \| null            | Нет          | **Да**           | Время непрерывной работы в секундах, если доступно |
| `last_message_received` | string (ISO 8601) \| null | Нет          | **Да**           | Метка времени последнего сообщения из потока       |

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

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

<DocClientTypes id="v31/adsb/live-types" />

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

Опрашивайте воздушные суда в реальном времени вблизи аэропорта, чтобы наложить воздушную обстановку на карту.

Пример ниже выполняет поиск по радиусу с ограничением размера страницы, использует короткие тайм-ауты (10 с / 15 с) и преобразует результаты в маркеры на карте. Не кэшируйте позиции в реальном времени — опрашивайте каждые 5–15 секунд в зависимости от вашей квоты и требований к UX.

<DocExample id="v31/adsb/live-fetch" />

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

**Интервал опроса.** Данные [ADS-B](https://www.faa.gov/air_traffic/technology/adsb) обновляются каждые несколько секунд. Опрос чаще чем раз в \~5 с редко повышает актуальность данных и быстро расходует квоту.

**Ограничение области запросов.** Для карт всегда передавайте `lat`/`lon`/`radius` или `bbox` — глобальные запросы без фильтров могут возвращать очень большие объёмы данных.

**Пагинация.** Используйте `limit` + `offset` при выводе таблиц. `total_count` отражает размер текущей страницы, а не общее число ВС в парке.

**Пробелы в обогащении.** `registration` и `aircraft_type` могут быть `null` для военных, заблокированных или незарегистрированных hex-кодов. В этом случае отображайте позывной и [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address).

**Цепочка «реальное время → лётно-технические характеристики».** `aircraft_type` в потоке реального времени часто содержит маркетинговое название (например, `"Boeing B738"`), а не обозначение типа ICAO. Чтобы получить [лётно-технические характеристики ВС](/docs/v31/aircraft-performance), вызовите [Поиск воздушных судов](/docs/v31/aircraft-lookup#lookup-by-icao24) с `icao24` и используйте `aircraft.icao_type` из ответа реестра.

**Нормализация [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address).** Принимайте 6-символьные hex-коды из потоков [ADS-B](https://www.faa.gov/air_traffic/technology/adsb); верхний и нижний регистр равнозначны. Дополняйте короткие адреса ведущими нулями, если источник их опускает.

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

Общие ошибки платформы (авторизация, ограничения частоты запросов, ошибки сервера) описаны в разделе [Обработка ошибок](/docs/errors). Поведение, специфичное для эндпоинта:

### 404 — по фильтру ICAO24 ничего не найдено (ВС в реальном времени) [#404--icao24-filter-not-found-live-aircraft]

Если при фильтрации по `icao24` ни одно воздушное судно не найдено:

```json
{
  "error": "Aircraft not found",
  "detail": "No aircraft found with ICAO24 000000",
  "timestamp": "2026-06-16T14:00:00Z"
}
```

Применяется только тогда, когда `icao24` передан как фильтр, — но не к пустым результатам поиска по радиусу.

### 422 — недопустимое сочетание фильтров [#422--invalid-filter-combination]

```json
{
  "detail": [
    {
      "type": "greater_than",
      "loc": ["query", "radius"],
      "msg": "Input should be greater than 0"
    }
  ]
}
```

Возникает, когда числовые фильтры выходят за допустимые пределы (например, `radius` ≤ 0 или высота вне диапазона 0–60000 ft) либо когда смешаны параметры круга и bbox.

***

См. также: [Поиск воздушных судов](/docs/v31/aircraft-lookup) · [Исторические данные ADS-B](/docs/v31/historical-adsb) · [Статус рейса](/docs/v31/flight-status)