PEGELONLINE REST-API Dokumentation

• Überblick
• Ressourcen
  • Station
  • Water
  • Measurement
  • Timeseries
  • CurrentMeasurement
  • Vorhersagen
• Allgemeine URL-Parameter
• Caching
• Kompression
• Versionierung
• Fehlermeldungen
• Umgang mit Sonderzeichen in URLs

Überblick

PEGELONLINE REST-API ist eine einfache Schnittstelle, um unterschiedliche gewässerkundliche Informationen von PEGELONLINE abzurufen.

Die API ist ressourcenorientiert, d.h. es sind eine Reihe von Ressourcen definiert, welche über HTTP-URLs eindeutig adressierbar sind. Die Ressourcen können unterschiedlich repräsentiert werden, d.h. in unterschiedlichen Formaten dargestellt werden. Aktuell wird JSON und bei den gemessenen Rohdaten zusätzlich CSV und eine Diagrammdarstellung als PNG unterstützt.

Um die Datenübertragung zu beschleunigen oder ganz zu vermeiden wird HTTP-Kompression und clientseitiges Caching unterstützt.

Die API ist unterhalb von https://www.pegelmobil.de/webservices/rest-api/v2 adressierbar.

Es ist keine Authentifizierung oder Autorisierung erforderlich, um die PEGELONLINE REST-API zu nutzen.

Ressourcen

Station

Hierbei handelt es sich um die Pegel bzw. die Messstellen von PEGELONLINE.

Zugriff auf die Stationen inklusive verschiedener untergeordneter Daten:

/stations.json	Alle Pegel sortiert nach Gewässername und Messstellenname.
/stations.json?includeTimeseries=true	Alle Pegel inklusive Informationen zu den Zeitreihen.
/stations.json?includeTimeseries=true&includeCurrentMeasurement=true	Alle Pegel inklusive Informationen zu den Zeitreihen mit dem aktuell gemessenen Wert.
/stations.json?includeTimeseries=true&includeCharacteristicValues=true	Alle Pegel inklusive Informationen zu den Zeitreihen mit den kennzeichnenden Wasserstände.
/stations.json?includeForecastTimeseries=true&hasTimeseries=WV	Alle Pegel mit Vorhersagezeitreihen ("Wasserstandvorhersage", "WV"). Weitere Informationen zu den Vorhersagen sind im Abschnitt Vorhersagen zu finden.

Zugriff auf bestimmte Stationen:

/stations/593647aa-9fea-43ec-a7d6-6476a76ae868.json	Zugriff auf einen Pegel per UUID. Die UUIDs sind in der Pegeltabelle aufgelistet oder können aus /stations.json entnommen werden.
/stations.json?waters=RHEIN,MAIN	Alle Pegel bestimmter Gewässer.
/stations.json?ids=593647aa-9fea-43ec-a7d6-6476a76ae868,70272185-b2b3-4178-96b8-43bea330dcae	Mehrere Pegel per UUIDs.
/stations.json?timeseries=Q&includeTimeseries=true	Nur Pegel mit deren Q-Zeitreihen (Abflusszeitreihen).
/stations.json?hasTimeseries=Q&includeTimeseries=true	Pegel, welche eine Q-Zeitreihe besitzen, mit allen Zeitreihen des Pegels.

Spezialabfragen:

/stations.json?latitude=52.44&longitude=13.57&radius=30	Pegel innerhalb eines Radius an einer geografischen Position. Koordinaten in WGS84 in Dezimalnotation.
/stations.json?fuzzyId=berlin	Pegel, welche im Namen 'Berlin' enthalten.
/stations.json?waters=RHEIN&km=680&radius=50	Pegel des Gewässers Rhein im Umkreis eines bestimmten Flusskilometers.

Erläuterung der Attribute der Ressource Station:

uuid	Eindeutige unveränderliche ID.
number	Pegelnummer
shortname	Pegelname (max. 40 Zeichen)
longname	Pegelname (max. 255 Zeichen)
km	Flusskilometer
agency	Wasserstraßen- und Schifffahrtsamt
longitude	Längengrad in WGS84 Dezimalnotation
latitude	Breitengrad in WGS84 Dezimalnotation
water	Angaben zum Gewässer

Measurement

Hierbei handelt es sich um die gemessenen Rohwerte. Es können Daten für die letzten 31 Tage bezogen werden.

