PIREPs (Pilotenmeldungen)

PIREPs (Pilotenmeldungen) sind freiwillige Wetterbeobachtungen von Piloten während des Flugs, die Bedingungen erfassen, die automatische Sensoren nicht erkennen — Turbulenz, Vereisung, Wolkenobergrenzen, Sicht und Temperatur in der Höhe —, oft Minuten bevor sie in Vorhersagen auftauchen. Dieser Endpoint liefert jeden PIREP, dessen Position innerhalb eines konfigurierbaren Zeitfensters in Ihrem Begrenzungsrahmen (Bounding Box) liegt. Verwenden Sie PIREPs zusammen mit METAR, TAF und AIRMET/SIGMET, wenn Sie aktuelle, von Piloten beobachtete Gefahren entlang einer Route benötigen. Die Meldungen sind geografisch — übergeben Sie einen Begrenzungsrahmen um Ihre Flugroute, nicht den ICAO-Code eines einzelnen Flughafens. Die Abdeckung konzentriert sich auf die USA; Abfragen über Gebieten mit wenig Flugverkehr liefern oft leere reports-Arrays, selbst wenn die Bbox gültig ist.

Meldungstypen: UA (Routine-PIREP) und UUA (dringender PIREP — erhebliche Gefahr; in Ihrer UI priorisieren).

Anfrage

Senden Sie eine Anfrage per GET mit einem geografischen Begrenzungsrahmen und optionalem Rückblickzeitraum.

Tipps zum Begrenzungsrahmen. Bemessen Sie den Rahmen nach Ihrem Streckenabschnitt plus Puffer — PIREPs sind außerhalb von stark beflogenem Luftraum spärlich. Ein leeres reports-Array ist eine normale Antwort, wenn in letzter Zeit keine Piloten Meldungen für das Gebiet abgegeben haben.

Antwort

{
  "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
}

Wenn keine Meldungen passen, liefert die API "reports": [] und "total": 0 — keinen Fehler.

Meldung

JSON-Pfad: reports[]. Nur raw ist garantiert nicht null. Alle dekodierten Felder sind null, wenn sie in der abgegebenen Meldung nicht enthalten sind — rechnen Sie mit spärlich befüllten Objekten, besonders bei älteren oder knappen PIREPs.

Objektschemas und Nullbarkeit

Jeder Schlüssel eines Meldungsobjekts ist immer vorhanden — nichts wird weggelassen, wenn ein Feld nicht gemeldet wurde. null steht für Abschnitte, die der Pilot nicht angegeben hat.

Intensitätsskalen

Die dekodierten Zeichenketten in turbulence und icing folgen dem üblichen PIREP-Intensitätsvokabular. Die Werte sind dekodierter Text; die genaue Zeichenkette kann zwischen Meldungen leicht variieren.

Client-Typen

"""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

Integration

Fragen Sie PIREPs in einem Begrenzungsrahmen entlang einer Route ab und zeigen Sie dringende Meldungen zuerst an.

Das Beispiel fragt eine Korridor-Bbox ab, speichert die Ergebnisse 10 Minuten lang im Cache (PIREPs sind kurzlebig) und gibt nur dringende UUA-Meldungen sowie den höchsten beobachteten Turbulenzgrad zurück. Ein leeres reports-Array ist auf ruhigen Routen normal — zeigen Sie „keine aktuellen Pilotenmeldungen“ an, niemals einen Fehlerzustand. Priorisieren Sie UUA-Meldungen gegenüber routinemäßigen UA-Meldungen in Dispatch- oder EFB-UIs.

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])

Hinweise zur Implementierung

Spärliche Daten sind normal. Anders als bei METAR hängen PIREPs davon ab, dass Piloten Meldungen abgeben. Vergrößern Sie die Bbox oder erhöhen Sie hours, bevor Sie annehmen, dass die API defekt ist.

UUA priorisieren. Dringende PIREPs weisen auf erhebliche Gefahren hin. Behandeln Sie jede UUA-Meldung mit turbulence: "SVR" oder "EXTM" als sofortige Warnung.

Lücken bei der Geokodierung. latitude und longitude sind null, wenn die Meldung nur eine Position relativ zu einer Funknavigationsanlage enthält (z. B. 25 SW of ORL). Greifen Sie für die Anzeige auf das Parsen von location und raw zurück; verwerfen Sie diese Meldungen nicht.

Nicht zu häufig abfragen. Ein Aktualisierungsintervall von 5–15 Minuten reicht aus. Kombinieren Sie die Abfrage mit AIRMET/SIGMET für gebietsweite Warnungen.

time vs. Anfragezeitpunkt. time ist die Beobachtungszeit aus dem PIREP — verwenden Sie sie für Anzeigen wie „vor X Minuten“. Für PIREPs gibt es keinen separaten Zeitstempel des API-Abrufs.

Fehlerantworten

Nur Endpoint-spezifische Fehler. Zu Authentifizierung, Validierung, Rate Limits und Serverfehlern siehe Fehlerbehandlung.

400 — ungültiges bbox-Format

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

503 — Upstream nicht verfügbar

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

Wiederholen Sie die Anfrage mit exponentiellem Backoff. Ein einzelner Wiederholungsversuch nach 5–10 Sekunden reicht meist aus.

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": {}
    }
  ]
}

Siehe auch: Wetter-Übersicht · AIRMET/SIGMET · METAR · Anwendungsfall: dringende PIREPs