# Оценка времени полёта с помощью ML

ML-прогнозы времени полёта gate-to-gate между аэропортами: необязательный тип ВС, расстояние и границы оценки min/max.



Время полёта от выхода до выхода (gate-to-gate) между любыми двумя аэропортами, прогнозируемое моделью GradientBoosting, обученной на исторических эксплуатационных данных (R² ≈ 0.98). **Блочное время** — это плановая продолжительность от выхода до выхода (gate-to-gate), включая руление в обоих аэропортах.

Используйте этот эндпоинт, когда вам нужны оценки блочного времени для составления расписаний, буферов на стыковки или панелей оценки риска задержек — без поддержки собственных статистических таблиц по маршрутам.

Передайте аэропорты вылета и назначения кодами ICAO или IATA. Для более точной оценки передайте необязательный код типа воздушного судна ICAO (`B738`, `A320`, `B77W`); если он не указан, модель использует типичные крейсерские параметры реактивного самолёта для данной пары городов. API возвращает точечную оценку, минимальную и максимальную границы и удобочитаемую строку продолжительности.

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

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

<DocRequirements>
  <DocRequirementAuth />
</DocRequirements>

<DocApiPath method="GET" path="/ml/flight-time" />

| Параметр   | Тип    | Обязательный | По умолчанию                 | Описание                                                                 |
| ---------- | ------ | ------------ | ---------------------------- | ------------------------------------------------------------------------ |
| `from`     | string | Да           | -                            | Код ICAO или IATA аэропорта вылета (3–4 символа), например `KSFO`, `SFO` |
| `to`       | string | Да           | -                            | Код ICAO или IATA аэропорта назначения, например `KJFK`, `JFK`           |
| `aircraft` | string | Нет          | значение модели по умолчанию | Код типа воздушного судна ICAO, например `B738`, `A320`, `C172`          |

## Ответ [#response]

```json
{
  "origin": "KSFO",
  "destination": "KJFK",
  "aircraft_type": "B738",
  "distance_nm": 2241.75,
  "estimated_minutes": 294,
  "estimated_hours_display": "4h 54m",
  "min_minutes": 259,
  "max_minutes": 329,
  "model_version": "2.0.0-wind"
}
```

### Объект прогноза [#prediction-object]

| Поле                      | Тип            | Обязательный | Может быть null? | Описание                                                                                 |
| ------------------------- | -------------- | ------------ | ---------------- | ---------------------------------------------------------------------------------------- |
| `origin`                  | string         | **Да**       | Никогда          | Итоговый код ICAO аэропорта вылета                                                       |
| `destination`             | string         | **Да**       | Никогда          | Итоговый код ICAO аэропорта назначения                                                   |
| `aircraft_type`           | string \| null | Нет          | **Да**           | Тип воздушного судна, использованный для прогноза, или `null`, если не указан            |
| `distance_nm`             | number         | **Да**       | Никогда          | Расстояние по ортодромии в морских милях                                                 |
| `estimated_minutes`       | integer        | **Да**       | Никогда          | Оценка от выхода до выхода в минутах (включает среднее время руления в обоих аэропортах) |
| `estimated_hours_display` | string         | **Да**       | Никогда          | Удобочитаемая продолжительность, например `"4h 54m"`                                     |
| `min_minutes`             | integer        | **Да**       | Никогда          | Нижняя граница диапазона оценки                                                          |
| `max_minutes`             | integer        | **Да**       | Никогда          | Верхняя граница диапазона оценки                                                         |
| `model_version`           | string         | **Да**       | Никогда          | Строка версии артефакта модели                                                           |

**Важно:** используйте `estimated_minutes` для расчётов, а `estimated_hours_display` — для подписей, которые видят пассажиры. Показывайте `min_minutes`–`max_minutes` как диапазон, когда нужны интервалы неопределённости (планирование стыковок, буферы SLA).

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

<DocClientTypes id="v31/flight-time/prediction-types" />

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

Планировщики маршрутов обычно кэшируют результаты ML-оценки времени полёта для каждой пары городов, поскольку базовая модель меняется нечасто. Пример ниже получает прогноз, преобразует его в компактную модель представления (`block_minutes`, `display`, `range`) и использует явные таймауты подключения и чтения, чтобы медленный вызов инференса не мог заблокировать ваш воркер.

<DocExample id="v31/flight-time/prediction-fetch" />

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

**Тип воздушного судна.** Коды узкофюзеляжных (`B738`, `A320`) и широкофюзеляжных (`B77W`, `A359`) самолётов существенно влияют на блочное время на длинных маршрутах — передавайте `aircraft`, если в строке вашего расписания уже известен тип ВС.

**Границы и точечная оценка.** `min_minutes` и `max_minutes` охватывают типичный эксплуатационный разброс. Не рассматривайте их как жёсткие эксплуатационные ограничения.

**Важно:** если ML-модель временно недоступна, SkyLink может переключиться на расчёт по расстоянию и скорости. Проверяйте `model_version` при аудите прогнозов для ESG-отчётности или процессов планирования расписаний.

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

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

### 422 — недопустимый код аэропорта [#422--invalid-airport-code]

Возвращается, когда `from` или `to` не удаётся сопоставить с известным аэропортом или когда query-параметры не проходят валидацию.

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