# PIREP (донесения пилотов)

Донесения пилотов (PIREP) в ограничивающем прямоугольнике: турбулентность, обледенение и погода в полёте, переданные пилотами за заданный период.



[PIREP (донесения пилотов)](https://www.aviationweather.gov/help/data/#pirep) — это добровольные сообщения о погоде в полёте, которые передают пилоты. Они фиксируют условия, которые пропускают автоматические датчики, — турбулентность, обледенение, верхнюю границу облаков, видимость и температуру на высоте, — часто за несколько минут до того, как эти условия появятся в прогнозах. Этот эндпоинт возвращает все [PIREP](https://www.aviationweather.gov/help/data/#pirep), местоположение которых попадает в ваш ограничивающий прямоугольник (bounding box) в пределах настраиваемого временного окна. Используйте [PIREP](https://www.aviationweather.gov/help/data/#pirep) вместе с [METAR](/docs/v31/weather-metar), [TAF](/docs/v31/weather-taf) и [AIRMET/SIGMET](/docs/v31/airsigmet), когда вам нужны недавние опасные явления вдоль маршрута, замеченные пилотами. Донесения привязаны к географии — передавайте ограничивающий прямоугольник вокруг траектории полёта, а не код ICAO одного аэропорта. Покрытие ориентировано на США; запросы по районам с низкой интенсивностью полётов часто возвращают пустой массив `reports`, даже если bbox задан корректно.

Типы донесений: **UA** (обычный [PIREP](https://www.aviationweather.gov/help/data/#pirep)) и **UUA** (срочный [PIREP](https://www.aviationweather.gov/help/data/#pirep) — значительная опасность; выделяйте такие донесения в интерфейсе в первую очередь).

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

<DocRequirements>
  <DocRequirementAuth />
</DocRequirements>

Отправьте запрос <HttpMethod>GET</HttpMethod> с географическим ограничивающим прямоугольником и, при необходимости, окном поиска в прошлом.

<DocApiPath method="GET" path="/weather/pireps" />

| Параметр | Тип     | Обязательный | По умолчанию | Описание                                                                                                                                          |
| -------- | ------- | ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bbox`   | string  | Да           | -            | Ограничивающий прямоугольник в формате `lat1,lon1,lat2,lon2` — сначала юго-западный угол. Пример: `39,-78,42,-71` (коридор на северо-востоке США) |
| `hours`  | integer | Нет          | `2`          | На сколько часов назад искать (`1`–`24`)                                                                                                          |

**Советы по ограничивающему прямоугольнику.** Задавайте размер прямоугольника по участку маршрута с запасом — за пределами загруженного воздушного пространства [PIREP](https://www.aviationweather.gov/help/data/#pirep) встречаются редко. Пустой массив `reports` — нормальный ответ, если в последнее время пилоты не передавали донесений в этом районе.

## Ответ [#response]

```json
{
  "bbox": "39.0,-78.0,42.0,-71.0",
  "hours": 3,
  "reports": [
    {
      "raw": "UA /OV JFK/TM 1845/FL085/TP B738/TB MOD/RM CONT MOD CHOP",
      "report_type": "UA",
      "location": "JFK",
      "time": "2025-01-15T18:45:00Z",
      "altitude": "FL085",
      "aircraft_type": "B738",
      "turbulence": "Moderate",
      "icing": null,
      "sky_conditions": null,
      "temperature": null,
      "wind": null,
      "remarks": "CONT MOD CHOP",
      "latitude": 40.64,
      "longitude": -73.78
    }
  ],
  "total": 1
}
```

Если подходящих донесений нет, API возвращает `"reports": []` и `"total": 0` — это не ошибка.

| Поле      | Тип     | Обязательный | Описание                                        |
| --------- | ------- | ------------ | ----------------------------------------------- |
| `bbox`    | string  | **Да**       | Эхо запрошенного ограничивающего прямоугольника |
| `hours`   | integer | **Да**       | Применённое окно поиска в прошлом               |
| `reports` | array   | **Да**       | Подходящие PIREP (может быть пустым)            |
| `total`   | integer | **Да**       | Количество элементов в `reports`                |

### Донесение [#report]

Путь в JSON: `reports[]`. Гарантированно не равно null только поле `raw`. Все декодированные поля равны `null`, если соответствующих данных нет в переданном донесении, — рассчитывайте на разреженные объекты, особенно в старых или кратких [PIREP](https://www.aviationweather.gov/help/data/#pirep).

| Поле             | Тип            | Обязательный                      | Может быть null? | Описание                                                                           |
| ---------------- | -------------- | --------------------------------- | ---------------- | ---------------------------------------------------------------------------------- |
| `raw`            | string         | **Да**                            | Никогда          | Полный текст PIREP в том виде, в каком он был передан                              |
| `report_type`    | string \| null | **Да** (ключ присутствует всегда) | **Да**           | `UA` (обычное) или `UUA` (срочное)                                                 |
| `location`       | string \| null | **Да** (ключ присутствует всегда) | **Да**           | Идентификатор местоположения или пеленг/расстояние от радионавигационного средства |
| `time`           | string \| null | **Да** (ключ присутствует всегда) | **Да**           | Время наблюдения (UTC, ISO 8601)                                                   |
| `altitude`       | string \| null | **Да** (ключ присутствует всегда) | **Да**           | Эшелон полёта или высота, например `FL085`                                         |
| `aircraft_type`  | string \| null | **Да** (ключ присутствует всегда) | **Да**           | Код типа ВС, например `B738`                                                       |
| `sky_conditions` | string \| null | **Да** (ключ присутствует всегда) | **Да**           | Состояние неба или облачность                                                      |
| `turbulence`     | string \| null | **Да** (ключ присутствует всегда) | **Да**           | Интенсивность турбулентности — см. [Шкалы интенсивности](#intensity-scales)        |
| `icing`          | string \| null | **Да** (ключ присутствует всегда) | **Да**           | Интенсивность обледенения — см. [Шкалы интенсивности](#intensity-scales)           |
| `temperature`    | string \| null | **Да** (ключ присутствует всегда) | **Да**           | Температура наружного воздуха                                                      |
| `wind`           | string \| null | **Да** (ключ присутствует всегда) | **Да**           | Направление и скорость ветра                                                       |
| `remarks`        | string \| null | **Да** (ключ присутствует всегда) | **Да**           | Дополнительные примечания                                                          |
| `latitude`       | number \| null | **Да** (ключ присутствует всегда) | **Да**           | Широта донесения, если выполнено геокодирование                                    |
| `longitude`      | number \| null | **Да** (ключ присутствует всегда) | **Да**           | Долгота донесения, если выполнено геокодирование                                   |

### Схемы объектов и допустимость null [#object-schemas-and-nullability]

Каждый ключ объекта донесения присутствует всегда — ничего не опускается, даже если поле не было сообщено. Если пилот не включил какой-либо раздел, используется `null`.

| Ситуация                                                         | Что вы получаете                    | Но не это           |
| ---------------------------------------------------------------- | ----------------------------------- | ------------------- |
| Пилот не указал турбулентность                                   | `turbulence: null`                  | ключ отсутствует    |
| Пилот не указал обледенение                                      | `icing: null`                       | ключ отсутствует    |
| Указана только позиция относительно радионавигационного средства | `latitude: null`, `longitude: null` | ключ отсутствует    |
| Нет донесений в заданном окне                                    | `reports: []`, `total: 0`           | `null`, ошибка HTTP |
| Обычное донесение                                                | `report_type: "UA"`                 | `null`              |
| Срочное донесение об опасности                                   | `report_type: "UUA"`                | `"UA"`              |

<a id="intensity-scales" />

#### Шкалы интенсивности [#intensity-scales]

Декодированные строки `turbulence` и `icing` следуют стандартной терминологии интенсивности [PIREP](https://www.aviationweather.gov/help/data/#pirep). Значения представляют собой декодированный текст; точная строка может незначительно различаться от донесения к донесению.

| Турбулентность (примеры) | Значение      |
| ------------------------ | ------------- |
| `NEG` / `Negative`       | Не отмечена   |
| `LGT` / `Light`          | Слабая        |
| `MOD` / `Moderate`       | Умеренная     |
| `SVR` / `Severe`         | Сильная       |
| `EXTM` / `Extreme`       | Экстремальная |

| Обледенение (примеры) | Значение  |
| --------------------- | --------- |
| `NEG` / `Negative`    | Нет       |
| `TRC` / `Trace`       | Следы     |
| `LGT` / `Light`       | Слабое    |
| `MOD` / `Moderate`    | Умеренное |
| `SVR` / `Severe`      | Сильное   |

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

<DocClientTypes id="v31/weather/pirep-types" />

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

Опрашивайте [PIREP](https://www.aviationweather.gov/help/data/#pirep) в ограничивающем прямоугольнике вдоль маршрута и выводите срочные донесения первыми.

Пример запрашивает bbox коридора, кэширует результаты на 10 минут ([PIREP](https://www.aviationweather.gov/help/data/#pirep) быстро теряют актуальность) и возвращает только срочные донесения `UUA`, а также максимальную наблюдавшуюся интенсивность турбулентности. **Пустой массив `reports` — норма для спокойных маршрутов**: показывайте «нет недавних донесений пилотов», а не состояние ошибки. &#x2A;*Ставьте донесения `UUA`** выше обычных `UA` в интерфейсах диспетчеров или EFB.

<DocExample id="v31/weather/pirep-fetch" />

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

**Разреженные данные — это нормально.** В отличие от [METAR](https://en.wikipedia.org/wiki/METAR), [PIREP](https://www.aviationweather.gov/help/data/#pirep) зависят от того, передают ли пилоты донесения. Прежде чем решить, что API не работает, расширьте bbox или увеличьте `hours`.

**Приоритет для `UUA`.** Срочные [PIREP](https://www.aviationweather.gov/help/data/#pirep) указывают на значительные опасные явления. Считайте любое донесение `UUA` с `turbulence: "SVR"` или `"EXTM"` поводом для немедленного оповещения.

**Пробелы в геокодировании.** `latitude` и `longitude` равны `null`, если в донесении указана только позиция относительно радионавигационного средства (например, `25 SW of ORL`). Для отображения разбирайте `location` и `raw`; не отбрасывайте такие донесения.

**Не опрашивайте слишком часто.** Достаточно интервала обновления 5–15 минут. Для предупреждений по целым районам дополняйте данные эндпоинтом [AIRMET/SIGMET](/docs/v31/airsigmet).

**`time` и время запроса.** `time` — это время наблюдения из [PIREP](https://www.aviationweather.gov/help/data/#pirep); используйте его для отображения в формате «X минут назад». Отдельной метки времени получения данных через API у [PIREP](https://www.aviationweather.gov/help/data/#pirep) нет.

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

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

### 400 — недопустимый формат bbox [#400--invalid-bbox-format]

```json
{
  "detail": "Invalid bounding box format. Expected 'lat1,lon1,lat2,lon2'"
}
```

### 503 — вышестоящий сервис недоступен [#503--upstream-unavailable]

```json
{
  "detail": "PIREP service temporarily unavailable"
}
```

Повторите запрос с экспоненциальной задержкой (backoff). Обычно достаточно одной повторной попытки через 5–10 секунд.

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

***

См. также: [Раздел «Погода»](/docs/v31/weather) · [AIRMET/SIGMET](/docs/v31/airsigmet) · [METAR](/docs/v31/weather-metar) · [Сценарий: срочные PIREP на маршруте](/docs/v31/weather-integration-enroute#8-urgent-pireps-along-the-route)