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

PIREP (донесения пилотов) — это добровольные сообщения о погоде в полёте, которые передают пилоты. Они фиксируют условия, которые пропускают автоматические датчики, — турбулентность, обледенение, верхнюю границу облаков, видимость и температуру на высоте, — часто за несколько минут до того, как эти условия появятся в прогнозах. Этот эндпоинт возвращает все PIREP, местоположение которых попадает в ваш ограничивающий прямоугольник (bounding box) в пределах настраиваемого временного окна. Используйте PIREP вместе с METAR, TAF и AIRMET/SIGMET, когда вам нужны недавние опасные явления вдоль маршрута, замеченные пилотами. Донесения привязаны к географии — передавайте ограничивающий прямоугольник вокруг траектории полёта, а не код ICAO одного аэропорта. Покрытие ориентировано на США; запросы по районам с низкой интенсивностью полётов часто возвращают пустой массив reports, даже если bbox задан корректно.

Типы донесений: UA (обычный PIREP) и UUA (срочный PIREP — значительная опасность; выделяйте такие донесения в интерфейсе в первую очередь).

Запрос

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

Советы по ограничивающему прямоугольнику. Задавайте размер прямоугольника по участку маршрута с запасом — за пределами загруженного воздушного пространства PIREP встречаются редко. Пустой массив reports — нормальный ответ, если в последнее время пилоты не передавали донесений в этом районе.

Ответ

{
  "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 — это не ошибка.

Донесение

Путь в JSON: reports[]. Гарантированно не равно null только поле raw. Все декодированные поля равны null, если соответствующих данных нет в переданном донесении, — рассчитывайте на разреженные объекты, особенно в старых или кратких PIREP.

Схемы объектов и допустимость null

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

Шкалы интенсивности

Декодированные строки turbulence и icing следуют стандартной терминологии интенсивности PIREP. Значения представляют собой декодированный текст; точная строка может незначительно различаться от донесения к донесению.

Клиентские типы

"""PIREP response types - matches pireps field tables."""from dataclasses import dataclass@dataclassclass PirepReport:    raw: str    report_type: str | None = None    location: str | None = None    time: str | None = None    altitude: str | None = None    aircraft_type: str | None = None    sky_conditions: str | None = None    turbulence: str | None = None    icing: str | None = None    temperature: str | None = None    wind: str | None = None    remarks: str | None = None    latitude: float | None = None    longitude: float | None = None@dataclassclass PirepResponse:    bbox: str    hours: int    reports: list[PirepReport]    total: int

Интеграция

Опрашивайте PIREP в ограничивающем прямоугольнике вдоль маршрута и выводите срочные донесения первыми.

Пример запрашивает bbox коридора, кэширует результаты на 10 минут (PIREP быстро теряют актуальность) и возвращает только срочные донесения UUA, а также максимальную наблюдавшуюся интенсивность турбулентности. Пустой массив reports — норма для спокойных маршрутов: показывайте «нет недавних донесений пилотов», а не состояние ошибки. Ставьте донесения UUA выше обычных UA в интерфейсах диспетчеров или EFB.

import osimport timefrom typing import TypedDictimport requestsHEADERS = {    "x-api-key": os.getenv("SKYLINK_API_KEY", "YOUR_API_KEY")}BASE = "https://data.skylinkapi.com/v3.1"CACHE: dict[str, tuple[dict, float]] = {}PIREP_TTL = 600  # 10 min - PIREPs are short-livedclass PirepReport(TypedDict, total=False):    raw: str    report_type: str | None    turbulence: str | None    icing: str | None    time: str | Nonedef fetch_pireps(bbox: str, hours: int = 3) -> dict:    cache_key = f"pirep:{bbox}:{hours}"    cached = CACHE.get(cache_key)    if cached and time.time() < cached[1]:        return cached[0]    r = requests.get(        f"{BASE}/weather/pireps",        headers=HEADERS,        params={"bbox": bbox, "hours": hours},        timeout=(10, 20),    )    r.raise_for_status()    data = r.json()    CACHE[cache_key] = (data, time.time() + PIREP_TTL)    return datadef urgent_reports(bbox: str, hours: int = 3) -> list[PirepReport]:    payload = fetch_pireps(bbox, hours=hours)    reports: list[PirepReport] = payload.get("reports", [])    return [r for r in reports if r.get("report_type") == "UUA"]if __name__ == "__main__":    import json    bbox = "-74.5,40.3,-73.5,41.0"    payload = fetch_pireps(bbox, hours=3)    print(json.dumps(payload, indent=2, default=str)[:3000])

Примечания по реализации

Разреженные данные — это нормально. В отличие от METAR, PIREP зависят от того, передают ли пилоты донесения. Прежде чем решить, что API не работает, расширьте bbox или увеличьте hours.

Приоритет для UUA. Срочные PIREP указывают на значительные опасные явления. Считайте любое донесение UUA с turbulence: "SVR" или "EXTM" поводом для немедленного оповещения.

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

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

time и время запроса. time — это время наблюдения из PIREP; используйте его для отображения в формате «X минут назад». Отдельной метки времени получения данных через API у PIREP нет.

Ответы с ошибками

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

400 — недопустимый формат bbox

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

503 — вышестоящий сервис недоступен

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

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

curl -X GET "https://data.skylinkapi.com/v3.1/weather/pireps?bbox=string"

{
  "bbox": "39,-78,42,-71",
  "hours": 2,
  "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",
      "remarks": "CONT MOD CHOP"
    }
  ],
  "total": 1
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

См. также: Раздел «Погода» · AIRMET/SIGMET · METAR · Сценарий: срочные PIREP на маршруте