PEGELONLINE REST-API Dokumentation
- Überblick
- Ressourcen
- 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://pegelonline-testprev.wsv.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=Wed Nov 27 09:00:00 CET 2024+01:00&end=Mon Dec 09 16:00:00 CET 2024+01:00 | Wasserstandsrohdaten des Pegels Bonn zwischen dem Wed Nov 27 09:00:00 CET 2024 Uhr bis zum Mon Dec 09 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 | In JSON ist der Zeitpunkt kodiert im ISO_8601 Format. Bei CSV handelt es sich um die lokale Zeit in einer Excel-kompatiblen Form. |
| 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:
|
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 does not exist."}
Umgang mit Sonderzeichen in URLs
Bei der Verwendung von Sonderzeichen in URLs, also z.B. bei https://pegelonline-testprev.wsv.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 |