Die Messwerte können in JSON bezogen werden, im CSV-Format oder als Diagramm visualisiert werden.

Bei der Diagrammvisualisierung der Messwerte werden bei einer Reihe von Küstenpegeln zusätzlich astronomische Gezeitenganglinien dargestellt. Die Ganglinien werden gestrichelt in einem abgeschwächten Farbton gerendert.
Die Gezeitenvorausberechnungen werden vom Bundesamt für Seeschifffahrt und Hydrographie zur Verfügung gestellt.

Zugriff auf die Ressource Measurement:

/stations/593647aa-9fea-43ec-a7d6-6476a76ae868/W/measurements.json	Wasserstandsrohdaten des Pegels Bonn der letzten 10 Tage (Standardzeitraum).
/stations/593647aa-9fea-43ec-a7d6-6476a76ae868/W/measurements.json?start=Sat Oct 19 09:00:00 CEST 2024+01:00&end=Thu Oct 31 16:00:00 CET 2024+01:00	Wasserstandsrohdaten des Pegels Bonn zwischen dem Sat Oct 19 09:00:00 CEST 2024 Uhr bis zum Thu Oct 31 16:00:00 CET 2024 Uhr. Die Notation der Zeitstempel erfolgt nach ISO_8601. Der Parameter end kann auch weggelassen werden. In diesem Fall wird der aktuelle Zeitpunkt angenommen.
/stations/593647aa-9fea-43ec-a7d6-6476a76ae868/W/measurements.json?start=P8D	Die Messwerte der letzten 8 Tage. Hier wird für start eine ISO_8601 Period (P8D) verwendet. Um zum Beispiel die Daten der letzen 6 Tage, 10 Stunden und 15 Minuten anzufordern würde man P6DT10H15M verwenden.
/stations/593647aa-9fea-43ec-a7d6-6476a76ae868/W/measurements.csv?contentType=text/plain	Abruf der Messwerte im CSV-Format. Die Zeitstempel, Messwerte und der CSV-Trenner sind so formatiert, dass sie direkt von der Excel-Tabellenkalkulation erkannt werden. Mit der Angabe contentType=text/plain wird das CSV direkt im Browser dargestellt und nicht als Datei heruntergeladen. Der Parameter ist für den CSV-Abruf nicht notwendig.
/stations/593647aa-9fea-43ec-a7d6-6476a76ae868/W/measurements.png?start=P20D&width=900&height=400	Eine grafische Darstellung der Messwerte der letzten 20 Tage in einer bestimmten Höhe und Breite.
/stations/593647aa-9fea-43ec-a7d6-6476a76ae868/W/measurements.png?start=P20D&width=700&height=200&enableSecondaryYAxis=true	Eine grafische Darstellung mit zweiter Y-Achse auf der rechten Seite.
/stations/8727ebfd-e2e1-43da-ab3d-fee48cff9acc/W/measurements.png?start=P1D&end=P1D&width=900&height=400	Eine grafische Darstellung des Küstenpegels BORKUM FISCHERBALJE 24 Stunden vor und 24 Stunden nach dem aktuellen Zeitpunkt. Es wird zusätzlich eine astronomische Gezeitenganglinie angezeigt.

Erläuterung der Attribute der Ressource Measurement:

timestamp	Zeitpunkt kodiert im ISO_8601 Format.
value	Wert als Dezimalzahl in der Einheit, welche durch die Timeseries der Station vorgegeben ist.

Water

Hiermit können alle in PEGELONLINE verfügbaren Gewässer, optional mit untergeordneten Pegeln und Zeitreihen bezogen werden.

Zugriff auf die Ressource Water:

/waters.json	Alle Gewässer.
/waters.json?includeStations=true	Alle Gewässer mit untergeordneten Pegeln. Wie bei Stations können auch hier weitere untergeordnete Daten mit den Parametern includeTimeseries, includeCurrentMeasurement und includeCharacteristicValues angefordert werden.
/waters.json?ids=SAALE,ELBE&stations=ace7d4b0-33e5-46db-a41d-2fa7a321f67a,4626f6bc-494b-4a51-8c10-b47a32e87790,1edc5fa4-88af-47f5-95a4-0e77a06fe8b1,de4cc1db-51cb-4b62-bee2-9750cbe4f5c4& timeseries=W&includeTimeseries=true&includeStations=true	Gewässer mit untergeordneten Stationen und Zeitreihen. Beschränkung erfolgt auf die Gewässer Saale und Elbe, auf die Stationen Nienburg, Roepzig, Dessau und Storkau, sowie auf Wasserstandszeitreihen.

