WSV
PEGELONLINE PEGELONLINE Webservices PEGELONLINE

PEGELONLINE REST-API User's Guide

Über die PEGELONLINE REST-API können die gewässerkundlichen Daten von PEGELONLINE auf einfache Weise abgefragt werden, um sie z.B. auf einer externen Webseite oder in einer mobilen App zu nutzen.

Die Daten sind über klar definierte HTTP-URLs adressierbar. Der Server codiert das Ergebnis in JSON (JavaScript Object Notation). JSON kann aber in praktisch allen verbreiteten Sprachen interpretiert werden.

Die API wird in ihrer Dokumentation detaillierter beschrieben.

Beispielabfragen

Eine Abfrage aller verfügbaren Messstellen von PEGELONLINE erfolgt mit dieser URL:

Die Messstellen enthalten weitere untergeordnete Informationen zu den Zeitreihen und zum gerade aktuell gemessenen Wert. Diese Daten können folgendermaßen angefordert werden:

Die Messstellen enthalten jetzt jeweils das Element timeseries, in dem eine odere mehrere Zeitreihen beschrieben sind, welche an der Messstelle verfügbar sind. Jede Timeseries enthält das Element currentMeasurement, in dem der aktuell gemessene Wert enthalten ist.

Die Liste der Messstellen kann z.B. auf bestimmte Gewässer beschränkt werden.

Der aktuelle gemessene Wert einer einzelnen Messstelle kann entweder mit den Messstelleninformationen..

oder auch isoliert abgefragt werden.

Die gemessenen Rohwerte einer Zeitreihe an einer Messstelle können über die Ressource Measurement abgefragt werden. Folgende URL ruft die Messwerte der letzten 15 Tage ab ('P15D' ist eine ISO_8601 Zeitspanne.). Alternativ kann für den Parameter start auch ein ISO_8601 Zeitpunkt angegeben werden.

Die Messwerte können alternativ auch als PNG-Image visualisiert werden. Dazu ändert man die Endung .json in .png.

Das Format, in dem der Server die Daten ausliefert, wird also über die Endung bestimmt. Zukünftig werden weitere Formate wie z.B. XLS (Excel), XML oder GeoJSON angeboten.

Einbettung der Ganglinienvisualisierung in externe Webseiten über HTML

Folgendes Beispiel zeigt die Einbettung einer Ganglinienvisualisierung mit Wasserstandsdaten der letzten 15 Tage in eine externe Webseite. Die Darstellung wird durch einen regulären HTML Img-Tag angefordert. Ergebnis:

Einbettung der Daten in externe Webseiten über Javascript

Folgendes Beispiel zeigt die Einbettung der Daten in eine externe Webseite mit Hilfe von JavaScript und jQuery. Es werden Daten über der Messstelle Bonn über ihre UUID angefordert und diese innerhalb eines HTML-Elements dargestellt.

Weitere Hinweise

Caching

Die API unterstützt clientseitiges Caching durch die HTTP Header Cache-Control, Expires und Etag.

Durch die Verwendung von Expires und max-age im HTTP Header Cache-Control, kann für eine gewisse Zeit ein HTTP-Request gänzlich entfallen. Durch den Header Etag sendet der Server nur dann die angeforderten Daten zurück, wenn sie sich auf der Serverseite verändert haben.

Im obigen Javascriptbeispiel wird bei jedem Klick der Browser angefordert, die Daten unter der URL abzufragen. Die Auswirkung der Http-Header lässt sich über den Netzwerkverkehr mit Hilfe der Chrome Entwicklertools oder der Firefox Extension Firebug beobachten.

Weiterführende Hinweise gibt es in im entsprechenden Abschnitt der Dokumentation.

UUID

Auf die Messstellen sollte sich nur per UUID bezogen werden. Messstellennummer oder -namen können sich verändern bzw. sind nicht eindeutig.

Kompression

Siehe entsprechenden Abschnitt in der Dokumentation.

Umgang mit Sonderzeichen in URLs

Siehe entsprechenden Abschnitt in der Dokumentation.