Поиск воздушных судов

Получайте тип воздушного судна, оператора и фотографии по регистрационному номеру (национальный регистрационный идентификатор ВС, например G-STBC, N12345) или по ICAO24 (6-символьный шестнадцатеричный адрес транспондера, передаваемый в ADS-B, например 40621D). Реестр воздушных судов SkyLink содержит более 615 000 записей и обновляется ежедневно — новые регистрации и смены владельцев могут появляться с задержкой относительно официальных реестров авиационных властей.

Используйте поиск по регистрационному номеру, когда в вашем интерфейсе или строке расписания уже есть бортовой номер. Используйте поиск по ICAO24, когда вы получаете hex-коды из потока ADS-B в реальном времени и хотите дополнить их метаданными о типе и операторе. Получив icao_type (4-символьный код типа ВС, используемый в планах полётов, например B738), переходите к эндпоинту Лётно-технические характеристики ВС за крейсерской скоростью, дальностью и категорией турбулентности следа.

Важно: поиск по регистрационному номеру и по ICAO24 при отсутствии совпадения возвращает HTTP 200 с found: false и aircraft: null — никогда не 404. Проверяйте поле found в теле JSON; не считайте такой ответ ошибкой HTTP.

Важно: по умолчанию photos равен true для удобства, но это увеличивает задержку. Передавайте photos=false в списочных представлениях, задачах пакетного обогащения данных и слоях карты, где миниатюры не нужны.

Поиск по регистрационному номеру

Поиск воздушного судна по регистрационному (бортовому) номеру. В v3.1 в объект воздушного судна добавлены поля manufacturer_and_model, airline_code, serial_number и is_private_operator.

Запрос

Ответ

{
  "query": "G-STBC",
  "found": true,
  "aircraft": {
    "registration": "G-STBC",
    "icao24": "40621D",
    "icao_type": "B77W",
    "type_name": "BOEING 777-36NER",
    "manufacturer": "Boeing Company",
    "manufacturer_and_model": "Boeing Company BOEING 777-36NER",
    "owner_operator": "British Airways",
    "airline_code": null,
    "is_private_operator": false,
    "serial_number": "38287",
    "year_built": null,
    "photos": [
      {
        "image": "https://image.airport-data.com/aircraft/001912010.jpg",
        "link": "https://airport-data.com/aircraft/photo/001912010",
        "photographer": "Roberto Cassar"
      }
    ]
  }
}

Объект воздушного судна (aircraft)

Элемент фотографии (aircraft.photos[])

curl -X GET "https://data.skylinkapi.com/v3.1/aircraft/registration/N12345"

