# Расписания

API расписаний вылетов и прилётов аэропорта за прошедшие дни и ближайшее будущее — со строками, удобными для табло рейсов.



Расписания вылетов и прилётов аэропорта за заданный интервал времени. Обе операции возвращают строки рейсов одинаковой структуры с полем-дискриминатором `direction` (`departures` или `arrivals`). По умолчанию API возвращает предстоящие рейсы примерно на ближайшие 12 часов и может незаметно для вас подгружать дополнительные страницы.

Подходит для табло аэропортов, диспетчерских дашбордов и пакетных ETL-процессов. Передавайте ровно один идентификатор аэропорта (`icao` или `iata`) в каждом запросе.

**Важно:** ключи строк рейсов пишутся **с заглавной буквы** — `Time`, `Flight`, `Status`, а не `time`, `flight`, `status`. Обращение к ключам в нижнем регистре вернёт `undefined`.

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

<DocRequirements>
  <DocRequirementAuth />
</DocRequirements>

**Вылеты**

<DocApiPath method="GET" path="/schedules/departures" />

**Прилёты**

<DocApiPath method="GET" path="/schedules/arrivals" />

| Параметр | Тип     | Обязательный            | По умолчанию  | Описание                                                                            |
| -------- | ------- | ----------------------- | ------------- | ----------------------------------------------------------------------------------- |
| `icao`   | string  | Один из `icao` / `iata` | -             | 4-буквенный код аэропорта ICAO, например `KJFK`, `EGLL`                             |
| `iata`   | string  | Один из `icao` / `iata` | -             | 3-буквенный код аэропорта IATA, например `JFK`, `LHR`                               |
| `date`   | string  | Нет                     | текущая дата  | Дата в формате `DD-MM-YYYY`. Диапазон: от 5 дней назад до 1 дня вперёд              |
| `time`   | string  | Нет                     | текущее время | Время в формате `HH:MM`. Если указано, требуется также `date`                       |
| `ts`     | integer | Нет                     | -             | Метка времени Unix в **миллисекундах**. Если задана, переопределяет `date` и `time` |

Для программного опроса предпочтительнее `ts` — так вы избежите ошибок форматирования, связанных с локалью и часовыми поясами, в cron-задачах и бессерверных воркерах.

## Ответ [#response]

Обе операции используют одинаковую обёртку ответа. Поле `direction` соответствует вызванной операции.

### Пример вылетов [#departures-example]

```json
{
  "iata": "MXP",
  "direction": "departures",
  "airport_code": "LIMC",
  "flights": [
    {
      "Time": "16:05",
      "Date": "11 Feb",
      "IATA": "ICN",
      "Destination": "Seoul",
      "Flight": "C84093",
      "Airline": "Federal Airlines",
      "Status": "Estimated 16:39"
    }
  ],
  "total_flights": 85,
  "pages_fetched": 3
}
```

### Пример прилётов [#arrivals-example]

```json
{
  "iata": "MXP",
  "direction": "arrivals",
  "airport_code": "LIMC",
  "flights": [
    {
      "Time": "16:20",
      "Date": "11 Feb",
      "IATA": "RAK",
      "Origin": "Marrakech",
      "Flight": "EC3929",
      "Airline": "easyJet Europe",
      "Status": "Landed 16:15"
    }
  ],
  "total_flights": 72,
  "pages_fetched": 3
}
```

### Поля обёртки ответа [#envelope-fields]

| Поле            | Тип     | Обязательный | Описание                                                                         |
| --------------- | ------- | ------------ | -------------------------------------------------------------------------------- |
| `iata`          | string  | **Да**       | IATA-код запрошенного аэропорта, если известен                                   |
| `direction`     | string  | **Да**       | `departures` или `arrivals`                                                      |
| `airport_code`  | string  | **Да**       | Эхо вашего запроса — ICAO, если вы передали `icao`, и IATA, если передали `iata` |
| `flights`       | array   | **Да**       | Строки расписания (может быть пустым)                                            |
| `total_flights` | integer | **Да**       | Общее число рейсов в запрошенном интервале                                       |
| `pages_fetched` | integer | **Да**       | Число страниц, загруженных в фоновом режиме                                      |

### Объект строки рейса (`flights[]`) [#flight-row-object-flights]

Путь в JSON: `flights[]`. Имена ключей пишутся с заглавной буквы.

| Поле          | Тип    | Обязательный        | Описание                                                                       |
| ------------- | ------ | ------------------- | ------------------------------------------------------------------------------ |
| `Time`        | string | **Да**              | Местное время по расписанию                                                    |
| `Date`        | string | **Да**              | Метка местной даты, например `11 Feb`                                          |
| `IATA`        | string | **Да**              | IATA-код аэропорта на другом конце маршрута                                    |
| `Destination` | string | Только для вылетов  | Город/аэропорт назначения                                                      |
| `Origin`      | string | Только для прилётов | Город/аэропорт отправления                                                     |
| `Flight`      | string | **Да**              | Номер рейса в том виде, в каком он отображается на табло                       |
| `Airline`     | string | **Да**              | Отображаемое название авиакомпании                                             |
| `Status`      | string | **Да**              | Статус в свободной текстовой форме, например `Estimated 16:39`, `Landed 16:15` |

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

<DocClientTypes id="v31/schedules/schedules-types" />

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

Получите вылеты и приведите ключи с заглавной буквы к плоской структуре элемента табло.

Пример ниже требует ровно один из параметров `icao` или `iata` (исключающее ИЛИ), использует запросы с тайм-аутами для пакетного опроса и сопоставляет строки со стабильными внутренними ключами.

<DocExample id="v31/schedules/schedules-fetch" />

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

**Разбор статуса.** `Status` — это отображаемый текст из источника расписаний. Если вам нужны структурированные состояния, разбирайте его осторожно.

**Пагинация.** Начинайте с интервала по умолчанию; более длинные интервалы вперёд увеличивают задержку.

**Подробности по одному рейсу.** Чтобы узнать выход на посадку и терминал для конкретного рейса, используйте [Статус рейса](/docs/v31/flight-status).

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

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

### 422 - недопустимые дата/время или отсутствует код аэропорта [#422---invalid-datetime-or-missing-airport-code]

```json
{
  "detail": [
    {
      "type": "value_error",
      "loc": ["query", "date"],
      "msg": "Invalid date format. Expected DD-MM-YYYY."
    }
  ]
}
```

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

***

См. также: [Статус рейса](/docs/v31/flight-status) · [Аэропорты](/docs/v31/airports) · [Авиакомпании](/docs/v31/airlines)