История местоположений
Получайте необработанную временную шкалу местоположений воздушного судна по бортовому номеру или hex-коду ICAO24 — без предварительного шага поиска. В отличие от эндпоинта трека рейса, история местоположений не ограничена одним рейсом и может охватывать несколько рейсов в одном окне.
Выбор пути: чтобы получить трек одного архивного рейса от выхода до выхода, используйте цепочку регистрационный номер → поиск рейсов → flight_id → трек. Для необработанной временной шкалы по нескольким рейсам или если вы не знаете границ рейсов, используйте напрямую регистрационный номер → местоположения.
Уровни тарифов: главная страница исторических данных ADS-B.
Требования
x-api-key в каждом запросе (прямая подписка). Подробнее →Pro, Ultra или Mega — используйте префикс пути, соответствующий нужному окну.
Подробнее →По ICAO24
Запрос
https://data.skylinkapi.com/v3.1/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/....
Путь MEGA — по [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address) (`/mega/history/...`)Развернуть раздел
https://data.skylinkapi.com/v3.1/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.
По регистрационному номеру
Структура ответа та же, что и для запроса по ICAO24, но эндпоинт принимает регистрационный (бортовой) номер (например, N12345, G-XWBA), который преобразуется в ICAO24 на стороне сервера. Возвращает 404, если регистрационного номера нет в реестре воздушных судов.
Запрос
https://data.skylinkapi.com/v3.1/ultra/history/positions/registration/{registration}| Параметр | Тип | Обязательный | По умолчанию | Описание |
|---|---|---|---|---|
registration | string | Да | - | Бортовой номер воздушного судна |
start | string | Нет | 24 ч назад | Начало окна — ISO 8601 |
end | string | Нет | сейчас | Конец окна — ISO 8601 |
limit | integer | Нет | 1000 | Макс. количество строк местоположений (не более 5000 на пути ULTRA) |
Путь MEGA — по регистрационному номеру (`/mega/history/...`)Развернуть раздел
https://data.skylinkapi.com/v3.1/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.
Ответ
{
"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 | Да | Никогда | Снимки местоположения от новых к старым |
flights | array | Да | Никогда | Архивные рейсы, пересекающиеся с окном |
Эндпоинт по регистрационному номеру добавляет поле верхнего уровня registration, возвращающее определённый бортовой номер; icao24 заполняется после поиска на стороне сервера.
Окно рейса (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) |
Клиентские типы
"""Typed models for Historical ADS-B - matches historical-adsb.mdx field tables."""from __future__ import annotationsfrom dataclasses import dataclassfrom typing import Literal@dataclassclass HistoricalFlightSummary: flight_id: str icao24: str | None callsign: str | None flight_number: str | None tail_number: str | None departure_airport_icao: str | None arrival_airport_icao: str | None flight_start: str flight_end: str takeoff_time: str | None landing_time: str | None flight_duration_min: float | None distance_nm: float | None@dataclassclass HistoricalPosition: timestamp: str icao24: str latitude: float longitude: float altitude_baro: float | None ground_speed: float | None track: float | None vertical_rate: float | None is_on_ground: bool@dataclassclass HistoricalFlightWindow: flight_id: str callsign: str | None departure_airport_icao: str | None arrival_airport_icao: str | None takeoff_time: str | None landing_time: str | None flight_start: str flight_end: str flight_state: str | None@dataclassclass AirportTrafficFlight: flight_id: str icao24: str | None callsign: str | None departure_airport_icao: str | None arrival_airport_icao: str | None takeoff_time: str | None landing_time: str | None flight_duration_min: float | None distance_nm: float | None@dataclassclass AirportTrafficResponse: icao: str direction: Literal["dep", "arr", "both"] count: int flights: list[AirportTrafficFlight]Интеграция
Постройте трек для воспроизведения по бортовому номеру воздушного судна. Пример ниже получает историю местоположений по регистрационному номеру, переставляет местоположения в хронологическом порядке для воспроизведения на карте и обрабатывает оба случая ошибок: 404 (неизвестный бортовой номер) и 422 (слишком широкое окно). Если ретроспективы в 90 дней недостаточно, переходите на путь /mega/history/....
import osfrom datetime import datetime, timedelta, timezoneimport requestsBASE = "https://data.skylinkapi.com/v3.1"HEADERS = { "x-api-key": os.getenv("SKYLINK_API_KEY") or os.getenv("SKYLINK_API_KEY", "YOUR_API_KEY")}def fetch_positions(icao24: str, *, tier: str = "ultra", hours: int = 24) -> dict: now = datetime.now(timezone.utc) start = (now - timedelta(hours=hours)).strftime("%Y-%m-%dT%H:%M:%SZ") end = now.strftime("%Y-%m-%dT%H:%M:%SZ") r = requests.get( f"{BASE}/{tier}/history/positions/{icao24.lower()}", headers=HEADERS, params={"start": start, "end": end, "limit": 100}, timeout=(10, 30), ) r.raise_for_status() return r.json()if __name__ == "__main__": import json # Resolve icao24 from a recent archived flight r = requests.get( f"{BASE}/ultra/history/flights", headers=HEADERS, params={"callsign": "BAW178", "limit": 1}, timeout=(10, 25), ) r.raise_for_status() flights = r.json().get("flights") or [] if not flights: print("No flight found") else: icao24 = flights[0]["icao24"] data = fetch_positions(icao24) print(json.dumps({"icao24": data.get("icao24"), "count": data.get("count")}, indent=2))Примечания по реализации
Регистрационный номер или hex-код. Предпочитайте registration, если ваши пользователи знают бортовые номера; используйте icao24 при приёме необработанных потоков ADS-B. Эндпоинты по регистрационному номеру возвращают 404, если бортовой номер неизвестен.
Важно: история местоположений возвращает positions от новых к старым. Для воспроизведения на карте переставьте их в хронологическом порядке.
Размер окна. При частоте выборки раз в 5 секунд один рейс даёт ~700–1500 строк местоположений. Для многодневных запросов увеличьте limit (до 5000 на ULTRA, до 10 000 на MEGA) или сузьте окно и объедините результаты на стороне клиента.
Ответы с ошибками
Ограничение по тарифу 401/403: главная страница исторических данных ADS-B. Ошибки, специфичные для эндпоинта:
404 — регистрационный номер не найден
{
"detail": "Registration 'N00000' not found"
}Возвращается эндпоинтом /history/positions/registration/{registration}, если бортового номера нет в реестре воздушных судов.
422 — слишком широкое окно
Возвращается, если интервал start/end превышает максимум для пути — 90 дней на /ultra/history/... или 365 дней на /mega/history/...:
{
"detail": "Query window exceeds maximum of 90 days for your plan on /ultra/history/..."
}Your SkyLink licence key, for keys bought direct from skylinkapi.com.
In: header
Path Parameters
Query Parameters
Start datetime ISO 8601. Defaults to 24 h ago.
End datetime ISO 8601. Defaults to now.
Max position rows (default 1000, max 5000)
10001 <= value <= 5000Response Body
application/json
application/json
curl -X GET "https://data.skylinkapi.com/v3.1/ultra/history/positions/a835af"null{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string",
"input": null,
"ctx": {}
}
]
}Your SkyLink licence key, for keys bought direct from skylinkapi.com.
In: header
Path Parameters
Query Parameters
Start datetime ISO 8601. Defaults to 24 h ago.
End datetime ISO 8601. Defaults to now.
Max position rows (default 1000, max 5000)
10001 <= value <= 5000Response Body
application/json
application/json
curl -X GET "https://data.skylinkapi.com/v3.1/ultra/history/positions/registration/N12345"null{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string",
"input": null,
"ctx": {}
}
]
}Your SkyLink licence key, for keys bought direct from skylinkapi.com.
In: header
Path Parameters
Query Parameters
Start datetime ISO 8601. Defaults to 24 h ago.
End datetime ISO 8601. Defaults to now.
Max position rows (default 1000, max 10000)
10001 <= value <= 10000Response Body
application/json
application/json
curl -X GET "https://data.skylinkapi.com/v3.1/mega/history/positions/a835af"null{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string",
"input": null,
"ctx": {}
}
]
}Your SkyLink licence key, for keys bought direct from skylinkapi.com.
In: header
Path Parameters
Query Parameters
Start datetime ISO 8601. Defaults to 24 h ago.
End datetime ISO 8601. Defaults to now.
Max position rows (default 1000, max 10000)
10001 <= value <= 10000Response Body
application/json
application/json
curl -X GET "https://data.skylinkapi.com/v3.1/mega/history/positions/registration/N12345"null{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string",
"input": null,
"ctx": {}
}
]
}