{"openapi":"3.1.0","info":{"title":"Sachsen Pegel Proxy API","description":"Liefert Stationslisten und Wasserstandsmessungen des sächsischen Hochwasser- und Wasserstands-Informationssystems (HWIMS) als JSON.\n\nDie API liest die offiziellen HWIMS-Übersichts- und RSS-Quellen aus. Messwerte und Stationsnamen können `null` sein, wenn sie in der Quelldatei fehlen oder nicht erkannt werden. Zeitstempel werden als ISO-8601-Werte mit Zeitzoneninformation ausgegeben.\n\nDie interaktive Dokumentation steht unter `/docs`, das OpenAPI-Schema unter `/openapi.json` bereit.","version":"1.0.0"},"paths":{"/api/pegel":{"get":{"tags":["Pegel"],"summary":"Pegelstationen auflisten","description":"Liefert die auf der HWIMS-Übersichtsseite gefundenen Pegelstationen. Mit `limit` lässt sich die zurückgegebene Liste begrenzen; `total_available` enthält weiterhin die Gesamtzahl. Der Index wird 15 Minuten zwischengespeichert. Ist die Quelle nicht erreichbar, wird ein vorhandener Cache verwendet und die Antwort enthält `warnings` sowie `cache_fetched_at`. Ohne verfügbaren Cache wird HTTP 502 geliefert.","operationId":"list_pegel_api_pegel_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit"}}],"responses":{"200":{"description":"Stationsliste mit Quelle und Abrufzeitpunkt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PegelIndexResponse"}}}},"400":{"description":"`limit` ist keine positive Zahl."},"502":{"description":"Die Discovery-Quelle ist nicht verfügbar und es gibt keinen Cache."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/pegel/{pegel_id}":{"get":{"tags":["Pegel"],"summary":"Messwerte eines Pegels abrufen","description":"Liefert alle im RSS-Feed verfügbaren Einträge einer Station. Einträge ohne Wasserstand und ohne Durchfluss (Platzhalter der Quelle für noch nicht verfügbare Messwerte) werden herausgefiltert. `latest` ist der neueste verbleibende Eintrag und entspricht `entries[0]`; die Reihenfolge von `entries` folgt dem Feed (neueste zuerst). Pegel-IDs bestehen aus mindestens sechs Ziffern. Einzelne fehlende Messwerte werden als `null` ausgegeben. `alarm_thresholds` wird zusätzlich von der Pegel-Detailseite ermittelt und 24 Stunden zwischengespeichert; ist sie nicht erreichbar, wird ein vorhandener Cache verwendet oder `null` geliefert, ohne die übrige Antwort zu beeinträchtigen.","operationId":"get_pegel_api_pegel__pegel_id__get","parameters":[{"name":"pegel_id","in":"path","required":true,"schema":{"type":"string","title":"Pegel Id"}}],"responses":{"200":{"description":"Stationsmetadaten, neuester Messwert und Feed-Historie.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PegelResponse"}}}},"400":{"description":"Die Pegel-ID besteht nicht aus mindestens sechs Ziffern."},"404":{"description":"Für diese Pegel-ID enthält der RSS-Feed keine Einträge mit Messwerten."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AlarmThreshold":{"properties":{"level":{"type":"integer","title":"Level","description":"Alarmstufe, 1 bis 4."},"water_level_cm":{"type":"integer","title":"Water Level Cm","description":"Richtwasserstand dieser Alarmstufe in Zentimetern."}},"type":"object","required":["level","water_level_cm"],"title":"AlarmThreshold"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"PegelEntry":{"properties":{"timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timestamp"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"water_level_cm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Water Level Cm"},"flow_m3s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Flow M3S"},"flood_alert_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Flood Alert Level","description":"Meldestufe als Text. Beobachtete Werte: `Niedrigwasser`, `Kein Hochwasser`, `Kein Hochwassermeldepegel` (der Pegel wird nicht für amtliche Hochwassermeldungen bzw. -steuerung genutzt; für solche Pegel liefert `alarm_thresholds` `null`). Bei Hochwasser sind laut HWIMS-Legende `Alarmstufe 1` bis `Alarmstufe 4` zu erwarten; deren genaue Schreibweise im Feed ist nicht verifiziert. Clients sollten unbekannte Werte tolerieren.","examples":["Niedrigwasser","Kein Hochwasser","Kein Hochwassermeldepegel","Alarmstufe 1","Alarmstufe 2","Alarmstufe 3","Alarmstufe 4"]}},"type":"object","required":["timestamp","title","water_level_cm","flow_m3s","flood_alert_level"],"title":"PegelEntry"},"PegelIndexResponse":{"properties":{"count":{"type":"integer","title":"Count"},"total_available":{"type":"integer","title":"Total Available"},"items":{"items":{"$ref":"#/components/schemas/PegelStation"},"type":"array","title":"Items"},"source":{"type":"string","title":"Source"},"fetched_at":{"type":"string","title":"Fetched At"},"warnings":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Warnings"},"cache_fetched_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cache Fetched At"}},"type":"object","required":["count","total_available","items","source","fetched_at"],"title":"PegelIndexResponse"},"PegelResponse":{"properties":{"station_id":{"type":"string","title":"Station Id"},"station_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Station Title"},"count":{"type":"integer","title":"Count"},"latest":{"$ref":"#/components/schemas/PegelEntry"},"entries":{"items":{"$ref":"#/components/schemas/PegelEntry"},"type":"array","title":"Entries"},"alarm_thresholds":{"anyOf":[{"items":{"$ref":"#/components/schemas/AlarmThreshold"},"type":"array"},{"type":"null"}],"title":"Alarm Thresholds","description":"Richtwasserstände der Alarmstufen 1 bis 4 in Zentimetern, von der Pegel-Detailseite ermittelt. `null`, wenn der Pegel keine Hochwassermeldefunktion hat (siehe `flood_alert_level`) oder die Werte nicht ermittelt werden konnten."},"source":{"type":"string","title":"Source"},"fetched_at":{"type":"string","title":"Fetched At"}},"type":"object","required":["station_id","station_title","count","latest","entries","alarm_thresholds","source","fetched_at"],"title":"PegelResponse"},"PegelStation":{"properties":{"station_id":{"type":"string","title":"Station Id"},"station_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Station Title"},"source":{"type":"string","title":"Source"}},"type":"object","required":["station_id","station_title","source"],"title":"PegelStation"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"Pegel","description":"Entdecken von Pegelstationen und Abrufen ihrer Messwerte."}]}