cyroxx/sachsen_pegel_proxy
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
489a026b9c5eb56b737397cd8892272e352fd11f
sachsen_pegel_proxy/README.md
T
Matthias Jacob 489a026b9c docs: document flood_alert_level values and placeholder filtering 
Add observed values and expected Alarmstufe levels to README and OpenAPI schema.
2026-10-27 23:37:15 +01:00

8.6 KiB
Raw Blame History

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

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:

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:

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

GET /api/pegel/560021

Beispielantwort:

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

curl "https://sachsen-pegel-proxy.vercel.app/api/pegel?limit=5"
curl "https://sachsen-pegel-proxy.vercel.app/api/pegel/560021"

Home Assistant

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

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:

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:

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:

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

Reference in new issue View Git Blame Copy Permalink