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: https://sachsen-pegel-proxy.vercel.app
Interaktive Swagger-Dokumentation: https://sachsen-pegel-proxy.vercel.app/docs
Alternatives ReDoc: https://sachsen-pegel-proxy.vercel.app/redoc
OpenAPI-Schema: https://sachsen-pegel-proxy.vercel.app/openapi.json

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
`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.

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

API: http://127.0.0.1:8000/api/pegel
Swagger: http://127.0.0.1:8000/docs
ReDoc: http://127.0.0.1:8000/redoc
OpenAPI: http://127.0.0.1:8000/openapi.json

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