{
  "query": "G-STBC",
  "found": true,
  "country": "United Kingdom",
  "country_code": "GB",
  "aircraft": {
    "registration": "G-STBC",
    "icao24": "40621d",
    "icao_type": "B77W",
    "type_name": "777-36N",
    "manufacturer": "Boeing",
    "manufacturer_and_model": "Boeing 777-36N",
    "owner_operator": "British Airways",
    "airline_code": "BAW",
    "is_private_operator": false,
    "serial_number": "38695",
    "year_built": "2013",
    "photos": [
      {
        "image": "https://image.airport-data.com/aircraft/001912010.jpg",
        "link": "https://airport-data.com/aircraft/photo/001912010.html",
        "photographer": "Roberto Cassar"
      }
    ]
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Поиск по ICAO24

Поиск воздушного судна по шестнадцатеричному адресу транспондера ICAO24 — тому же идентификатору, который передаётся в ADS-B (например, 40621D). Возвращает объект aircraft той же структуры, что и поиск по регистрационному номеру.

Запрос

Ответ

Та же структура ответа, что и при поиске по регистрационному номеру. Поле query повторяет адрес ICAO24.

curl -X GET "https://data.skylinkapi.com/v3.1/aircraft/icao24/a835af"

{
  "query": "40621D",
  "found": true,
  "country": "United Kingdom",
  "country_code": "GB",
  "aircraft": {
    "registration": "G-STBC",
    "icao24": "40621d",
    "icao_type": "B77W",
    "type_name": "777-36N",
    "manufacturer": "Boeing",
    "manufacturer_and_model": "Boeing 777-36N",
    "owner_operator": "British Airways",
    "airline_code": "BAW",
    "is_private_operator": false,
    "serial_number": "38695",
    "year_built": "2013",
    "photos": [
      {
        "image": "https://image.airport-data.com/aircraft/001912010.jpg",
        "link": "https://airport-data.com/aircraft/photo/001912010.html",
        "photographer": "Roberto Cassar"
      }
    ]
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Статистика базы данных

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

Запрос

Query-параметры и параметры пути отсутствуют.

Ответ

{
  "loaded": true,
  "total_icao_entries": 612678,
  "total_registration_entries": 608905,
  "source_url": "https://api.skylinkapi.com/internal/aircraft.json"
}

curl -X GET "https://data.skylinkapi.com/v3.1/aircraft/database/stats"

{
  "loaded": true,
  "total_icao_entries": 615656,
  "total_registration_entries": 613252,
  "source_url": "http://10.0.1.15:8090/aircraft.json"
}

Клиентские типы

"""Aircraft lookup response models for /aircraft/registration and /aircraft/icao24."""from __future__ import annotationsfrom dataclasses import dataclass@dataclassclass AircraftPhoto:    image: str    link: str    photographer: str@dataclassclass AircraftDetails:    registration: str | None    icao24: str | None    icao_type: str | None    type_name: str | None    manufacturer: str | None    manufacturer_and_model: str | None    owner_operator: str | None    airline_code: str | None    is_private_operator: bool | None    serial_number: str | None    year_built: str | None    photos: list[AircraftPhoto]@dataclassclass AircraftLookupResponse:    query: str    found: bool    aircraft: AircraftDetails | None@dataclassclass AircraftDatabaseStats:    loaded: bool    total_icao_entries: int    total_registration_entries: int    source_url: str@dataclassclass AircraftSummary:    """Compact model for UI cards."""    registration: str | None    icao24: str | None    icao_type: str | None    display_name: str    operator: str | None    photo_url: str | None

Интеграция

Преобразуйте бортовой номер в компактную карточку воздушного судна для отслеживания рейсов или отображения флота.

В примере ниже успешные результаты поиска кэшируются на 24 часа, поскольку метаданные реестра меняются редко. Каждый запрос использует явные тайм-ауты (10 с на подключение / 15 с на чтение), чтобы медленный вышестоящий вызов не заблокировал ваш воркер. Вспомогательная функция приводит ответ к удобной для интерфейса модели и обрабатывает found: false, не считая это ошибкой HTTP.

import osimport timefrom dataclasses import dataclassimport requestsHEADERS = {    "x-api-key": os.getenv("SKYLINK_API_KEY", "YOUR_API_KEY")}BASE = "https://data.skylinkapi.com/v3.1"CACHE: dict[str, tuple[dict, float]] = {}AIRCRAFT_TTL = 86_400  # 24 h@dataclassclass AircraftSummary:    registration: str | None    icao24: str | None    icao_type: str | None    display_name: str    operator: str | None    photo_url: str | Nonedef fetch_aircraft_by_registration(registration: str, *, photos: bool = False) -> dict | None:    """Look up aircraft by tail number. Returns None when found=false."""    reg = registration.strip().upper()    key = f"aircraft:reg:{reg}:{photos}"    cached = CACHE.get(key)    if cached and time.time() < cached[1]:        return cached[0]    try:        r = requests.get(            f"{BASE}/aircraft/registration/{reg}",            headers=HEADERS,            params={"photos": photos},            timeout=(10, 15),        )    except requests.Timeout as exc:        raise RuntimeError(f"SkyLink timeout fetching aircraft {reg}") from exc    r.raise_for_status()    payload = r.json()    if not payload.get("found"):        return None    CACHE[key] = (payload, time.time() + AIRCRAFT_TTL)    return payloaddef aircraft_summary(registration: str) -> AircraftSummary | None:    payload = fetch_aircraft_by_registration(registration, photos=True)    if not payload:        return None    ac = payload["aircraft"]    photos = ac.get("photos") or []    return AircraftSummary(        registration=ac.get("registration"),        icao24=ac.get("icao24"),        icao_type=ac.get("icao_type"),        display_name=ac.get("type_name") or ac.get("manufacturer_and_model") or registration,        operator=ac.get("owner_operator"),        photo_url=photos[0]["image"] if photos else None,    )if __name__ == "__main__":    import json    from dataclasses import asdict    summary = aircraft_summary("N636JB")    print(json.dumps(asdict(summary), indent=2) if summary else "Aircraft not found")

Примечания по реализации

Переключатель фотографий. Значение по умолчанию photos=true удобно для галерей, но работает медленнее. Передавайте photos=false в списочных представлениях и задачах пакетного обогащения данных.

Переход к характеристикам. Если присутствует icao_type, вызовите Лётно-технические характеристики ВС, чтобы получить крейсерскую скорость, дальность и категорию турбулентности следа.

Обогащение данных ADS-B. Для треков в реальном времени предпочтительнее поиск по ICAO24 после получения hex-кодов из ADS-B.

Ответы с ошибками

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

200 — воздушное судно не найдено (регистрационный номер / ICAO24)

{
  "query": "ZZZZNOT",
  "found": false,
  "aircraft": null
}

Считайте found: false обычным пустым результатом — не повторяйте запрос.

422 — недопустимый регистрационный номер или ICAO24

{
  "detail": [
    {
      "type": "string_too_short",
      "loc": ["path", "registration"],
      "msg": "String should have at least 2 characters"
    }
  ]
}

Возникает, если параметр пути слишком короткий или не проходит валидацию.

См. также: Лётно-технические характеристики ВС · ADS-B · История позиций ADS-B