WSV
PEGELONLINE PEGELONLINE Webservices PEGELONLINE

PEGELONLINE REST-API Dokumentation


Ü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-Notation und bei den gemessenen Rohdaten zusätzlich 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 liegt momentan in Version 2 vor und ist unterhalb von https://www.pegelonline.wsv.de/webservices/rest-api/v2 adressierbar.

Die Daten werden in JSON-Notation erzeugt. Die gemessenen Rohdaten von PEGELONLINE können weiterhin auch als Diagramm abgefragt werden.

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 mit Einschließung 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.

Zugriff auf bestimmte Stationen:

/stations/BONN.json Zugriff auf einen Pegel per Name. Statt BONN.json kann der Pegel auch über die Pegelnummer, also 2710080.json oder über die UUID - 593647aa-9fea-43ec-a7d6-6476a76ae868.json - adressiert werden. Nur für die UUID kann garantiert werden, dass sie sich nicht ändert.
/stations.json?waters=RHEIN,MAIN Pegel bestimmter Gewässer.
/stations.json?ids=BONN,2730010 Bestimmte Pegel. Für die IDs kann eine Pegelnummer, ein Pegelname oder eine UUID verwendet werden.
/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 Wasser- 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 30 Tage bezogen werden.

Die Messwerte können in JSON bezogen werden oder als Diagramm visualisiert werden.

Zugriff auf die Ressource Measurement:

/stations/BONN/W/measurements.json Wasserstandsrohdaten des Pegels Bonn der letzten 10 Tage (Standardzeitraum).
/stations/BONN/W/measurements.json?start=2017-03-07T09:00+01:00&end=2017-03-19T16:00+01:00 Wasserstandsrohdaten des Pegels Bonn zwischen dem 07. März 2017 09:00 Uhr bis zum 19. März 2017 16:00 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/BONN/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/BONN/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/BONN/W/measurements.png?start=P20D&width=700&height=200&enableSecondaryYAxis=true Eine grafische Darstellung mit zweiter Y-Achse auf der rechten Seite.

Erläuterung der Attribute der Ressource Measurement:

timestamp Zeitpunkt codiert 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=NIENBURG,ROEPZIG,DESSAU,STORKAU& 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/KETZIN/W.json?includeCurrentMeasurement=true Die Wasserstandszeitreihe des Pegels Ketzin mit dem aktuelle Messwert.
/stations/KETZIN/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 Pegelparameter):

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 codiert 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/KETZIN/W.json?includeCurrentMeasurement=true Die Wasserstandszeitreihe des Pegels Ketzin mit dem aktuelle Messwert.
/stations/KETZIN/W/currentmeasurement.json Den aktuellen Wert von Ketzin.

Erläuterung der Attribute der Ressource CurrentMeasurement

timestamp Zeitpunkt codiert im ISO_8601 Format.
value Wert als Dezimalzahl in der Einheit, welche durch die Timeseries der Station vorgegeben ist.
trend Drückt numerisch aus, ob es sich um steigende (1), fallende (-1) oder gleichbleibende (0) Tendenz handelt. Kann die Tendenz nicht ermittelt werden, so ist trend -999.
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.

nach oben

Allgemeine URL-Parameter

charset Hierüber kann angegeben werden, mit welchem Zeichensatz der Response kodiert wird. Standard ist UTF-8. Alternativ könnte z.B. charset=ISO-8859-1 in der URL definiert werden.
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).
nach oben


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.

Beide Cachingverfahren werden nur über HTTP vom Server unterstützt, nicht über HTTPS.

nach oben


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.

nach oben


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.

nach oben


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."}
nach oben


Umgang mit Sonderzeichen in URLs

Bei der Verwendung von Sonderzeichen in URLs, also z.B. bei https://www.pegelonline.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

nach oben