From 489a026b9c5eb56b737397cd8892272e352fd11f Mon Sep 17 00:00:00 2001 From: Matthias Jacob Date: Tue, 27 Oct 2026 23:37:15 +0100 Subject: [PATCH] docs: document flood_alert_level values and placeholder filtering Add observed values and expected Alarmstufe levels to README and OpenAPI schema. --- README.md | 17 +++++++++++++++-- api/app.py | 21 +++++++++++++++++++-- 2 files changed, 34 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1b36527..7a4e49d 100644 --- a/README.md +++ b/README.md @@ -117,12 +117,25 @@ Beispielantwort: | `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 | +| `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`. @@ -131,7 +144,7 @@ Fehler der API enthalten ein JSON-Objekt mit dem Feld `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` | +| `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` | diff --git a/api/app.py b/api/app.py index 3021642..ee3540a 100644 --- a/api/app.py +++ b/api/app.py @@ -1,6 +1,6 @@ from fastapi import FastAPI, HTTPException from fastapi.responses import JSONResponse, RedirectResponse -from pydantic import BaseModel +from pydantic import BaseModel, Field import feedparser import re import html @@ -54,7 +54,24 @@ class PegelEntry(BaseModel): title: str | None water_level_cm: float | None flow_m3s: float | None - flood_alert_level: str | None + flood_alert_level: str | None = Field( + description=( + "Meldestufe als Text. Beobachtete Werte: `Niedrigwasser`, `Kein Hochwasser`, " + "`Kein Hochwassermeldepegel` (Pegel ohne Hochwassermeldefunktion). 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", + ], + ) class PegelResponse(BaseModel): station_id: str