Erläuterung der Attribute der Ressource Waters:

shortname	Kurzbezeichnung, maximal 40 Zeichen.
longname	Langbezeichnung, maximal 255 Zeichen.

Timeseries

Diese Ressource enthält Informationen zu den Zeitreihen. Sie kann mit Hilfe des URL-Parameters includeTimeseries bei den Ressourcen Stations und Waters mit angefordert werden.
Eine eigenständige Abfrage ist auch möglich.

Zugriff auf die Ressource Timeseries:

/stations.json?includeTimeseries=true	Stationen mit untergeordneten Zeitreihen.
/stations/d2d025a2-e691-4986-b9c4-923e7f1a47c3/W.json?includeCurrentMeasurement=true	Die Wasserstandszeitreihe des Pegels Ketzin mit dem aktuelle Messwert.
/stations/d2d025a2-e691-4986-b9c4-923e7f1a47c3/W.json?includeCharacteristicValues=true	Die Wasserstandszeitreihe des Pegels Ketzin mit kennzeichnenden Wasserständen.

Erläuterung der Attribute der Ressource Timeseries:

shortname	Kurzbezeichnung.
longname	Langbezeichnung.
unit	Maßeinheit
equidistance	Abstand der Messwerte in Minuten.

Erläuterung der Attribute der Unterressource Gauge Zero (Es handelt sich hierbei um den Pegelnullpunkt):

unit	Einheit des Pegelnullpunkts (immer in Metern über einem Normalhöhennull)
value	Höhe als Dezimalwert
validFrom	Beginn der Gültigkeit. ISO_8601 Datum.

Erläuterung der Attribute der Unterressource Characteristic Value (Es handelt sich hierbei um kennzeichnende Wasserstände und Pegelkennwerte):

shortname	Kurzbezeichnung, maximal 40 Zeichen.
longname	Langbezeichnung, maximal 255 Zeichen.
unit	Maßeinheit.
value	Wert als Dezimalzahl.
validFrom/occurences/timespanStart/timespanEnd	Drückt aus ab welchem Zeitpunkt (validFrom), an welchen Zeitpunkten (occurences) oder in welchem Zeitraum (timespanStart, timespanEnd) ein Kennwert gültig ist. Die Zeitstempel werden in ISO_8601 kodiert und können sich auf ein Jahr (z.B. '2002'), auf einen Monat (z.B. '2002-10') oder auf ein Datum (z.B. '2002-10-01') beziehen.

Erläuterung der Attribute der Unterressource Comment
Liegt z.B. eine Fehlfunktion oder ein Ausfall an der Messstelle vor, so ist dies hier mit einer Textbeschreibung erläutert.

shortDescription	Kurzbeschreibung, maximal 55 Zeichen.
longDescription	Langbeschreibung, maximal 500 Zeichen.

CurrentMeasurement

Diese Ressource enthält den aktuellen Wert. Sie kann als Unterresource von Timeseries angefordert werden oder auch eigenständig.

Zugriff auf die Ressource CurrentMeasurement:

/stations/d2d025a2-e691-4986-b9c4-923e7f1a47c3/W.json?includeCurrentMeasurement=true	Die Wasserstandszeitreihe des Pegels Ketzin mit dem aktuelle Messwert.
/stations/d2d025a2-e691-4986-b9c4-923e7f1a47c3/W/currentmeasurement.json	Den aktuellen Wert von Ketzin.

Erläuterung der Attribute der Ressource CurrentMeasurement

timestamp	Zeitpunkt kodiert im ISO_8601 Format.
value	Wert als Dezimalzahl in der Einheit, welche durch die Timeseries der Station vorgegeben ist.
stateMnwMhw und stateNswHsw	Diese Attribute sind nur bei Wasserständen vorhanden. Sie setzen den aktuellen Wasserstand entweder mit den mittleren niedrigsten Werten (MNW) und den mittleren höchsten Werten (MHW) in Beziehung (stateMnwMhw) oder mit dem höchsten Schifffahrtswasserstand (stateNswHsw). Die Attribute stateMnwMhw und stateNswHsw können folgende Werte annehmen: low: Aktueller Wasserstand unterhalb/gleich des MNW (nur stateMnwMhw) normal: Aktueller Wasserstand zwischen MNW und MHW bzw. zwischen 0 und HSW high: Aktueller Wasserstand oberhalb/gleich MHW bzw. HSW unknown: Unbekannt, da MHW/MNW bzw. HSW für Zeitreihe nicht vorhanden commented: Fehlfunktion oder Störung. Siehe Subressource comment in Ressource Timeseries out-dated: Aktueller Wasserstand veraltet (älter als 25 Stunden) Siehe auch die Hilfe zu den Grenzwerten.

