# Поиск воздушных судов
Поиск ВС по бортовому номеру или hex-адресу ICAO24: тип, оператор, серийный номер и фото от сообщества из реестра более 600 000 записей.
Получайте тип воздушного судна, оператора и фотографии по **регистрационному номеру** (национальный регистрационный идентификатор ВС, например `G-STBC`, `N12345`) или по **[ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address)** (6-символьный шестнадцатеричный адрес транспондера, передаваемый в [ADS-B](https://www.faa.gov/air_traffic/technology/adsb), например `40621D`). Реестр воздушных судов SkyLink содержит более 615 000 записей и обновляется ежедневно — новые регистрации и смены владельцев могут появляться с задержкой относительно официальных реестров авиационных властей.
Используйте поиск по регистрационному номеру, когда в вашем интерфейсе или строке расписания уже есть бортовой номер. Используйте поиск по [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address), когда вы получаете hex-коды из потока [ADS-B](/docs/v31/adsb) в реальном времени и хотите дополнить их метаданными о типе и операторе. Получив `icao_type` (4-символьный код типа ВС, используемый в планах полётов, например `B738`), переходите к эндпоинту [Лётно-технические характеристики ВС](/docs/v31/aircraft-performance) за крейсерской скоростью, дальностью и категорией турбулентности следа.
| Эндпоинт | Когда использовать |
| ------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `GET /aircraft/registration/{registration}` | Поиск по бортовому номеру для карточек рейсов, страниц флота или фотогалерей |
| `GET /aircraft/icao24/{icao24}` | Дополнение hex-адресов ADS-B из потоков трекеров в реальном времени |
| `GET /aircraft/database/stats` | Проверка работоспособности — убедиться, что реестр загружен, и посмотреть количество записей |
**Важно:** поиск по регистрационному номеру и по [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address) при отсутствии совпадения возвращает HTTP **200** с `found: false` и `aircraft: null` — никогда не 404. Проверяйте поле `found` в теле JSON; не считайте такой ответ ошибкой HTTP.
**Важно:** по умолчанию `photos` равен `true` для удобства, но это увеличивает задержку. Передавайте `photos=false` в списочных представлениях, задачах пакетного обогащения данных и слоях карты, где миниатюры не нужны.
Регистрационный номер
[ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address)
Статистика базы
## Поиск по регистрационному номеру [#lookup-by-registration]
Поиск воздушного судна по регистрационному (бортовому) номеру. В v3.1 в объект воздушного судна добавлены поля `manufacturer_and_model`, `airline_code`, `serial_number` и `is_private_operator`.
### Запрос [#request]
| Параметр | Тип | Обязательный | По умолчанию | Описание |
| -------------- | ------- | ------------ | ------------ | ----------------------------------------------------------------- |
| `registration` | string | Да (путь) | - | Бортовой номер, например `G-STBC`, `N12345` (от 2 до 10 символов) |
| `photos` | boolean | Нет | `true` | Включать фотографии ВС от сообщества, если они есть |
### Ответ [#response]
```json
{
"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"
}
]
}
}
```
| Поле | Тип | Обязательный | Может быть null? | Описание |
| ---------- | -------------- | ------------ | ---------------- | -------------------------------------------------------------------- |
| `query` | string | **Да** | Никогда | Искомый регистрационный номер (эхо запроса) |
| `found` | boolean | **Да** | Никогда | Найдено ли совпадение в реестре |
| `aircraft` | object \| null | Нет | **Да** | Данные ВС, если `found` равно `true`; `null`, если ничего не найдено |
#### Объект воздушного судна (`aircraft`) [#aircraft-object-aircraft]
| Поле | Тип | Обязательный | Может быть null? | Описание |
| ------------------------ | --------------- | ------------ | ---------------- | ------------------------------------------------------------------------------------ |
| `registration` | string \| null | Нет | **Да** | Бортовой номер |
| `icao24` | string \| null | Нет | **Да** | 24-битный шестнадцатеричный адрес транспондера ICAO (на практике в верхнем регистре) |
| `icao_type` | string \| null | Нет | **Да** | Обозначение типа ВС по ICAO, например `B77W` |
| `type_name` | string \| null | Нет | **Да** | Название модели, например `BOEING 777-36NER` |
| `manufacturer` | string \| null | Нет | **Да** | Название производителя |
| `manufacturer_and_model` | string \| null | Нет | **Да** | Объединённая строка «производитель + модель» |
| `owner_operator` | string \| null | Нет | **Да** | Зарегистрированный владелец или оператор |
| `airline_code` | string \| null | Нет | **Да** | Код авиакомпании-оператора, если известен |
| `is_private_operator` | boolean \| null | Нет | **Да** | `true` для частных операторов |
| `serial_number` | string \| null | Нет | **Да** | Серийный номер производителя |
| `year_built` | string \| null | Нет | **Да** | Год выпуска |
| `photos` | array | Нет | Никогда | Присутствует при `photos=true`; может быть `[]`, если фотографий нет |
#### Элемент фотографии (`aircraft.photos[]`) [#photo-item-aircraftphotos]
| Поле | Тип | Обязательный | Описание |
| -------------- | ------ | ------------ | -------------------------------------------- |
| `image` | string | **Да** | URL полноразмерной фотографии |
| `link` | string | **Да** | URL внешней страницы фотографии, если указан |
| `photographer` | string | **Да** | Автор фотографии |
## Поиск по ICAO24 [#lookup-by-icao24]
Поиск воздушного судна по шестнадцатеричному адресу транспондера [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address) — тому же идентификатору, который передаётся в [ADS-B](https://www.faa.gov/air_traffic/technology/adsb) (например, `40621D`). Возвращает объект `aircraft` той же структуры, что и поиск по регистрационному номеру.
### Запрос [#request-1]
| Параметр | Тип | Обязательный | По умолчанию | Описание |
| -------- | ------- | ------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `icao24` | string | Да (путь) | - | 6-символьный шестнадцатеричный 24-битный адрес ICAO (без учёта регистра), например `40621D`. Дополняйте его ведущими нулями, если ваш источник ADS-B их опускает |
| `photos` | boolean | Нет | `true` | Включать фотографии ВС от сообщества, если они есть |
### Ответ [#response-1]
Та же структура ответа, что и при [поиске по регистрационному номеру](#lookup-by-registration). Поле `query` повторяет адрес [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address).
## Статистика базы данных [#database-statistics]
Возвращает количество записей и статус загрузки реестра воздушных судов, хранящегося в памяти. Параметры не требуются — эндпоинт удобен для проверок работоспособности при запуске и дашбордов мониторинга.
### Запрос [#request-2]
Query-параметры и параметры пути отсутствуют.
### Ответ [#response-2]
```json
{
"loaded": true,
"total_icao_entries": 612678,
"total_registration_entries": 608905,
"source_url": "https://api.skylinkapi.com/internal/aircraft.json"
}
```
| Поле | Тип | Обязательный | Описание |
| ---------------------------- | ------- | ------------ | -------------------------------------------------------- |
| `loaded` | boolean | **Да** | Завершена ли загрузка реестра |
| `total_icao_entries` | integer | **Да** | Количество записей с индексом по ICAO24 |
| `total_registration_entries` | integer | **Да** | Количество записей с индексом по регистрационному номеру |
| `source_url` | string | **Да** | Непрозрачная ссылка на набор данных, возвращаемая API |
## Клиентские типы [#client-types]
## Интеграция [#integration]
Преобразуйте бортовой номер в компактную карточку воздушного судна для отслеживания рейсов или отображения флота.
В примере ниже успешные результаты поиска кэшируются на 24 часа, поскольку метаданные реестра меняются редко. Каждый запрос использует явные тайм-ауты (10 с на подключение / 15 с на чтение), чтобы медленный вышестоящий вызов не заблокировал ваш воркер. Вспомогательная функция приводит ответ к удобной для интерфейса модели и обрабатывает `found: false`, не считая это ошибкой HTTP.
### Примечания по реализации [#implementation-notes]
**Переключатель фотографий.** Значение по умолчанию `photos=true` удобно для галерей, но работает медленнее. Передавайте `photos=false` в списочных представлениях и задачах пакетного обогащения данных.
**Переход к характеристикам.** Если присутствует `icao_type`, вызовите [Лётно-технические характеристики ВС](/docs/v31/aircraft-performance), чтобы получить крейсерскую скорость, дальность и категорию турбулентности следа.
**Обогащение данных [ADS-B](https://www.faa.gov/air_traffic/technology/adsb).** Для треков в реальном времени предпочтительнее поиск по [ICAO24](https://en.wikipedia.org/wiki/ICAO_24-bit_address) после получения hex-кодов из [ADS-B](/docs/v31/adsb).
## Ответы с ошибками [#error-responses]
Общие ошибки платформы (авторизация, ограничения частоты запросов, ошибки сервера) описаны в разделе [Обработка ошибок](/docs/errors). Поведение, специфичное для эндпоинта:
### 200 — воздушное судно не найдено (регистрационный номер / ICAO24) [#200--aircraft-not-found-registration--icao24]
```json
{
"query": "ZZZZNOT",
"found": false,
"aircraft": null
}
```
Считайте `found: false` обычным пустым результатом — не повторяйте запрос.
### 422 — недопустимый регистрационный номер или ICAO24 [#422--invalid-registration-or-icao24]
```json
{
"detail": [
{
"type": "string_too_short",
"loc": ["path", "registration"],
"msg": "String should have at least 2 characters"
}
]
}
```
Возникает, если параметр пути слишком короткий или не проходит валидацию.
***
См. также: [Лётно-технические характеристики ВС](/docs/v31/aircraft-performance) · [ADS-B](/docs/v31/adsb) · [История позиций ADS-B](/docs/v31/historical-adsb-positions)