# Ветер на высотах Ветер на высотах (FB) для маршрутов в США: направление и скорость ветра и температура на стандартных высотах в пределах bbox. Прогнозы [ветра на высотах](https://www.aviationweather.gov/winds/help) описывают ожидаемое направление и скорость ветра и температуру на стандартных высотах для планирования полётов в США. **[FB Winds](https://www.aviationweather.gov/winds/help)** (Winds and Temperatures Aloft) выпускаются по фиксированному графику и охватывают станции по всей континентальной части США; этот эндпоинт возвращает все станции, координаты которых попадают в ваш ограничивающий прямоугольник (bounding box). Используйте его вместе с [METAR](/docs/v31/weather-metar) и [TAF](/docs/v31/weather-taf), когда нужны составляющие ветра на крейсерской высоте для планирования топлива и времени, а не приземные условия в отдельном аэропорту. Покрытие — **только США**: запросы по территориям за пределами США возвращают `404` без станций. ## Запрос [#request] Отправьте GET с географическим ограничивающим прямоугольником. Необязательные query-параметры задают горизонт прогноза и диапазон высот. | Параметр | Тип | Обязательный | По умолчанию | Описание | | ---------- | ------- | ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bbox` | string | Да | - | Ограничивающий прямоугольник в формате `lat1,lon1,lat2,lon2` — сначала юго-западный угол, затем северо-восточный. Пример: `40,-80,42,-73` (район Нью-Йорка) | | `forecast` | integer | Нет | `12` | Период прогноза в часах — `6`, `12` или `24` | | `level` | string | Нет | `low` | Диапазон высот: `low` (3000–39 000 ft MSL) или `high` (6000–45 000 ft MSL) | **Советы по ограничивающему прямоугольнику.** Держите прямоугольник как можно ближе к маршруту — меньшие области возвращают меньше станций, и ответ приходит быстрее. Координаты задаются в десятичных градусах ([WGS-84](https://en.wikipedia.org/wiki/World_Geodetic_System)). Долгота к западу от нулевого меридиана отрицательна (например, `-73.78` для JFK). ## Ответ [#response] ```json { "bbox": "40.0,-80.0,42.0,-73.0", "forecast_hour": 12, "level": "low", "valid_time": "131800Z", "stations": [ { "station": "JFK", "latitude": 40.6413, "longitude": -73.7781, "winds": [ { "altitude_ft": 3000, "wind_direction": 310, "wind_speed_kt": 7, "temperature_c": null, "light_and_variable": false, "raw": "3107" }, { "altitude_ft": 18000, "wind_direction": 270, "wind_speed_kt": 35, "temperature_c": -9, "light_and_variable": false, "raw": "2735-09" } ], "raw_text": "JFK 3107 3215+13 2926+08 2827+06 2735-09 2645-23 255637 256344 255852" } ], "total": 1 } ``` | Поле | Тип | Обязательный | Описание | | --------------- | -------------- | --------------------------------- | -------------------------------------------------------------------------------- | | `bbox` | string | **Да** | Повтор запрошенного ограничивающего прямоугольника | | `forecast_hour` | integer | **Да** | Применённый период прогноза (`6`, `12` или `24`) | | `level` | string | **Да** | Применённый диапазон высот (`low` или `high`) | | `valid_time` | string \| null | **Да** (ключ присутствует всегда) | Время действия прогноза (UTC), например `131800Z`. `null`, если не указано | | `stations` | array | **Да** | Станции FB Winds внутри bbox. `[]`, если совпадений нет, — обычно вместе с `404` | | `total` | integer | **Да** | Количество станций в `stations` | ### Диапазоны высот [#altitude-bands] | `level` | Типичные возвращаемые высоты (ft MSL) | | ------- | -------------------------------------------------------------------------- | | `low` | 3000 / 6000 / 9000 / 12 000 / 18 000 / 24 000 / 30 000 / 34 000 / 39 000 | | `high` | 6000 / 9000 / 12 000 / 18 000 / 24 000 / 30 000 / 34 000 / 39 000 / 45 000 | Точный набор высот для каждой станции зависит от продукта FB — не каждая станция возвращает все высоты. ### Схемы объектов и допустимость null [#object-schemas-and-nullability] Каждый ключ объекта станции присутствует всегда. Каждый ключ объекта уровня ветра присутствует всегда, если сам объект существует. Используйте `null`, `0` или `[]` согласно шаблонам ниже — никогда не проверяйте отсутствие ключа. | Ситуация | Что вы получите | Чего не будет | | ------------------------------------------- | -------------------------------------------------------------- | ------------------------------- | | Низкий уровень без температуры | `temperature_c: null` | `0`, отсутствующий ключ | | Группа ветра не декодирована | `wind_direction: null`, `wind_speed_kt: null` | отсутствующий ключ или `0` | | Слабый ветер переменного направления | `light_and_variable: true`, `wind_direction` может быть `null` | `null` для `light_and_variable` | | Станция без декодированных уровней | `winds: []` | `null`, отсутствующий ключ | | Нет исходной строки FB для станции | `raw_text: null` | отсутствующий ключ | | Источник данных не указывает время действия | `valid_time: null` | отсутствующий ключ | | Нет станций внутри bbox | `stations: []` + HTTP `404` | `null` | #### Станция [#station] Путь в JSON: `stations[]`. Каждый элемент представляет одну станцию FB Winds внутри bbox. | Поле | Тип | Обязательный | Допускает null | Описание | | ----------- | -------------- | --------------------------------- | -------------- | --------------------------------------------------------------------------------------------------- | | `station` | string | **Да** | Никогда | 3-буквенный идентификатор станции FB Winds (часто совпадает с ближайшим аэропортом, например `JFK`) | | `latitude` | number | **Да** | Никогда | Широта станции (десятичные градусы) | | `longitude` | number | **Да** | Никогда | Долгота станции (десятичные градусы) | | `winds` | array | **Да** | Никогда | Уровни ветра и температуры для этой станции. `[]`, если ни один уровень не декодирован | | `raw_text` | string \| null | **Да** (ключ присутствует всегда) | **Да** | Полная исходная строка FB Winds для этой станции. `null`, если не указана | #### Уровень ветра [#wind-level] Путь в JSON: `stations[].winds[]`. Каждый элемент представляет один уровень высоты для родительской станции. | Поле | Тип | Обязательный | Допускает null | Описание | | -------------------- | --------------- | --------------------------------- | -------------- | ------------------------------------------------------------------------------------ | | `altitude_ft` | integer | **Да** | Никогда | Высота уровня в футах над MSL | | `wind_direction` | integer \| null | **Да** (ключ присутствует всегда) | **Да** | Истинное направление в градусах (`0`–`360`). `null`, если не декодировано | | `wind_speed_kt` | integer \| null | **Да** (ключ присутствует всегда) | **Да** | Скорость в узлах. `null`, если не декодирована | | `temperature_c` | integer \| null | **Да** (ключ присутствует всегда) | **Да** | Температура в °C. На самых низких уровнях (3000–6000 ft) часто `null` | | `light_and_variable` | boolean | **Да** | Никогда | `true`, если ветер слабый и переменного направления (\< 5 kt). По умолчанию `false` | | `raw` | string | **Да** | Никогда | Закодированная группа ветра для этого уровня, например `2735-09` (270°/35 kt, −9 °C) | **Слабый ветер переменного направления.** Когда `light_and_variable` равно `true`, скорость ветра ниже 5 узлов и определённого направления нет — `wind_direction` и `wind_speed_kt` могут быть `null` или нулём. ## Клиентские типы [#client-types] ## Интеграция [#integration] Запросите ветер для ограничивающего прямоугольника маршрута и выберите уровень, ближайший к планируемой крейсерской высоте. Пример запрашивает прямоугольник вокруг района Нью-Йорка, кэширует ответ на один час (продукты FB обновляются по фиксированному графику) и возвращает уровень ветра, ближайший к целевой высоте. При `404` вспомогательная функция возвращает `null`, и вызывающий код показывает пустое состояние вместо ошибки. ### Примечания по реализации [#implementation-notes] **Покрытие только США.** [FB Winds](https://www.aviationweather.gov/winds/help) — продукт США. Bbox над Европой или океаном без станций США возвращает `404` — это не ошибка аутентификации или квоты. Стройте bbox по точкам маршрута в США. **Пустой результат и 404.** Если ни один центроид станции не попадает в bbox, API возвращает `404` с сообщением `detail`, в котором указаны прогноз и уровень. Немного расширьте bbox или сместите его вдоль маршрута. **Выбор `level`.** Используйте `low` для типичного крейсерского полёта авиалайнеров ниже FL390. Используйте `high`, когда нужны данные для FL390–FL450. Если сервис временно недоступен для уровня, вы можете получить `503` — повторите запрос с экспоненциальной задержкой (backoff). **Отсутствие температуры на низких высотах.** На уровне 3000 ft, а иногда и 6000 ft температура обычно не указывается (`temperature_c: null`). Используйте для планирования направление и скорость ветра; отсутствующую температуру трактуйте как «не сообщается на этом уровне». ## Ответы с ошибками [#error-responses] Здесь описаны только ошибки, специфичные для эндпоинта. Об ошибках аутентификации, валидации, ограничениях частоты запросов и ошибках сервера, общих для всех эндпоинтов, см. [Обработка ошибок](/docs/errors). ### 404 — в bbox нет станций [#404--no-stations-in-bbox] ```json { "detail": "No FB winds stations found in the given bounding box for forecast=12h, level=low" } ``` Частые причины: bbox за пределами покрытия США, слишком маленький bbox между станциями или координаты вне США. Расширьте прямоугольник или убедитесь, что маршрут проходит над США. ### 400 — некорректный формат bbox [#400--invalid-bbox-format] ```json { "detail": "Invalid bounding box format. Expected 'lat1,lon1,lat2,lon2'" } ``` ### 503 — источник данных недоступен [#503--upstream-unavailable] ```json { "detail": "Winds aloft service temporarily unavailable" } ``` Повторите запрос после короткой задержки. Если ошибка сохраняется, попробуйте другой `level` или другой час `forecast`. *** См. также: [Раздел «Погода»](/docs/v31/weather) · [METAR](/docs/v31/weather-metar) · [TAF](/docs/v31/weather-taf) · [Сценарий: ветер на крейсерской высоте](/docs/v31/weather-integration-enroute#7-cruise-wind-at-fl180-winds-aloft)