Vorhersagen

Vorhersagen des Wasserstands werden vom Wasserstraßen- und Schifffahrtsamt Elbe, der Bundesanstalt für Gewässerkunde, der Hochwasservorhersagezentrale Rheinland-Pfalz und dem Landesbetrieb für Hochwasserschutz und Wasserwirtschaft Sachsen-Anhalt erstellt.

Die Vorhersagen sind nur bei einigen Stationen abrufbar. Informationen zu den Vorhersagezeitreihen lassen sich mittels des Query-Parameters includeForecastTimeseries=true einblenden. Beispiel für Station Kaub: /stations/1d26e504-7f9e-480a-b52c-5932be6549ab.json?includeForecastTimeseries=true. Neben den bei unter Timeseries erläuterten Attributen tauchen hier noch weitere auf.

start	Ab wann existieren für diese Station Vorhersagen. Der Zeitpunkt ist kodiert im ISO_8601 Format.
end	Bis zu welchem Zeitpunkt existieren für diese Station Vorhersagen. Der Zeitpunkt ist kodiert im ISO_8601 Format.
comment	Hier wird aufgeführt, wann und von wem die Vorhersagen erstellt worden sind.

Der Abruf der Vorhersagen erfolgt über die Zeitreihe WV (Wasserstandvorhersagen). Eine Beispielabfrage für den Pegel Kaub sieht folgendermaßen aus: /stations/1d26e504-7f9e-480a-b52c-5932be6549ab/WV/measurements.json Die Abfrage lässt sich mit den bei Measurement beschriebenen Parametern start und end zeitlich weiter einschränken. Ohne zeitliche Einschränkung wie im Beispiel werden alle verfügbaren Vorhersagen angezeigt.

Die Vorhersagen können auch im CSV-Format abgerufen werden: /stations/1d26e504-7f9e-480a-b52c-5932be6549ab/WV/measurements.csv

Erläuterung der Attribute der Vorhersagen:

initialized	Zeitpunkt, an dem die Vorhersage erstellt wurde, im ISO_8601 Format kodiert.
timestamp	Zeitpunkt der Vorhersage im ISO_8601 Format kodiert.
value	Wert als Dezimalzahl in der Einheit Zentimeter.
type	Entweder forcast oder estimate. Bei forecast handelt es sich um eine Wasserstandsvorhersage mit größerer Genauigkeit, welche näher in der Zukunft liegt, üblicherweise bis zu 48 Stunden. Bei estimate handelt es sich um eine Abschätzung mit geringerer Genauigkeit, die üblicherweise für mehr als 48 Stunden in der Zukunft prognostiziert worden ist. Zur Unterscheidung von Vorhersage und Abschätzung bietet die BfG weitere Details.
percentile10, percentile20, percentile30, percentile40, percentile60, percentile70, percentile80, percentile90	Ein Perzentil definiert einen Wert, der mit einer bestimmten Wahrscheinlichkeit über- oder unterschritten werden wird. Ist zum Beispiel percentile20=300, so wird innerhalb des Vorhersagemodells der Wasserstand 300 Zentimeter an der Station mit 80% Wahrscheinlichkeit überschritten und mit 20% Wahrscheinlichkeit unterschritten. Das Attribut value liefert in dem Fall den Median also den Mittelwert. Je breiter die Perzentilspanne ist, desto unsicherer ist die Vorhersage. Nur einige Vorhersagen verfügen über Perzentile, deswegen sind diese Attribute optional.

Allgemeine URL-Parameter

