# История местоположений

Исторические снимки местоположения ADS-B по hex-коду ICAO24 или бортовому номеру — от новых к старым, с привязкой к окнам рейсов.



Получайте необработанную временную шкалу местоположений воздушного судна по бортовому номеру или hex-коду [ICAO24](/docs/v31/adsb) — без предварительного шага поиска. В отличие от эндпоинта [трека рейса](/docs/v31/historical-adsb-flight-detail#flight-track), история местоположений не ограничена одним рейсом и может охватывать несколько рейсов в одном окне.

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

Уровни тарифов: [главная страница исторических данных 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> — используйте префикс пути, соответствующий нужному окну.
  </DocRequirement>
</DocRequirements>

<DocJumpNav>
  <DocJumpLink href="#aircraft-position-history-by-icao24" icon="solar:transmission-bold-duotone">
    По 

    [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address)
  </DocJumpLink>

  <DocJumpLink href="#aircraft-position-history-by-registration" icon="solar:plate-bold-duotone">
    По регистрационному номеру
  </DocJumpLink>
</DocJumpNav>

<a id="aircraft-position-history-by-icao24" />

## По ICAO24 [#by-icao24]

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

<DocApiPath method="GET" path="/ultra/history/positions/{icao24}" />

| Параметр | Тип     | Обязательный | По умолчанию | Описание                                                                |
| -------- | ------- | ------------ | ------------ | ----------------------------------------------------------------------- |
| `icao24` | string  | Да           | -            | Hex-код ICAO24 воздушного судна (6 символов)                            |
| `start`  | string  | Нет          | 24 ч назад   | Начало окна — ISO 8601                                                  |
| `end`    | string  | Нет          | сейчас       | Конец окна — ISO 8601                                                   |
| `limit`  | integer | Нет          | `1000`       | Макс. количество строк местоположений (не более **5000** на пути ULTRA) |

Окно запроса не может превышать **90 дней** на `/ultra/history/...`.

<DocDetails title="Путь MEGA — по [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address) (`/mega/history/...`)">
  <DocApiPath method="GET" path="/mega/history/positions/{icao24}" />

  | Параметр | Тип     | Обязательный | По умолчанию | Описание                                                           |
  | -------- | ------- | ------------ | ------------ | ------------------------------------------------------------------ |
  | `icao24` | string  | Да           | -            | Hex-код ICAO24 воздушного судна                                    |
  | `start`  | string  | Нет          | 24 ч назад   | Начало окна — ISO 8601 (на пути MEGA охват не более **365 дней**)  |
  | `end`    | string  | Нет          | сейчас       | Конец окна                                                         |
  | `limit`  | integer | Нет          | `1000`       | Макс. количество местоположений (не более **10 000** на пути MEGA) |

  Требуется тариф **Ultra** или **Mega**. Структура ответа та же, что и для ULTRA.
</DocDetails>

<a id="aircraft-position-history-by-registration" />

## По регистрационному номеру [#by-registration]

Структура ответа та же, что и для запроса [по ICAO24](#aircraft-position-history-by-icao24), но эндпоинт принимает [регистрационный](/docs/v31/aircraft-lookup) (бортовой) номер (например, `N12345`, `G-XWBA`), который преобразуется в [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address) на стороне сервера. Возвращает `404`, если регистрационного номера нет в реестре воздушных судов.

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

<DocApiPath method="GET" path="/ultra/history/positions/registration/{registration}" />

| Параметр       | Тип     | Обязательный | По умолчанию | Описание                                                                |
| -------------- | ------- | ------------ | ------------ | ----------------------------------------------------------------------- |
| `registration` | string  | Да           | -            | Бортовой номер воздушного судна                                         |
| `start`        | string  | Нет          | 24 ч назад   | Начало окна — ISO 8601                                                  |
| `end`          | string  | Нет          | сейчас       | Конец окна — ISO 8601                                                   |
| `limit`        | integer | Нет          | `1000`       | Макс. количество строк местоположений (не более **5000** на пути ULTRA) |

<DocDetails title="Путь MEGA — по регистрационному номеру (`/mega/history/...`)">
  <DocApiPath method="GET" path="/mega/history/positions/registration/{registration}" />

  | Параметр       | Тип     | Обязательный | По умолчанию | Описание                                                           |
  | -------------- | ------- | ------------ | ------------ | ------------------------------------------------------------------ |
  | `registration` | string  | Да           | -            | Бортовой номер                                                     |
  | `start`        | string  | Нет          | 24 ч назад   | Начало окна — ISO 8601 (на пути MEGA охват не более **365 дней**)  |
  | `end`          | string  | Нет          | сейчас       | Конец окна                                                         |
  | `limit`        | integer | Нет          | `1000`       | Макс. количество местоположений (не более **10 000** на пути MEGA) |

  Требуется тариф **Ultra** или **Mega**. Структура ответа та же, что и для ULTRA.
</DocDetails>

## Ответ [#response]

```json
{
  "icao24": "40621d",
  "count": 864,
  "positions": [
    {
      "timestamp": "2026-05-13T03:08:05Z",
      "icao24": "40621d",
      "latitude": 40.6413,
      "longitude": -73.7781,
      "altitude_baro": 0,
      "ground_speed": 12,
      "track": 90,
      "vertical_rate": 0,
      "callsign": "BAW178",
      "is_on_ground": true,
      "registration": "G-XWBA",
      "aircraft_type": "B77W",
      "gps_spoofed": false
    }
  ],
  "flights": [
    {
      "flight_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "callsign": "BAW178",
      "flight_number": "BAW178",
      "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",
      "takeoff_time": "2026-05-12T19:45:00Z",
      "landing_time": "2026-05-13T03:08:00Z",
      "flight_start": "2026-05-12T19:42:05Z",
      "flight_end": "2026-05-13T03:11:10Z",
      "flight_state": "ARCHIVED"
    }
  ]
}
```

| Поле        | Тип     | Обязательный | Null?   | Описание                                                                                                       |
| ----------- | ------- | ------------ | ------- | -------------------------------------------------------------------------------------------------------------- |
| `icao24`    | string  | **Да**       | Никогда | Hex-код запрошенного воздушного судна                                                                          |
| `count`     | integer | **Да**       | Никогда | Количество элементов в `positions`                                                                             |
| `positions` | array   | **Да**       | Никогда | [Снимки местоположения](/docs/v31/historical-adsb-flight-detail#position-snapshot-positions) от новых к старым |
| `flights`   | array   | **Да**       | Никогда | Архивные рейсы, пересекающиеся с окном                                                                         |

Эндпоинт по регистрационному номеру добавляет поле верхнего уровня `registration`, возвращающее определённый бортовой номер; `icao24` заполняется после поиска на стороне сервера.

### Окно рейса (`flights[]`) [#flight-window-flights]

| Поле                     | Тип            | Обязательный | Null?   | Описание                                             |
| ------------------------ | -------------- | ------------ | ------- | ---------------------------------------------------- |
| `flight_id`              | string         | **Да**       | Никогда | UUID для запросов деталей и трека                    |
| `callsign`               | string \| null | Нет          | **Да**  | Позывной во время этого рейса                        |
| `flight_number`          | string \| null | Нет          | **Да**  | Нормализованный номер рейса, если удалось определить |
| `departure_airport_icao` | string \| null | Нет          | **Да**  | Аэропорт вылета, если удалось определить             |
| `departure_airport_iata` | string \| null | Нет          | **Да**  | IATA-код аэропорта вылета                            |
| `departure_airport_name` | string \| null | Нет          | **Да**  | Название аэропорта вылета                            |
| `arrival_airport_icao`   | string \| null | Нет          | **Да**  | Аэропорт прилёта, если удалось определить            |
| `arrival_airport_iata`   | string \| null | Нет          | **Да**  | IATA-код аэропорта прилёта                           |
| `arrival_airport_name`   | string \| null | Нет          | **Да**  | Название аэропорта прилёта                           |
| `takeoff_time`           | string \| null | Нет          | **Да**  | Время взлёта для этого рейса (ISO 8601)              |
| `landing_time`           | string \| null | Нет          | **Да**  | Время посадки для этого рейса (ISO 8601)             |
| `flight_start`           | string         | **Да**       | Никогда | Первое архивное местоположение в окне этого рейса    |
| `flight_end`             | string         | **Да**       | Никогда | Последнее архивное местоположение в окне этого рейса |
| `flight_state`           | string \| null | Нет          | **Да**  | Состояние в архиве (например, `ARCHIVED`)            |

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

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

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

Постройте трек для воспроизведения по бортовому номеру воздушного судна. Пример ниже получает историю местоположений по регистрационному номеру, переставляет местоположения в хронологическом порядке для воспроизведения на карте и обрабатывает оба случая ошибок: `404` (неизвестный бортовой номер) и `422` (слишком широкое окно). Если ретроспективы в 90 дней недостаточно, переходите на путь `/mega/history/...`.

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

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

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

**Важно:** история местоположений возвращает `positions` от новых к старым. Для воспроизведения на карте переставьте их в хронологическом порядке.

**Размер окна.** При частоте выборки раз в 5 секунд один рейс даёт \~700–1500 строк местоположений. Для многодневных запросов увеличьте `limit` (до 5000 на ULTRA, до 10 000 на MEGA) или сузьте окно и объедините результаты на стороне клиента.

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

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

### 404 — регистрационный номер не найден [#404--registration-not-found]

```json
{
  "detail": "Registration 'N00000' not found"
}
```

Возвращается эндпоинтом `/history/positions/registration/{registration}`, если бортового номера нет в реестре воздушных судов.

### 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/..."
}
```

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