# TAF Прогнозы по аэродрому (TAF) для любого аэропорта ICAO. Опциональный декодированный вывод: периоды прогноза и ожидаемая категория полётных условий. [TAF (прогнозы по аэродрому)](https://en.wikipedia.org/wiki/Terminal_aerodrome_forecast) — это структурированные прогнозы для конкретного аэропорта и его ближайших окрестностей, обычно охватывающие примерно пять морских миль вокруг аэродрома. Стандартные [TAF](https://en.wikipedia.org/wiki/Terminal_aerodrome_forecast) выпускаются четыре раза в сутки — в 00Z, 06Z, 12Z и 18Z — и действуют 24 или 30 часов в зависимости от станции. Каждый [TAF](https://en.wikipedia.org/wiki/Terminal_aerodrome_forecast) описывает ожидаемые ветер, видимость, слои облачности, погодные явления и категории полётных условий в рамках прогнозных групп с привязкой ко времени, таких как FROM, TEMPO и BECMG. Пилоты, диспетчеры по обеспечению полётов и специалисты по планированию полётов используют эти прогнозы, чтобы оценить ожидаемые условия в аэропортах вылета, назначения и запасных при составлении оперативных планов. Многие небольшие аэропорты публикуют только [METAR](https://en.wikipedia.org/wiki/METAR) — ответ `404` для [TAF](https://en.wikipedia.org/wiki/Terminal_aerodrome_forecast) встречается часто и не означает, что аэропорт неизвестен. ## Запрос [#request] Отправьте запрос GET с кодом ICAO аэропорта в пути. Необязательные query-флаги управляют декодированием. | Параметр | Тип | Обязательный | По умолчанию | Описание | | -------- | ------- | ------------ | ------------ | --------------------------------------------------------------------------------------------- | | `icao` | string | Да | - | Четырёхбуквенный код ICAO — [поиск](/docs/v31/airport-search#search-by-text), например `KJFK` | | `parsed` | boolean | Нет | `false` | Добавить декодированные периоды прогноза под ключом `parsed` | ## Ответ [#response] ### Исходный ответ (по умолчанию) [#raw-default] ```json { "raw": "TAF KJFK 072334Z 0800/0906 35014G20KT P6SM FEW050 SCT100 FM080600 03011KT P6SM SCT025 ...", "icao": "KJFK", "airport_name": "John F. Kennedy International Airport", "timestamp": "2026-06-08T23:45:12Z" } ``` | Поле | Тип | Обязательный | Описание | | -------------- | ----------------- | ------------ | ------------------------------------------------------ | | `raw` | string | **Да** | Полная строка TAF в исходном виде | | `icao` | string | **Да** | Код ICAO | | `airport_name` | string | **Да** | Название аэропорта | | `timestamp` | string (ISO 8601) | **Да** | Время получения данных API — не время выпуска прогноза | ### Декодированный ответ (`parsed=true`) [#parsed-parsedtrue] ```json { "raw": "TAF KJFK 061933Z 0620/0724 ...", "icao": "KJFK", "airport_name": "John F. Kennedy International Airport", "timestamp": "2026-06-06T23:09:48Z", "parsed": { "start_time": "2026-06-06T22:00:00+02:00", "end_time": "2026-06-08T02:00:00+02:00", "forecast": [ { "type": "FROM", "start_time": "2026-06-06T22:00:00+02:00", "end_time": "2026-06-07T01:00:00+02:00", "wind": { "direction": 200, "speed": 14, "gust": null, "variable": [] }, "visibility": { "value": null, "repr": "P6" }, "clouds": [ { "type": "SCT", "base": 70, "repr": "SCT070" }, { "type": "BKN", "base": 250, "repr": "BKN250" } ], "wx_codes": [], "flight_rules": "VFR", "probability": null, "turbulence": [], "icing": [] }, { "type": "TEMPO", "start_time": "2026-06-07T01:00:00+02:00", "end_time": "2026-06-07T05:00:00+02:00", "wind": { "direction": 290, "speed": 25, "gust": 45, "variable": [] }, "visibility": { "value": 3, "repr": "3" }, "clouds": [ { "type": "SCT", "base": 25, "repr": "SCT025" }, { "type": "BKN", "base": 50, "repr": "BKN050CB" } ], "wx_codes": [ { "repr": "TSRA", "value": "Thunderstorm Rain" }, { "repr": "BR", "value": "Mist" } ], "flight_rules": "MVFR", "probability": null, "turbulence": [], "icing": [] } ] } } ``` | Поле | Тип | Обязательный | Описание | | -------------------------------- | ----------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------ | | `parsed` | object | **Да** (при `parsed=true`) | Отсутствует при `parsed=false` — не `null` | | `parsed.start_time` | string (ISO 8601) | **Да** | Начало периода действия TAF (`DDHH/DDHH` в исходной строке) | | `parsed.end_time` | string (ISO 8601) | **Да** | Конец периода действия TAF | | `parsed.forecast` | array | **Да** | Периоды прогноза в хронологическом порядке — см. [Типы периодов прогноза](#forecast-period-types) | | `parsed.forecast[].type` | string | **Да** (для каждого элемента) | `FROM`, `TEMPO` или `BECMG` | | `parsed.forecast[].start_time` | string (ISO 8601) | **Да** (для каждого элемента) | Когда эта группа начинает действовать | | `parsed.forecast[].end_time` | string (ISO 8601) | **Да** (для каждого элемента) | Когда эта группа заканчивается | | `parsed.forecast[].wind` | object | **Да** (для каждого элемента) | Та же структура, что у [METAR `parsed.wind`](/docs/v31/weather-metar#object-schemas-and-nullability) | | `parsed.forecast[].visibility` | object | **Да** (для каждого элемента) | Та же структура, что у METAR `parsed.visibility` | | `parsed.forecast[].clouds` | array | **Да** (для каждого элемента) | Та же структура, что у METAR `parsed.clouds`, — [коды облачности](/docs/v31/weather#cloud-cover-codes) | | `parsed.forecast[].wx_codes` | array | **Да** (для каждого элемента) | Ожидаемые погодные явления — `{ repr, value }[]` | | `parsed.forecast[].flight_rules` | string | **Да** (для каждого элемента) | Ожидаемая [категория полётных условий](/docs/v31/weather#flight-categories) для этой группы | | `parsed.forecast[].probability` | object \| null | **Да** (ключ присутствует всегда) | Заполняется в группах `PROB30`/`PROB40` — см. ниже | | `parsed.forecast[].turbulence` | array | **Да** (для каждого элемента) | Интенсивность атмосферной турбулентности, если она указана в прогнозе, — `[]`, если её нет | | `parsed.forecast[].icing` | array | **Да** (для каждого элемента) | Интенсивность обледенения ВС, если оно указано в прогнозе, — `[]`, если его нет | ### Схемы объектов и допустимость null [#object-schemas-and-nullability] Каждый объект в `parsed.forecast[]` содержит одинаковый набор ключей во всех периодах — для `wind`, `visibility`, `clouds` и `wx_codes` действуют те же правила, что и для [допустимости null в METAR](/docs/v31/weather-metar#object-schemas-and-nullability). | Поле | Тип | Обязательный | Null / пусто | Примечания | | ------------------------------- | -------------- | ------------ | -------------------------- | --------------------------------------------------------- | | `parsed.forecast[].wind` | object | **Да** | Присутствует всегда | Та же форма, что у METAR `parsed.wind` | | `parsed.forecast[].visibility` | object | **Да** | Присутствует всегда | `value: null` часто встречается при `P6SM` (`repr: "P6"`) | | `parsed.forecast[].clouds` | array | **Да** | Возможно `[]` | Та же форма элементов, что в METAR | | `parsed.forecast[].wx_codes` | array | **Да** | `[]`, если явлений нет | Та же форма элементов `{ repr, value }`, что в METAR | | `parsed.forecast[].probability` | object \| null | **Да** | `null` в большинстве групп | Объект в группах `PROB30`/`PROB40` — см. ниже | | `parsed.forecast[].turbulence` | array | **Да** | `[]`, если не указана | Никогда не `null` | | `parsed.forecast[].icing` | array | **Да** | `[]`, если не указано | Никогда не `null` | При `parsed=false` ключ `parsed` полностью отсутствует. #### Вероятность в группах PROB [#probability-on-prob-groups] В исходном [TAF](https://en.wikipedia.org/wiki/Terminal_aerodrome_forecast) группы `PROB30` и `PROB40` обозначают вероятностные подпериоды (вероятность явления 30 % или 40 %). В рабочем JSON они представлены записью `FROM` или `TEMPO` с заполненным объектом `probability` — отдельного `type: "PROB"` **нет** (проверено на KORD, EGLL, EDDF). ```json "probability": { "repr": "30", "value": 30, "spoken": "three zero" } ``` | Поле | Тип | Обязательный | Описание | | -------- | ------- | ------------ | --------------------------------- | | `repr` | string | **Да** | Исходный токен: `"30"` или `"40"` | | `value` | integer | **Да** | `30` или `40` | | `spoken` | string | **Да** | Устная форма из бюллетеня | Если группа не вероятностная, `probability` равно `null`. #### Группы турбулентности и обледенения [#turbulence-and-icing-groups] Большинство периодов прогноза возвращают `"turbulence": []` и `"icing": []`. Если исходный [TAF](https://en.wikipedia.org/wiki/Terminal_aerodrome_forecast) содержит группы `TURB` или `ICE`, каждый массив содержит один или несколько объектов как минимум с полями `repr` (исходный токен) и `value` (интенсивность в удобочитаемом виде) — тот же шаблон `{ repr, value }`, что и у `wx_codes`. Если в бюллетене указан вертикальный слой, могут появиться дополнительные ключи высоты; относитесь к неизвестным ключам как к расширениям, совместимым с будущими версиями. ```json "turbulence": [{ "repr": "MOD", "value": "Moderate" }], "icing": [] ``` #### Типы периодов прогноза [#forecast-period-types] Проходите по `parsed.forecast[]` в хронологическом порядке: сначала действующая базовая группа `FROM`, затем перекрывающие её модификаторы. | Токен TAF | `type` в JSON | Поля времени | Что это значит | | ----------------------- | ---------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------- | | Начальная группа / `FM` | `FROM` | `start_time` → `end_time` | **Базовые условия.** Каждая группа `FM` заменяет всё, что было до неё, начиная с `start_time` | | `TEMPO` | `TEMPO` | `start_time` → `end_time` | **Временные колебания** в рамках базовых условий — показывайте как оговорку, а не как замену | | `BECMG` | `BECMG` | `start_time` → `end_time` | **Постепенное изменение** к значениям этой группы к моменту `end_time` | | `PROB30` / `PROB40` | `FROM` или `TEMPO` + `probability` | как у родительского типа | **Вероятностный подпериод** — непустой `probability` в строке | **Чтение периодов для времени вылета** 1. Отфильтруйте `parsed.forecast[]` по условию `type == "FROM"` и `start_time <= departure <= end_time` — это базовые условия. 2. Соберите перекрывающиеся строки `TEMPO`, `BECMG` и вероятностные строки — это модификаторы. 3. Выводите базовое значение [flight\_rules](/docs/v31/weather#flight-categories) на видном месте; модификаторы перечисляйте отдельно. 4. Наихудший сценарий по всему [TAF](https://en.wikipedia.org/wiki/Terminal_aerodrome_forecast): наивысший ранг [flight\_rules](/docs/v31/weather#flight-categories) среди всех групп `FROM`. Пример для KORD: базовая группа `FROM` может давать `VFR`, а перекрывающая её `TEMPO` — `MVFR` с `-SHRA`; показывайте оба значения. ## Клиентские типы [#client-types] Скопируйте в свой проект. Допустимость null соответствует разделам [Схемы объектов и допустимость null](#object-schemas-and-nullability) и [допустимость null в METAR](/docs/v31/weather-metar#object-schemas-and-nullability) для общих вложенных объектов. `TafResponse` / `TafParsed` / `TafPeriod` соответствуют JSON API. `TafDepartureSummary` определён в начале каждой вкладки примера кода. ## Интеграция [#integration] Получение, кэширование и интерпретация периодов прогноза на время вылета. Пример кэширует каждый [TAF](https://en.wikipedia.org/wiki/Terminal_aerodrome_forecast) на пятнадцать минут ([TAF](https://en.wikipedia.org/wiki/Terminal_aerodrome_forecast) переиздаются четыре раза в сутки), использует тайм-ауты подключения/чтения 10 с / 15 с, выбирает действующую группу `FROM` на время вылета и перечисляет перекрывающиеся модификаторы `TEMPO`/`BECMG`. Пошаговый разбор наложения периодов: [Наложение периодов TAF](/docs/v31/weather-integration-airport#3-what-will-the-weather-be-when-i-depart). ### Примечания по реализации [#implementation-notes] **Чтение групп TEMPO и вероятностных групп.** TEMPO накладывается на действующую базовую группу FROM. `PROB30`/`PROB40` представлены строками с непустым `probability` — проверяйте `probability.value`, а не отдельный `type`. См. [Типы периодов прогноза](#forecast-period-types). **[TAF](https://en.wikipedia.org/wiki/Terminal_aerodrome_forecast) обновляются четыре раза в сутки** — в 00Z, 06Z, 12Z и 18Z. Кэширование на 15–30 минут вполне уместно. **404 при отсутствии [TAF](https://en.wikipedia.org/wiki/Terminal_aerodrome_forecast).** Многие аэродромы авиации общего назначения публикуют только [METAR](https://en.wikipedia.org/wiki/METAR). Воспринимайте `404` для [TAF](https://en.wikipedia.org/wiki/Terminal_aerodrome_forecast) как отсутствие прогнозных данных, а не как неудачный запрос. **Совместное использование с [METAR](https://en.wikipedia.org/wiki/METAR).** Запрашивайте оба параллельно. Используйте [flight\_rules](/docs/v31/weather#flight-categories) из [METAR](https://en.wikipedia.org/wiki/METAR) для текущих условий, а наихудшее значение [flight\_rules](/docs/v31/weather#flight-categories) среди групп FROM по всему [TAF](https://en.wikipedia.org/wiki/Terminal_aerodrome_forecast) — как наихудшие ожидаемые. ## Ответы с ошибками [#error-responses] Здесь описаны только ошибки, **специфичные для [TAF](https://en.wikipedia.org/wiki/Terminal_aerodrome_forecast)**. Общие ошибки: [Обработка ошибок](/docs/errors). `404` для [METAR](https://en.wikipedia.org/wiki/METAR) и для [TAF](https://en.wikipedia.org/wiki/Terminal_aerodrome_forecast) в продакшне: [Когда погодные данные отсутствуют](/docs/v31/weather-integration-errors#when-weather-data-is-missing). ### 404 — нет TAF для этого кода ICAO [#404--no-taf-for-this-icao] ```json { "detail": "No current TAF forecast available for KOXB. Weather station may not issue TAF reports or may be temporarily offline." } ``` Типичный случай: у аэропорта есть [METAR](https://en.wikipedia.org/wiki/METAR), но нет [TAF](https://en.wikipedia.org/wiki/Terminal_aerodrome_forecast). Запрашивайте [METAR](https://en.wikipedia.org/wiki/METAR) как обычно; пропустите [TAF](https://en.wikipedia.org/wiki/Terminal_aerodrome_forecast) и выведите в интерфейсе **Прогноз недоступен**. *** См. также: [METAR](/docs/v31/weather-metar) · [Сценарии использования](/docs/v31/weather-integration-airport) · [Ошибки](/docs/v31/weather-integration-errors) · [Продакшн](/docs/v31/weather-integration-production)