Höhenwinde

Höhenwind-Vorhersagen beschreiben die erwartete Windrichtung, Windgeschwindigkeit und Temperatur in Standardhöhenstufen für die Flugplanung in den USA. FB Winds (Winds and Temperatures Aloft) werden nach einem festen Zeitplan herausgegeben und decken Stationen im gesamten US-Festland ab; dieser Endpoint liefert jede Station, deren Koordinaten innerhalb Ihres Begrenzungsrahmens (Bounding Box) liegen. Verwenden Sie ihn zusammen mit METAR und TAF, wenn Sie Windkomponenten in Reiseflughöhe für die Kraftstoff- und Zeitplanung benötigen — nicht die Bodenbedingungen an einem einzelnen Flughafen. Die Abdeckung umfasst nur die USA: Abfragen für Gebiete außerhalb der USA liefern 404 ohne Stationen.

Anfrage

Senden Sie eine GET-Anfrage mit einem geografischen Begrenzungsrahmen. Optionale Query-Flags wählen den Vorhersagezeitraum und das Höhenband aus.

Tipps zum Begrenzungsrahmen. Legen Sie den Rahmen eng um Ihre Route — kleinere Gebiete liefern weniger Stationen und schnellere Antworten. Koordinaten werden in Dezimalgrad angegeben (WGS-84). Längengrade westlich des Nullmeridians sind negativ (z. B. -73.78 für JFK).

Antwort

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

Höhenbänder

Die genauen Höhenstufen pro Station hängen vom FB-Produkt ab — nicht jede Station liefert jede Höhe.

Objektschemas und Nullbarkeit

Jeder Schlüssel in einem Stationsobjekt ist immer vorhanden. Jeder Schlüssel in einem Windstufenobjekt ist immer vorhanden, sobald das Objekt existiert. Verwenden Sie null, 0 oder [] gemäß den folgenden Mustern — prüfen Sie niemals auf fehlende Schlüssel.

Client-Typen

"""Winds aloft response types - matches winds-aloft field tables."""from dataclasses import dataclassfrom typing import Literal@dataclassclass WindLevel:    altitude_ft: int    wind_direction: int | None    wind_speed_kt: int | None    temperature_c: int | None    light_and_variable: bool    raw: str@dataclassclass WindsAloftStation:    station: str    latitude: float    longitude: float    winds: list[WindLevel]    raw_text: str | None@dataclassclass WindsAloftResponse:    bbox: str    forecast_hour: int    level: str    valid_time: str | None    stations: list[WindsAloftStation]    total: int@dataclassclass CruiseWindSummary:    station: str    altitude_ft: int    direction_deg: int | None    speed_kt: int | None    temperature_c: int | None

Integration

Winde für den Begrenzungsrahmen einer Route abrufen und die Höhenstufe wählen, die Ihrer geplanten Reiseflughöhe am nächsten liegt.

Das Beispiel fragt einen Rahmen um den Raum New York ab, speichert die Antwort eine Stunde im Cache (FB-Produkte werden nach einem festen Zeitplan aktualisiert) und liefert die Windstufe, die einer Zielhöhe am nächsten liegt. Bei 404 gibt die Hilfsfunktion null zurück, und der Aufrufer zeigt einen leeren Zustand statt eines Fehlers an.

