# Задержки FAA

Задержки FAA NAS в реальном времени: программы наземных задержек, запреты вылетов, закрытия и программы управления потоками для аэропортов США.



Получайте активные программы задержек Национальной системы воздушного пространства FAA ([**NAS**](https://www.faa.gov/about/office_org/headquarters_offices/ato/service_units/operations/at_delay_info) — гражданское воздушное пространство США) для аэропортов США и территорий США. Используйте общенациональный поток данных для операционных дашбордов, а поток по отдельному аэропорту — для дополнения табло вылетов, оповещений экипажей и уведомлений пассажиров.

Категории задержек:

| Код         | Название                                                                       | Описание                                                                             |
| ----------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| **GDP**     | Программа наземных задержек (Ground Delay Program)                             | Дозирование прилётов на объект — включает строки со средней и максимальной задержкой |
| **GS**      | Запрет вылетов (Ground Stop)                                                   | Задержка вылетов в направлении конкретного объекта                                   |
| **Closure** | Закрытие аэропорта/программы                                                   | Объект закрыт или работает с ограничениями                                           |
| **AFP**     | Программа управления потоками в воздушном пространстве (Airspace Flow Program) | Перенаправление трафика на уровне ARTCC                                              |

Покрытие ограничено аэропортами под юрисдикцией FAA — континентальная часть США, Аляска, Гавайи, Пуэрто-Рико, Виргинские Острова США, Гуам и другие тихоокеанские территории США. Для контекста задержек за пределами США комбинируйте эти данные со [Статусом рейса](/docs/v31/flight-status) и операционными данными авиакомпаний.

**Важно:** массивы в ответе присутствуют всегда, но могут быть пустыми — `total_alerts: 0` со строкой `message` является корректным ответом «нет активных программ», а не ошибкой. Не кэшируйте дольше **2–5 минут** — программы GDP и GS меняются практически без предупреждения.

| Эндпоинт                 | Когда использовать                                                   |
| ------------------------ | -------------------------------------------------------------------- |
| `GET /delays/faa`        | Операционная карта — все активные оповещения GDP, GS, закрытия и AFP |
| `GET /delays/faa/{icao}` | Сведения по аэропорту — задержки, затрагивающие один аэропорт США    |

<DocJumpNav>
  <DocJumpLink href="#all-current-faa-delays" icon="solar:earth-bold-duotone">
    По всей стране
  </DocJumpLink>

  <DocJumpLink href="#delays-for-a-specific-airport" icon="solar:map-point-bold-duotone">
    По аэропорту
  </DocJumpLink>
</DocJumpNav>

## Все текущие задержки FAA [#all-current-faa-delays]

Возвращает все активные задержки [FAA NAS](https://www.faa.gov/about/office_org/headquarters_offices/ato/service_units/operations/at_delay_info) по всей стране.

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

<DocRequirements>
  <DocRequirementAuth />
</DocRequirements>

<DocApiPath method="GET" path="/delays/faa" />

Query-параметров нет. Возвращает текущие программы задержек FAA; данные обновляются при каждом запросе.

### Ответ [#response]

```json
{
  "ground_delays": [
    {
      "airport": "KSFO",
      "airport_name": null,
      "reason": "low ceilings",
      "avg_delay": "34 minutes",
      "max_delay": "1 hour and 25 minutes"
    }
  ],
  "ground_stops": [],
  "closures": [
    {
      "airport": "KJFK",
      "airport_name": null,
      "reason": "!JFK 06/158 JFK AD AP CLSD TO TRANSIENT GA ACFT EXC 24HR PPR ...",
      "begin": "Jun 11 at 16:30 UTC.",
      "reopen": "Jul 22 at 03:59 UTC."
    }
  ],
  "airspace_flow_programs": [],
  "total_alerts": 8,
  "message": null
}
```

| Поле                     | Тип     | Обязательный | Допускает null | Описание                                       |
| ------------------------ | ------- | ------------ | -------------- | ---------------------------------------------- |
| `ground_delays`          | array   | **Да**       | Никогда        | Активные записи GDP                            |
| `ground_stops`           | array   | **Да**       | Никогда        | Активные запреты вылетов                       |
| `closures`               | array   | **Да**       | Никогда        | Закрытия аэропортов/программ                   |
| `airspace_flow_programs` | array   | **Да**       | Никогда        | Программы управления потоками ARTCC            |
| `total_alerts`           | integer | Нет          | Никогда        | Сумма всех строк оповещений (по умолчанию `0`) |
| `message`                | string  | Нет          | **Да**         | Текст статуса, когда активных задержек нет     |

#### Наземная задержка (`ground_delays[]`) [#ground-delay-ground_delays]

| Поле           | Тип    | Обязательный | Допускает null | Описание                                                  |
| -------------- | ------ | ------------ | -------------- | --------------------------------------------------------- |
| `airport`      | string | **Да**       | Никогда        | Идентификатор аэропорта ICAO или FAA                      |
| `airport_name` | string | Нет          | **Да**         | Название аэропорта, если указано                          |
| `reason`       | string | **Да**       | Никогда        | Причина задержки (часто погода или объём трафика)         |
| `avg_delay`    | string | Нет          | **Да**         | Средняя продолжительность задержки (в удобочитаемом виде) |
| `max_delay`    | string | Нет          | **Да**         | Максимальная продолжительность задержки                   |

#### Запрет вылетов (`ground_stops[]`) [#ground-stop-ground_stops]

| Поле           | Тип    | Обязательный | Допускает null | Описание                          |
| -------------- | ------ | ------------ | -------------- | --------------------------------- |
| `airport`      | string | **Да**       | Никогда        | Затронутый аэропорт               |
| `airport_name` | string | Нет          | **Да**         | Название аэропорта, если доступно |
| `reason`       | string | **Да**       | Никогда        | Причина запрета                   |
| `end_time`     | string | Нет          | **Да**         | Ожидаемое время окончания (UTC)   |

#### Закрытие (`closures[]`) [#closure-closures]

| Поле           | Тип    | Обязательный | Допускает null | Описание                                      |
| -------------- | ------ | ------------ | -------------- | --------------------------------------------- |
| `airport`      | string | **Да**       | Никогда        | Затронутый аэропорт                           |
| `airport_name` | string | Нет          | **Да**         | Название аэропорта, если доступно             |
| `reason`       | string | **Да**       | Никогда        | Причина закрытия (часто включает текст NOTAM) |
| `begin`        | string | Нет          | **Да**         | Начало закрытия (UTC, в удобочитаемом виде)   |
| `reopen`       | string | Нет          | **Да**         | Ожидаемое время открытия                      |

#### Программа управления потоками в воздушном пространстве (`airspace_flow_programs[]`) [#airspace-flow-program-airspace_flow_programs]

| Поле        | Тип    | Обязательный | Допускает null | Описание                                                                                |
| ----------- | ------ | ------------ | -------------- | --------------------------------------------------------------------------------------- |
| `facility`  | string | **Да**       | Никогда        | Идентификатор органа УВД (**ARTCC** — районный диспетчерский центр), а не код аэропорта |
| `reason`    | string | **Да**       | Никогда        | Причина программы                                                                       |
| `fca_start` | string | Нет          | **Да**         | Начало зоны ограничения потока (FCA)                                                    |
| `fca_end`   | string | Нет          | **Да**         | Конец зоны ограничения потока (FCA)                                                     |

**Важно:** программы управления потоками используют `facility` (ARTCC), а не код аэропорта — чётко подписывайте их в интерфейсе, чтобы пользователи не путали строки AFP с задержками конкретного аэропорта.

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

## Задержки для конкретного аэропорта [#delays-for-a-specific-airport]

Возвращает активные [задержки FAA](https://www.faa.gov/about/office_org/headquarters_offices/ato/service_units/operations/at_delay_info), отфильтрованные по конкретному аэропорту США по коду ICAO. Программы управления потоками (уровня ARTCC) включаются полностью, поскольку они могут косвенно влиять на запрошенный аэропорт.

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

<DocRequirements>
  <DocRequirementAuth />
</DocRequirements>

<DocApiPath method="GET" path="/delays/faa/{icao}" />

| Параметр | Тип    | Обязательный | Описание                                              |
| -------- | ------ | ------------ | ----------------------------------------------------- |
| `icao`   | string | Да           | 4-буквенный код ICAO аэропорта США (например, `KJFK`) |

### Ответ [#response-1]

Та же структура, что и в разделе [Все текущие задержки FAA](#all-current-faa-delays), но массивы отфильтрованы по запрошенному аэропорту (плюс соответствующие строки AFP).

```json
{
  "ground_delays": [],
  "ground_stops": [],
  "closures": [
    {
      "airport": "KJFK",
      "airport_name": null,
      "reason": "!JFK 06/158 JFK AD AP CLSD TO TRANSIENT GA ACFT EXC 24HR PPR ...",
      "begin": "Jun 11 at 16:30 UTC.",
      "reopen": "Jul 22 at 03:59 UTC."
    }
  ],
  "airspace_flow_programs": [],
  "total_alerts": 1,
  "message": null
}
```

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

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

<DocClientTypes id="v31/faa-delays/delays-types" />

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

Опрашивайте [задержки FAA](https://www.faa.gov/about/office_org/headquarters_offices/ato/service_units/operations/at_delay_info) по аэропорту и сводите их в единый список оповещений для табло вылетов.

Пример ниже кэширует ответы на 2 минуты, потому что во время погодных явлений программы задержек меняются часто. Каждый запрос использует явные тайм-ауты (10 с на подключение / 20 с на чтение). Вспомогательная функция объединяет строки GDP, GS, закрытий и AFP в единый список `DelayAlert` для отрисовки бейджей.

<DocExample id="v31/faa-delays/delays-fetch" />

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

**Продолжительность в удобочитаемом виде.** `avg_delay` и `max_delay` — строки (например, `"34 minutes"`): разбирайте их с осторожностью или показывайте как есть.

**Пустые ответы.** `total_alerts: 0` с заполненным `message` может означать, что активных программ по стране нет, — показывайте пустое состояние, а не баннер с ошибкой.

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

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

### 422 — некорректная длина кода ICAO [#422--invalid-icao-length]

```json
{
  "detail": [
    {
      "type": "string_too_short",
      "loc": ["path", "icao"],
      "msg": "String should have at least 4 characters"
    }
  ]
}
```

### Руководства по интеграции [#integration-guides]

| Руководство                                                         | Содержание                                                  |
| ------------------------------------------------------------------- | ----------------------------------------------------------- |
| [NOTAM](/docs/v31/notams-integration)                               | Сводная таблица, фильтр по аэродрому, предполётная проверка |
| [Задержки FAA](/docs/v31/faa-delays-integration)                    | Сканирование по всей стране, дашборд хаба                   |
| [Обработка ошибок](/docs/v31/alerts-integration-errors)             | Пустые массивы, покрытие только США                         |
| [Кэширование и мониторинг](/docs/v31/alerts-integration-production) | TTL: 5 мин для NOTAM / 2 мин для FAA                        |

***

См. также: [NOTAM](/docs/v31/notams) · [Статус рейса](/docs/v31/flight-status) · [Расписания](/docs/v31/schedules)