GET
/api/v1/overviewDie Wasserlage einer Region
Pegel, Talsperren, Flüsse, Warnungen und Quellenzustände in einer Antwort. Der Einstieg für Karten und Übersichten.
Beispielantwort öffnenTechnische Dokumentation / Version 1
Wasserdaten.
Nachvollziehbar nutzen.
Pegel, Talsperren und Warnungen in einer gemeinsamen Schnittstelle. Jede Beobachtung behält ihre Herkunft. Fehlende Daten bleiben als fehlend erkennbar.
Ohne API-SchlüsselJSON · UTF-8Öffentliche Originalquellen
01
Schnellstart
Alle Pfade beziehen sich auf den Ursprung dieser Seite. Die Übersicht liefert eine vollständige Antwortstruktur – auch wenn einzelne Quellen gerade nicht erreichbar sind.
JavaScript · Landkreis Harz abrufen
const response = await fetch('/api/v1/overview?region=harz');
if (!response.ok) throw new Error('HTTP ' + response.status);
const data = await response.json();
// Ein HTTP 200 ist keine Aussage über die Datenfrische.
const current = data.stations.filter(station =>
station.measurement !== null && station.freshness === 'current'
);
console.log(current, data.providers);02
Regionen & Parameter
- region
- sachsen-anhalt ist der Standard. harz bezeichnet den Landkreis Harz innerhalb seiner Verwaltungsgrenze; Goslar und Nordhausen liegen außerhalb. germany zeigt die verfügbare Deutschlandabdeckung, keine vollständige Inventur.
- search
- Optional für die Pegelliste, bis 120 Zeichen. Beispiel:
search=Bode. Namen und IDs werden ohne Beachtung der Großschreibung durchsucht. - id
- Anbieter-ID aus der Antwort übernehmen, zum Beispiel
ST_579020. PEGELONLINE-UUIDs und Landes-IDs bleiben erhalten; eine ähnliche Bezeichnung ist kein gemeinsamer Schlüssel. - Zeit & Werte
- Zeitstempel nach ISO 8601 mit Zeitzone. JSON-Zahlen verwenden einen Dezimalpunkt. Einheit immer aus
unitlesen.nullbedeutet unbekannt; die Zahl0ist ein vorhandener Messwert.
03
Endpunkte
Alle Endpunkte sind lesend. Beispielantworten öffnen die tatsächliche API dieser Instanz. Vollständige Felddefinitionen enthält die OpenAPI-Spezifikation.
GET
/api/v1/stationsPegel finden
Standorte und verfügbare Messwerte. Die Suche gleicht Name, Gewässer und Anbieter-ID ab. Unterschiedliche Anbieter können denselben Standort unter eigenen IDs führen.
Beispielantwort öffnenGET
/api/v1/stations/{id}Einen Pegel lesen
ID unverändert aus der Pegelliste übernehmen; Punkte, Unterstriche und Bindestriche gehören gegebenenfalls dazu. Fehlender Messwert und fehlende Hochwasserklasse sind unabhängige Zustände.
Eine verfügbare ID aus Pegel finden einsetzen.
GET
/api/v1/stations/{id}/historyMesswerte im Zeitverlauf
Originalzeitreihen und lokal gesammelte Beobachtungen der letzten sieben Tage, soweit verfügbar. Das Zeitfenster kann kürzer sein; Lücken werden nicht mit erfundenen Messwerten gefüllt. Ein bekannter Pegel ohne Beobachtungen liefert HTTP 200 mit leerer measurements-Liste und Quellenzustand unavailable; der lokale Verlauf kann später wachsen.
Eine verfügbare ID aus Pegel finden einsetzen.
GET
/api/v1/reservoirsTalsperren und Speicher
Katalog mit Betreiber, Kapazität und tatsächlichen Betriebsdaten, soweit eine integrierte Betreiberquelle sie veröffentlicht. Bezugszeit, Einheit, Herkunft und Verfügbarkeit gehören zu den Werten. Bauliche Kapazität ist kein aktueller Stauinhalt.
Beispielantwort öffnenGET
/api/v1/warningsAmtliche Warnmeldungen
LHP-Hochwasserwarnungen über NINA, mit Gültigkeit und Quellenzustand. Auch eine erfolgreiche Antwort mit leerer Liste ist keine allgemeine Entwarnung.
Beispielantwort öffnenGET
/api/v1/forecastRegen und Modellabfluss
72 Stunden Niederschlagsprognose an ausgewählten Orten in Sachsen-Anhalt. Ergänzend tägliche GloFAS-Modellwerte für regionale Rasterpunkte; im Landkreis Harz keine ungeeigneten GloFAS-Reihen.
Beispielantwort öffnenGET
/api/v1/riversDer regionale Gewässeratlas
Flüsse von Quelle bis Mündung mit vereinfachten Verläufen und verknüpften Speichern. Die Geometrie dient der Orientierung und bildet keine vermessenen Ufer oder Überflutungsflächen ab.
Beispielantwort öffnenGET
/api/v1/sourcesQuellen und Bedingungen
Originalanbieter, Abdeckung und Zugang. Die öffentliche Lese-API überträgt keine zusätzlichen Rechte an den Daten ihrer Quellen.
Beispielantwort öffnenGET
/healthDienststatus prüfen
Liveness des API-Prozesses. Dieser Endpunkt bestätigt nicht die Verfügbarkeit der externen Datenquellen; dafür providers in der Datenantwort auswerten. Auf der Website-Domain prüft /health den Webcontainer.
Beispielantwort öffnen04
Daten richtig lesen
Messung ≠ Hochwasserklasse
measurement enthält einen Wasserstand. warningLevel beschreibt eine separat veröffentlichte LHP-Klasse. Ein Pegel kann einen aktuellen Messwert besitzen, ohne dass für ihn eine Klasse vorliegt.
Messzeit ≠ Abrufzeit
measurement.timestamp ist die Zeit der Beobachtung. fetchedAt bezeichnet den erfolgreichen Quellenabruf; generatedAt die API-Antwort. Ein neuer Abruf macht einen alten Messwert nicht aktuell.
- current
- Ein verfügbarer Pegelmesswert innerhalb des Frischefensters von zwei Stunden.
- stale
- Der Pegelmesswert ist älter oder die Aktualisierung fehlgeschlagen. Wert und ursprünglichen Zeitpunkt zusammen anzeigen.
- unavailable
- Kein verfügbarer Messwert. Als unbekannt darstellen; niemals durch 0 ersetzen oder als Entwarnung auslegen.
Die LHP-Klasse bleibt eine eigene Information
−1Keine Daten
0Kein Hochwasser
1Kleines Hochwasser
2Mittleres Hochwasser
3Großes Hochwasser
4Sehr großes Hochwasser
Diese amtliche LHP-Einteilung ist keine bundesweit einheitliche Landes-Alarmstufe. warningTimestamp gehört zur Klasse. Fehlt das Feld ganz, ist ebenfalls keine Klasse bekannt. Wasserstände beziehen sich auf den lokalen Pegelnullpunkt und sind keine Wassertiefen.
Quellenzustände und Teilverfügbarkeit
live bedeutet erfolgreich abgerufen; cached eine gespeicherte Antwort. unavailable kennzeichnet einen Ausfall oder eine unvollständige Quelle, reference einen redaktionellen oder historischen Katalog. stale: true markiert veraltete Cache-Daten nach einer fehlgeschlagenen Aktualisierung. Den jeweiligen message-Text mit anzeigen: HTTP 200 kann teilweise ausgefallene Quellen enthalten.
Talsperren: Bezugsgröße und Datenstand
Stauinhalt, Wasserstand, Zufluss und Abgabe sind verschiedene Betriebsgrößen. Prozentangaben beziehen sich auf eine ausdrücklich benannte Kapazität und sind keine Hochwasserwarnung. Die tägliche TSB-Meldung wird nach 36 Stunden als veraltet eingeordnet; HWW-Werte nach zwei Stunden. Eine fehlgeschlagene Aktualisierung wird unabhängig davon kenntlich gemacht. Jeder Parameter hat einen eigenen Messzeitpunkt. Fehlende Werte werden nicht aus der Kapazität oder benachbarten Pegeln geschätzt; folgen Sie bei Datenlücken dem angegebenen Betreiberlink.
Modelle sind keine Pegelbeobachtungen
Die Regenklassen low, elevated und high sind eine erläuterte Heuristik für ein 72-Stunden-Fenster. Sie sind keine amtlichen Warnstufen. completeness unterscheidet vollständige und lückenhafte Prognosen; fehlende Modellwerte bleiben null. GloFAS-Tageswerte sind modellierte Abflüsse in m³/s an regionalen Rasterpunkten ohne fachlich validierte Flusszuordnung. Schwellen, Quellen und Grenzen stehen in methodology.
05
Fehler & Betrieb
Fehlerantworten haben ein einheitliches Format. Für die Anzeige ist message vorgesehen; Programme können code und den HTTP-Status auswerten.
{ "error": {
"code": "INVALID_REQUEST",
"message": "Ungültige Anfrageparameter."
} }| Status | Bedeutung & nächster Schritt |
|---|---|
| 400 | Parameter ungültig. Region, ID und Suchlänge prüfen. |
| 404 | Endpunkt oder Standort unbekannt. Bekannte Pegel ohne verfügbare Beobachtungen liefern eine leere Zeitreihe mit HTTP 200 und Quellenzustand unavailable. |
| 429 | Anfragelimit erreicht: 120 Anfragen pro Minute und Quell-IP. Kurz warten, Retry-After beachten und Antworten zwischenspeichern. |
| 500 | Interner Fehler. Zeitversetzt erneut versuchen; nicht in einer schnellen Schleife wiederholen. |
Cache und lokale Beobachtungen
Der Standardcache beträgt fünf Minuten. Erfolgreich empfangene Beobachtungen und Metadaten werden lokal in SQLite gespeichert; historische Reihen wachsen ab Beginn des Betriebs. Es gibt keine künstliche Vorgeschichte. Die Aufbewahrung beträgt standardmäßig 90 Tage. Quelldaten werden außerdem regelmäßig abgerufen, ohne dass eine Seite geöffnet sein muss.
Der Providercache bleibt nach Quellenfehlern für Pegel höchstens eine Stunde und für Warnungen höchstens 15 Minuten verfügbar, jeweils ausdrücklich als veraltet gekennzeichnet. Danach kann der letzte lokal gespeicherte Pegelwert mit ursprünglichem Messzeitpunkt und freshness: stale weiter angezeigt werden. Abgelaufene Warnungen werden verworfen. Betreiberwerte für Talsperren können länger als gekennzeichneter letzter Stand verbleiben (TSB bis 48 Stunden, HWW bis 24 Stunden nach Abruf). Eine gespeicherte Beobachtung kann zusätzlich Teil eines historischen Verlaufs sein. Die Speicherung macht sie nicht zu einem aktuellen Messwert.
Abdeckung und Weiterverwendung
PEGELONLINE ergänzt Bundeswasserstraßen, LHP die Landespegel und Hochwasserklassen, LHW weitere Standorte in Sachsen-Anhalt und NLWKN zusätzliche Messwerte und Originalzeitreihen in Niedersachsen. Nicht jedes Landesmessnetz ist vollständig angebunden. Die Referenzstandorte enthalten bei Quellenausfällen keine historischen Messwerte oder Warnklassen. Quellenbedingungen und Datenherkunft bleiben bei Weiterverwendung verbindlich; Open-Meteos schlüsselloser Dienst ist für nichtkommerzielle Nutzung unter Fair-Use-Bedingungen vorgesehen.