# Höhenwinde FB-Höhenwinde für US-Routen – Windrichtung, Windgeschwindigkeit und Temperatur in Standardhöhen innerhalb eines geografischen Begrenzungsrahmens. [Höhenwind](https://www.aviationweather.gov/winds/help)-Vorhersagen beschreiben die erwartete Windrichtung, Windgeschwindigkeit und Temperatur in Standardhöhenstufen für die Flugplanung in den USA. **[FB Winds](https://www.aviationweather.gov/winds/help)** (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](/docs/v31/weather-metar) und [TAF](/docs/v31/weather-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 [#request] Senden Sie eine GET-Anfrage mit einem geografischen Begrenzungsrahmen. Optionale Query-Flags wählen den Vorhersagezeitraum und das Höhenband aus. | Parameter | Typ | Erforderlich | Standard | Beschreibung | | ---------- | ------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `bbox` | string | Ja | - | Begrenzungsrahmen als `lat1,lon1,lat2,lon2` — südwestliche Ecke zuerst, nordöstliche als zweite. Beispiel: `40,-80,42,-73` (Raum New York) | | `forecast` | integer | Nein | `12` | Vorhersagezeitraum in Stunden — `6`, `12` oder `24` | | `level` | string | Nein | `low` | Höhenband: `low` (3.000–39.000 ft MSL) oder `high` (6.000–45.000 ft MSL) | **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](https://en.wikipedia.org/wiki/World_Geodetic_System)). Längengrade westlich des Nullmeridians sind negativ (z. B. `-73.78` für JFK). ## Antwort [#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 } ``` | Feld | Typ | Erforderlich | Beschreibung | | --------------- | -------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------- | | `bbox` | string | **Ja** | Wiedergabe des abgefragten Begrenzungsrahmens | | `forecast_hour` | integer | **Ja** | Angewendeter Vorhersagezeitraum (`6`, `12` oder `24`) | | `level` | string | **Ja** | Angewendetes Höhenband (`low` oder `high`) | | `valid_time` | string \| null | **Ja** (Schlüssel immer vorhanden) | Gültigkeitszeit der Vorhersage (UTC), z. B. `131800Z`. `null`, wenn nicht angegeben | | `stations` | array | **Ja** | FB-Winds-Stationen innerhalb der bbox. `[]`, wenn keine passt — in der Regel zusammen mit `404` | | `total` | integer | **Ja** | Anzahl der Stationen in `stations` | ### Höhenbänder [#altitude-bands] | `level` | Typischerweise gelieferte Höhen (ft MSL) | | ------- | ---------------------------------------------------------------------------- | | `low` | 3.000 / 6.000 / 9.000 / 12.000 / 18.000 / 24.000 / 30.000 / 34.000 / 39.000 | | `high` | 6.000 / 9.000 / 12.000 / 18.000 / 24.000 / 30.000 / 34.000 / 39.000 / 45.000 | Die genauen Höhenstufen pro Station hängen vom FB-Produkt ab — nicht jede Station liefert jede Höhe. ### Objektschemas und Nullbarkeit [#object-schemas-and-nullability] 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. | Situation | Was Sie erhalten | Nicht so | | ------------------------------------------------- | ------------------------------------------------------------- | ------------------------------- | | Niedrige Höhenstufe ohne Temperatur | `temperature_c: null` | `0`, Schlüssel fehlt | | Windgruppe nicht dekodiert | `wind_direction: null`, `wind_speed_kt: null` | Schlüssel fehlt oder `0` | | Schwache, umlaufende Winde | `light_and_variable: true`, `wind_direction` kann `null` sein | `null` für `light_and_variable` | | Station ohne dekodierte Höhenstufen | `winds: []` | `null`, Schlüssel fehlt | | Keine rohe FB-Zeile für die Station | `raw_text: null` | Schlüssel fehlt | | Vorgelagerte Quelle lässt die Gültigkeitszeit weg | `valid_time: null` | Schlüssel fehlt | | Keine Stationen innerhalb der bbox | `stations: []` + HTTP `404` | `null` | #### Station [#station] JSON-Pfad: `stations[]`. Jedes Element steht für eine FB-Winds-Station innerhalb der bbox. | Feld | Typ | Erforderlich | Null? | Beschreibung | | ----------- | -------------- | ---------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- | | `station` | string | **Ja** | Nie | Dreistellige Kennung der FB-Winds-Station (entspricht oft einem nahegelegenen Flughafen, z. B. `JFK`) | | `latitude` | number | **Ja** | Nie | Breitengrad der Station (Dezimalgrad) | | `longitude` | number | **Ja** | Nie | Längengrad der Station (Dezimalgrad) | | `winds` | array | **Ja** | Nie | Wind-/Temperaturstufen für diese Station. `[]`, wenn keine Stufen dekodiert wurden | | `raw_text` | string \| null | **Ja** (Schlüssel immer vorhanden) | **Ja** | Vollständige rohe FB-Winds-Zeile für diese Station. `null`, wenn nicht angegeben | #### Windstufe [#wind-level] JSON-Pfad: `stations[].winds[]`. Jedes Element steht für eine Höhenstufe der übergeordneten Station. | Feld | Typ | Erforderlich | Null? | Beschreibung | | -------------------- | --------------- | ---------------------------------- | ------ | ------------------------------------------------------------------------- | | `altitude_ft` | integer | **Ja** | Nie | Höhe dieser Stufe in Fuß MSL | | `wind_direction` | integer \| null | **Ja** (Schlüssel immer vorhanden) | **Ja** | Grad rechtweisend (`0`–`360`). `null`, wenn nicht dekodiert | | `wind_speed_kt` | integer \| null | **Ja** (Schlüssel immer vorhanden) | **Ja** | Geschwindigkeit in Knoten. `null`, wenn nicht dekodiert | | `temperature_c` | integer \| null | **Ja** (Schlüssel immer vorhanden) | **Ja** | Temperatur in °C. In den niedrigsten Stufen (3.000–6.000 ft) oft `null` | | `light_and_variable` | boolean | **Ja** | Nie | `true` bei schwachen, umlaufenden Winden (\< 5 kt). Standard `false` | | `raw` | string | **Ja** | Nie | Kodiertes Wind-Token für diese Stufe, z. B. `2735-09` (270°/35 kt, −9 °C) | **Schwach und umlaufend.** Ist `light_and_variable` gleich `true`, liegen die Winde unter 5 Knoten ohne bestimmte Richtung — `wind_direction` und `wind_speed_kt` können `null` oder null sein. ## Client-Typen [#client-types] ## Integration [#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. ### Hinweise zur Implementierung [#implementation-notes] **Nur US-Abdeckung.** [FB Winds](https://www.aviationweather.gov/winds/help) 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 [#error-responses] Nur endpoint-spezifische Fehler. Fehler bei Authentifizierung, Validierung, Rate Limits und Serverfehler, die alle Endpoints gemeinsam haben, finden Sie unter [Fehlerbehandlung](/docs/errors). ### 404 — keine Stationen in der bbox [#404--no-stations-in-bbox] ```json { "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 [#400--invalid-bbox-format] ```json { "detail": "Invalid bounding box format. Expected 'lat1,lon1,lat2,lon2'" } ``` ### 503 — vorgelagerter Dienst nicht verfügbar [#503--upstream-unavailable] ```json { "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. *** Siehe auch: [Wetter-Übersicht](/docs/v31/weather) · [METAR](/docs/v31/weather-metar) · [TAF](/docs/v31/weather-taf) · [Anwendungsfall Reiseflugwind](/docs/v31/weather-integration-enroute#7-cruise-wind-at-fl180-winds-aloft)