import osimport timefrom typing import TypedDictimport requests# CruiseWindSummary - helper return type. Full wire types are in the Client types section.class WindLevel(TypedDict):    altitude_ft: int    wind_direction: int | None    wind_speed_kt: int | None    temperature_c: int | None    light_and_variable: bool    raw: strclass Station(TypedDict):    station: str    latitude: float    longitude: float    winds: list[WindLevel]    raw_text: str | Noneclass WindsAloftResponse(TypedDict):    bbox: str    forecast_hour: int    level: str    valid_time: str | None    stations: list[Station]    total: intclass CruiseWindSummary(TypedDict):    station: str    altitude_ft: int    direction_deg: int | None    speed_kt: int | None    temperature_c: int | NoneHEADERS = {    "x-api-key": os.getenv("SKYLINK_API_KEY", "YOUR_API_KEY")}BASE = "https://data.skylinkapi.com/v3.1"CACHE: dict[str, tuple[WindsAloftResponse, float]] = {}WINDS_TTL = 3600  # 1 h - FB products update on a fixed scheduledef fetch_winds_aloft(bbox: str, forecast: int = 12, level: str = "low") -> WindsAloftResponse | None:    cache_key = f"winds:{bbox}:{forecast}:{level}"    cached = CACHE.get(cache_key)    if cached and time.time() < cached[1]:        return cached[0]    try:        r = requests.get(            f"{BASE}/weather/winds-aloft",            headers=HEADERS,            params={"bbox": bbox, "forecast": forecast, "level": level},            timeout=(10, 20),        )    except requests.Timeout as exc:        raise RuntimeError(f"SkyLink timeout fetching winds aloft for {bbox}") from exc    if r.status_code == 404:        return None    r.raise_for_status()    data: WindsAloftResponse = r.json()    CACHE[cache_key] = (data, time.time() + WINDS_TTL)    return datadef nearest_cruise_wind(    bbox: str,    target_altitude_ft: int = 18_000,    forecast: int = 12,) -> CruiseWindSummary | None:    """Pick the wind level closest to target altitude from the first station in the bbox."""    payload = fetch_winds_aloft(bbox, forecast=forecast, level="low")    if not payload or not payload["stations"]:        return None    station = payload["stations"][0]    levels = station["winds"]    if not levels:        return None    best = min(levels, key=lambda w: abs(w["altitude_ft"] - target_altitude_ft))    return {        "station": station["station"],        "altitude_ft": best["altitude_ft"],        "direction_deg": best["wind_direction"],        "speed_kt": best["wind_speed_kt"],        "temperature_c": best["temperature_c"],    }if __name__ == "__main__":    import json    from dataclasses import asdict    bbox = "-74.5,40.3,-73.5,41.0"    cruise = nearest_cruise_wind(bbox, target_altitude_ft=18_000)    print(json.dumps(asdict(cruise), indent=2) if cruise else "No winds data")

Hinweise zur Implementierung

Nur US-Abdeckung. FB Winds sind ein US-Produkt. Eine bbox über Europa oder dem Ozean ohne US-Stationen liefert 404 — keinen Authentifizierungs- oder Kontingentfehler. Bilden Sie Ihre bbox aus den Wegpunkten von US-Routen.

Leer vs. 404. Liegen keine Stationsmittelpunkte innerhalb der bbox, liefert die API 404 mit einer detail-Meldung, die Vorhersage und Höhenstufe nennt. Erweitern Sie die bbox leicht oder verschieben Sie sie entlang der Route.

Wahl von level. Verwenden Sie low für den typischen Reiseflug von Fluggesellschaften unterhalb von FL390. Verwenden Sie high, wenn Sie Daten für FL390–FL450 benötigen. Ist der Dienst für eine Höhenstufe vorübergehend nicht verfügbar, erhalten Sie möglicherweise 503 — wiederholen Sie die Anfrage mit Backoff.

Fehlende Temperaturen in niedrigen Höhen. Die Stufe 3.000 ft und manchmal auch 6.000 ft lassen die Temperatur häufig weg (temperature_c: null). Verwenden Sie Windrichtung und -geschwindigkeit für die Planung; behandeln Sie eine fehlende Temperatur als „in dieser Höhenstufe nicht gemeldet“.

Fehlerantworten

Nur endpoint-spezifische Fehler. Fehler bei Authentifizierung, Validierung, Rate Limits und Serverfehler, die alle Endpoints gemeinsam haben, finden Sie unter Fehlerbehandlung.

404 — keine Stationen in der bbox

{
  "detail": "No FB winds stations found in the given bounding box for forecast=12h, level=low"
}

Häufige Ursachen: bbox außerhalb der US-Abdeckung, bbox zu klein zwischen den Stationen oder Koordinaten außerhalb der USA. Erweitern Sie den Rahmen oder prüfen Sie, ob die Route über den USA verläuft.

400 — ungültiges bbox-Format

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

503 — vorgelagerter Dienst nicht verfügbar

{
  "detail": "Winds aloft service temporarily unavailable"
}

Wiederholen Sie die Anfrage nach einem kurzen Backoff. Besteht das Problem fort, versuchen Sie den anderen level-Wert oder eine andere forecast-Stunde.

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

{
  "bbox": "40,-80,42,-73",
  "forecast_hour": 12,
  "level": "low",
  "valid_time": "130000Z",
  "stations": [
    {
      "station": "JFK",
      "latitude": 40.6413,
      "longitude": -73.7781,
      "winds": [
        {
          "altitude_ft": 3000,
          "wind_direction": 270,
          "wind_speed_kt": 9,
          "light_and_variable": false,
          "raw": "2709"
        }
      ],
      "raw_text": "JFK      2709 3012+08 ..."
    }
  ],
  "total": 1
}

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

Siehe auch: Wetter-Übersicht · METAR · TAF · Anwendungsfall Reiseflugwind