# Sachsen Pegel Proxy Kleiner FastAPI-Dienst, der Pegelstationen und Messwerte aus dem sächsischen Hochwasser- und Wasserstands-Informationssystem (HWIMS) als JSON bereitstellt. Die Daten stammen aus der offiziellen Stationsübersicht und den RSS-Feeds der Stationen. ## Live-Dienst und API-Dokumentation - API-Basis-URL: - Interaktive Swagger-Dokumentation: - Alternatives ReDoc: - OpenAPI-Schema: Alle API-Antworten sind JSON. Die Endpunkte benötigen keine Authentifizierung. ## Endpunkte | Methode | Pfad | Beschreibung | | --- | --- | --- | | `GET` | `/api/pegel` | Verfügbare Pegelstationen auflisten | | `GET` | `/api/pegel/{pegel_id}` | Messwerte und Feed-Historie einer Station abrufen | ### Stationsliste `GET /api/pegel` Optional kann die Anzahl der zurückgegebenen Stationen mit `limit` begrenzt werden: ```text GET /api/pegel?limit=5 ``` `limit` muss eine positive ganze Zahl sein. `count` ist die Anzahl der tatsächlich zurückgegebenen Elemente; `total_available` gibt die Gesamtzahl der gefundenen Stationen an und wird durch `limit` nicht verändert. Beispielantwort: ```json { "count": 1, "total_available": 312, "items": [ { "station_id": "560021", "station_title": "Golzern 1 / Vereinigte Mulde", "source": "https://www.umwelt.sachsen.de/umwelt/infosysteme/hwims/portal/web/feed/wasserstand-pegel-560021" } ], "source": "https://www.umwelt.sachsen.de/umwelt/infosysteme/hwims/portal/web/wasserstand-uebersicht", "fetched_at": "2026-05-05T00:15:00+00:00" } ``` | Feld | Typ | Bedeutung | | --- | --- | --- | | `count` | integer | Anzahl der Elemente in `items` | | `total_available` | integer | Gesamtzahl der gefundenen Stationen vor Anwendung von `limit` | | `items` | array | Stationen mit `station_id`, `station_title` und RSS-Feed-URL `source` | | `station_title` | string oder `null` | Stationsname, sofern er aus der Quelle ermittelt werden konnte | | `source` | string | Verwendete Discovery-Quelle; beim Cache-Fallback der Wert `"cache"` | | `fetched_at` | string | Zeitpunkt der Antworterstellung als ISO-8601-Zeitstempel | | `warnings` | array, optional | Hinweise auf Fehler der Discovery-Quelle, wenn ein Cache-Fallback verwendet wurde | | `cache_fetched_at` | string, optional | Zeitpunkt, an dem der verwendete Discovery-Cache geladen wurde; nur beim Cache-Fallback | Die Stationsübersicht wird intern 15 Minuten zwischengespeichert. Ist die Quelle vorübergehend nicht erreichbar, liefert der Dienst vorhandene Cache-Daten mit `warnings` und `cache_fetched_at`. Gibt es keinen verwendbaren Cache, antwortet der Endpunkt mit HTTP `502`. ### Messwerte einer Station `GET /api/pegel/{pegel_id}` Die Pegel-ID muss aus mindestens sechs Ziffern bestehen. Der Endpunkt liefert alle Einträge, die im RSS-Feed der Station verfügbar sind. `latest` ist der neueste Messwert und entspricht dem ersten Eintrag in `entries`. ```text GET /api/pegel/560021 ``` Beispielantwort: ```json { "station_id": "560021", "station_title": "Golzern 1 / Vereinigte Mulde", "count": 2, "latest": { "timestamp": "2026-05-05T02:15:00+02:00", "title": "Wasserstand und Durchfluss für 05.05.2026 02:15 Uhr (MESZ)", "water_level_cm": 98.0, "flow_m3s": 20.8, "flood_alert_level": "Kein Hochwasser" }, "entries": [ { "timestamp": "2026-05-05T02:15:00+02:00", "title": "Wasserstand und Durchfluss für 05.05.2026 02:15 Uhr (MESZ)", "water_level_cm": 98.0, "flow_m3s": 20.8, "flood_alert_level": "Kein Hochwasser" }, { "timestamp": "2026-05-05T02:00:00+02:00", "title": "Wasserstand und Durchfluss für 05.05.2026 02:00 Uhr (MESZ)", "water_level_cm": 98.0, "flow_m3s": 20.8, "flood_alert_level": "Kein Hochwasser" } ], "source": "https://www.umwelt.sachsen.de/umwelt/infosysteme/hwims/portal/web/feed/wasserstand-pegel-560021", "fetched_at": "2026-05-05T00:16:00+00:00" } ``` | Feld | Typ | Bedeutung | | --- | --- | --- | | `station_id` | string | Angefragte Pegel-ID | | `station_title` | string oder `null` | Stationsname aus dem RSS-Feed | | `count` | integer | Anzahl der vom Feed gelieferten Einträge | | `latest` | Objekt | Neuester Eintrag; identisch mit `entries[0]` | | `entries` | array | Feed-Einträge in der Reihenfolge der Quelle, normalerweise neueste zuerst | | `timestamp` | string oder `null` | Messzeitpunkt als ISO-8601 mit Zeitzonenoffset | | `title` | string oder `null` | Originaltitel des RSS-Eintrags | | `water_level_cm` | number oder `null` | Wasserstand in Zentimetern | | `flow_m3s` | number oder `null` | Durchfluss in Kubikmetern pro Sekunde | | `flood_alert_level` | string oder `null` | Meldestufe als Text, siehe unten | | `source` | string | URL des verwendeten RSS-Feeds | | `fetched_at` | string | Zeitpunkt des Abrufs durch die API als UTC-Zeitstempel | Ein Messwert ist `null`, wenn er im jeweiligen RSS-Eintrag fehlt oder nicht erkannt werden kann. Zeitstempel werden, wenn möglich, aus der Uhrzeit im RSS-Titel gebildet; andernfalls verwendet die API das Datumsfeld des Feeds. Sommer- und Winterzeit werden als Offset berücksichtigt. Einträge ohne Wasserstand und ohne Durchfluss (Platzhalter der Quelle für noch nicht verfügbare Messwerte, Meldestufe „Keine aktuellen Daten verfügbar“) werden herausgefiltert. `latest` ist daher der neueste Eintrag mit mindestens einem Messwert und kann vom neuesten Eintrag der Quelle abweichen. ### Werte von `flood_alert_level` | Wert | Bedeutung | | --- | --- | | `Niedrigwasser` | Niedrigwasser | | `Kein Hochwasser` | Hochwassermeldepegel, Richtwerte nicht erreicht | | `Kein Hochwassermeldepegel` | Pegel ohne Hochwassermeldefunktion | | `Alarmstufe 1` bis `Alarmstufe 4` | Richtwert der jeweiligen Alarmstufe überschritten (1 Meldedienst, 2 Kontrolldienst, 3 Wachdienst, 4 Hochwasserabwehr) | Die ersten drei Werte wurden in den Feeds aller Pegel beobachtet. Die Alarmstufen stammen aus der Legende der HWIMS-Übersichtsseite; ihre genaue Schreibweise im RSS-Feed ist nicht verifiziert, da sie bei der Prüfung nicht aufgetreten sind. Clients sollten unbekannte Werte tolerieren. ## Fehlerantworten Fehler der API enthalten ein JSON-Objekt mit dem Feld `detail`. | HTTP-Status | Ursache | Beispiel für `detail` | | --- | --- | --- | | `400` | `limit` ist kleiner oder gleich null | `Ungültiger limit-Parameter` | | `400` | Pegel-ID hat nicht mindestens sechs Ziffern | `Ungültige Pegel-ID` | | `404` | Feed enthält keine Einträge mit Messwerten für die Pegel-ID | `Keine Daten gefunden` | | `422` | Query-Parameter kann nicht als Zahl interpretiert werden | FastAPI-Validierungsfehler | | `502` | Stationsübersicht nicht erreichbar und kein Cache vorhanden | `Upstream-Discovery nicht verfügbar` | ## Beispiele Mit `curl`: ```bash curl "https://sachsen-pegel-proxy.vercel.app/api/pegel?limit=5" curl "https://sachsen-pegel-proxy.vercel.app/api/pegel/560021" ``` ### Home Assistant ```yaml rest: - resource: "https://sachsen-pegel-proxy.vercel.app/api/pegel/560021" scan_interval: 300 sensor: - name: "Pegel Golzern Wasserstand" value_template: "{{ value_json.latest.water_level_cm }}" unit_of_measurement: "cm" json_attributes_path: "$.latest" json_attributes: - timestamp - flow_m3s - flood_alert_level ``` ## Lokale Entwicklung ```bash python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt uvicorn api.app:app --reload ``` Lokal erreichbare Endpunkte: - API: - Swagger: - ReDoc: - OpenAPI: ## Bereitstellung auf Vercel Das Repository enthält keine plattformspezifische Deployment-Konfiguration. Das Projekt kann mit Vercel verbunden und anschließend beispielsweise mit der CLI bereitgestellt werden: ```bash npx vercel npx vercel --prod ``` Nach der Bereitstellung beide API-Endpunkte und `/docs` prüfen. ## Datenquelle und Hinweise Die Messwerte werden von der offiziellen Website des Freistaats Sachsen bereitgestellt: - Übersicht: - Beispiel-Feed: Verfügbarkeit und Richtigkeit der Quelldaten werden nicht garantiert. Änderungen am Aufbau der HWIMS-Seiten oder RSS-Feeds können die Verarbeitung beeinträchtigen. Dieses Projekt ist nicht mit dem Freistaat Sachsen verbunden. ## Lizenz MIT