prettyprint	Standardmäßig wird der Response in mehrere Zeilen geteilt und intendiert, um besser lesbar zu sein. Für den produktiven Einsatz kann dies mit prettyprint=false deaktiviert werden.
limit/offset	Mit Hilfe von limit und offset kann die Anzahl der Ergebnisse eingeschränkt werden und somit "Pagination" realisiert werden. Mit limit=10&offset=0 werden vom ersten Element an die ersten 10 angezeigt. Mit limit=5&offset=15 werden 5 Elemente beginnend mit dem 16. Element angezeigt (mit anderen Worten: die vierte Seite).

Caching

PEGELONLINE REST-API macht über zwei komplementäre Mechanismen clientseitiges Caching möglich.

Caching über HTTP Header Expires bzw. Cache-Control

Bei den meisten Ressourcen der PEGELONLINE REST-API kann bestimmt werden, wann in der Zukunft eine Änderung erfolgen könnte. Dieser Zeitraum ist relativ kurz und liegt zwischen 1 und 60 Sekunden.

Die API setzt dazu den HTTP-Header Expires auf einen Zeitpunkt in der Zukunft, sowie max-age in Cache-Control auf einen Sekundenwert, der ausdrückt, wie lange sich die Daten nicht ändern werden. Sowohl Expires, als auch max-age drücken dasselbe aus.

Wertet ein Http-Client diese HTTP-Header aus, so kann für eine gewisse Zeit vermieden werden, überhaupt eine HTTP Abfrage auszulösen.

"Conditional GET" über HTTP Header ETag

Alle HTTP-Antworten der PEGELONLINE REST-API werden mit einem Etag HTTP-Header ausgestattet. Dadurch können nachfolgende Anfragen auf dieselbe URL so gestellt werden, dass der Server nur dann Daten zurückliefert, wenn sie sich tatsächlich geändert haben. Der Client verwendet dazu den If-None-Match HTTP-Header mit dem Etag-Hashwert. Hat sich nichts geändert, so liefert der Server den HTTP Code 304 (Not Modified) ohne Content.

Um "Conditional GET" effektiv nutzen zu können, müssen Abfragen so konstruiert werden, dass veränderliche Daten von eher statischen Daten getrennt werden. Durch die Verwendung der bei Ressourcen beschriebenen include..-Parameter kann gesteuert Daten welche Daten vom Server geliefert werden.
Generell sind Stammdaten zu den Zeitreihen oder zu den Pegeln wenig Änderungen unterworfen. Dagegen ändert sich der gerade aktuelle Messwert sehr häufig.

Kompression

Die REST-API verwendet HTTP-Kompression. Durch Setzen des HTTP Headers Accept-Encoding auf z.B. gzip in der HTTP-Anfrage, wird die HTTP-Response durch den Server auf bis zu 10% der Originalgröße komprimiert.

Auf Kompression sollte, wenn überhaupt, nur bei sehr kleinen Datenmengen verzichtet werden.

Versionierung

Werden nichtabwärtskompatible Änderungen an der Schnittstelle vorgenommen, so wird eine neue Webserviceversion unter einer anderen URL veröffentlicht. Die alte Version bleibt bestehen. Abwärtskompatible Änderungen, wie z.B. das Hinzufügen von Attributen zu Ressourcen werden innerhalb der aktuellen Version unter der bestehenden URL veröffentlicht.

Fehlermeldungen

Fehler werden als HTTP Status Codes ausgedrückt (404, 304, 500 usw.). Weiterhin wird der HTTP Status Code und eine textuelle Beschreibung im jeweiligen Format zurück gegeben.

GET /stations/XYZ.json

{"status":404,"message":"Station id 'XYZ' does not exist."}

Umgang mit Sonderzeichen in URLs

Bei der Verwendung von Sonderzeichen in URLs, also z.B. bei https://www.pegelmobil.de/webservices/rest-api/v2/stations/KÖLN.json müssen diese in UTF-8 enkodiert werden.

Kopiert man obige URL in die Adresszeile des Browsers, so wird das Ö automatisch vom Browser in UTF-8 als %C3%96 enkodiert und an den Server gesendet.

Bei der Verwendung anderer Clients muss die Enkodierung möglicherweise selbst durchgeführt werden (siehe auch Wikipedia URL-Encoding).

Folgende Tabelle enthält die UTF-8 Entsprechungen bestimmter Sonderzeichen:

Sonderzeichen	UTF-8
Leerzeichen	%20
Ö	%C3%96
ö	%C3%B6
Ä	%C3%84
ä	%C3%A4
Ü	%C3%9C
ü	%C3%BC