Thermik API -- Technische Dokumentation¶

Überblick¶

Diese API stellt thermische Bewertungsdaten („Thermik Score") auf Basis von Open-Meteo-Wetterdaten bereit. Sie ist für die Integration in Systeme wie Home Assistant, Dashboards oder Automationen ausgelegt.

Endpunkte¶

Endpoint Zweck

/api/thermal Liefert aktuelle Thermikbewertung + Tagesprognose /api/locations Liefert alle verfügbaren Locations inkl. Default

Datenaktualisierung (Caching)¶

• Daten werden on demand geladen
• Cache-TTL: 30 Minuten (1800 Sekunden)
• Mehrere Zugriffe innerhalb der TTL erzeugen keine zusätzlichen Open-Meteo Requests
• Nach Ablauf der TTL wird beim nächsten Request neu geladen

/api/locations¶

Request¶

GET /api/locations

Beispiel¶

http://soaring.node01.de/api/locations

Response¶

{
  "default": "mfg-h",
  "locations": [
    {
      "key": "mfg-h",
      "name": "Modellfluggruppe Haueneberstein",
      "lat": 48.81,
      "lon": 8.21,
      "calibration_error": 0.0
    }
  ]
}

/api/thermal¶

Request¶

GET /api/thermal
GET /api/thermal?location=mfg-h

Beispiel¶

http://soaring.node01.deg/api/thermal?location=mfg-h

Response-Struktur¶

{
  "location": {...},
  "meta": {...},
  "forecast": {...},
  "current": {...}
}

current Objekt¶

{
  "time": "2026-02-19T14:00",
  "hourly_index": 12,
  "score": 63.4,
  "smooth": 61.9,
  "wind_dir_deg": 240,
  "wind_dir_label": "WSW",
  "wx": {
    "temperature_2m": 9.1,
    "cloudcover_low": 35,
    "windspeed_10m": 3.4,
    "windgusts_10m": 6.1,
    "precipitation": 0.0,
    "relative_humidity_2m": 58,
    "cape": 12
  }
}

Smooth-Funktion¶

Die Glättung erfolgt als 3-Punkt gleitender Mittelwert über alle Stunden:

• Erste Stunde:

  (score[0] + score[1]) / 2
  

• Letzte Stunde:

  (score[n-2] + score[n-1]) / 2
  

• Sonst:

  (score[i-1] + score[i] + score[i+1]) / 3
  

Eigenschaften:

• Reduziert Ausreißer
• Stabilisiert Automationen
• Wird für alle Stunden 0--23 berechnet

Windrichtung (16er-Windrose)¶

Berechnung:

index = int((deg + 11.25) / 22.5) % 16

Mögliche Werte:

N, NNE, NE, ENE, E, ESE, SE, SSE,
S, SSW, SW, WSW, W, WNW, NW, NNW

Beispiel Calls¶

curl http://soaring.node01.de/api/thermal
curl http://soaring.node01.de/api/thermal?location=mfg-h
curl http://soaring.node01.de/api/locations

Architektur¶

• Datenquelle: Open-Meteo
• Caching: 30 Minuten TTL
• Score: thermal_score_v2
• Smooth: 3-Punkt-Mittel
• Forecast: 10--20 Uhr
• Current: aktuelle Stunde