WSV
PEGELONLINE PEGELONLINE Webservices PEGELONLINE

PEGELONLINE Webservice-Aktuell Dokumentation

Versionshistorie

VersionStatus
Version 2.3.1aktuell
Version 2.2.1gewartet
Version 2.1.0gewartet
Version 2.0.2gewartet
Version 1.3.0nicht mehr unterstützt

Spezifikation Version 2.3.1

Stand 15.10.2014

nach oben

Änderungshistorie

Änderungen zwischen Version 2.3.0 und 2.3.1

Änderungen zwischen Version 2.2.1 und 2.3.0

Änderungen zwischen Version 2.2.0 und 2.2.1

Änderungen zwischen Version 2.1.0 und 2.2.0

Änderungen zwischen Version 2.0.2 und 2.1.0

Änderungen zwischen Version 2.0.1 und 2.0.2

Änderungen zwischen Version 2.0 und 2.0.1

Änderungen zwischen Version 1.0.2 und 2.0

nach oben

Einführung

Der PEGELONLINE Webservice-Aktuell umfasst zwei Teile: Eine SOAP-basierte Schnittstelle zur Abfrage unterschiedlicher in PEGELONLINE enthaltener Daten, die für die Veröffentlichung im Rahmen des hier beschriebenen Webservices vorgesehen sind. Zweitens können HTML-Fragmente über parametrisierte URLs direkt über http bezogen werden und in externen Seiten integriert werden.

Der SOAP-basierte Webservice ist über die URL

http://www.pegelonline.wsv.de/webservices/version2_3/2007/10/31/PegelonlineWebservice (Version 2.3)

im Internet verfügbar.

Der namespace von PEGELONLINE Webservice-Aktuell ist http://pegelonline.wsv.de/webservices/version2_3/2007/10/31

Kommunikationsprotokoll: SOAP 1.1 RPC über HTTP POST; Übertragung der Datenstrukturen findet als „wrapped/literal“ statt, es findet keine SOAP „Sektion 5“ Enkodierung statt. „wrapped/literal“ ist die Default-Einstellung unter .NET. „wrapped“ ist eine Untermenge der „document“-Übertragung.

Implementation: Jakarta Tomcat 4.1.30 (Servlet Container) und Apache Axis 1.4 (SOAP Engine)

Die Interoperabilität zu verschiedenen Platformen ist gemäß den Standards WSI Basic Profile 1.1 und WSI Simple SOAP Binding Profile 1.0 der Web Services Interoperability Organization gewährleistet. Eingesetzt werden dazu die Test-Tools der WSI.

Verifizierte Kompatibilität zu folgenden Webservice-Client-Frameworks:
APIs für PegelonlineWebservice können basierend auf Java 1.5 und JWSDP 2.0 oder Apache Axis 1.4 zur Verfügung gestellt werden. Die API-Pakete werden innerhalb einer Servlet-Webapplikation zur Verfügung gestellt. Sie enthalten den API-Quellcode, die notwendigen externen Bibliotheken und eine HTML-Maske, welche eine Beispielanwendung für PegelonlineWebservice darstellt.

Zeitpunkte werden innerhalb der SOAP-Message gemäß der W3C-XMLSchema-Spezifikation kodiert, immer als UTC- bzw. GMT-Zeit. Wird zum Beispiel im SOAP eine Uhrzeit von 16:00 Uhr kodiert, so handelt es sich dabei um 17:00 Uhr in der mitteleuropäischen Winterzeit, in der Sommerzeit wäre dies 18:00 Uhr. SOAP-Engines verschiedener Plattformen passen das SOAP-Datumsliteral immer an die jeweilige Zeitzone des Clients an.
nach oben

Datenabfragen über PEGELONLINE Webservice-Aktuell

Abfrage getParameterList

Beschreibung:
Generiert ein Array von PegelonlineParameter-Instanzen. Liefert alle in Pegelonline für die Veröffentlichung vorgesehene Parameter.

Request-Parameter:
keine

Response:
0 bis n Arrayelemente von PegelonlineParameter-Instanzen.

nach oben

Abfrage getGewaesserList

Beschreibung:
Generiert ein Array von PegelonlineGewaesser-Instanzen. In Abhängigkeit von den verwendeten Request-Parametern wird eine Teilmenge der verfügbaren Datensätze von Pegelonline zurückgeliefert (0 bis n Arrayelemente). Wird für parameterName nil übergeben, so wird die Ergebnismenge hinsichtlich dieses Parameters nicht eingeschränkt.

Request-Parameter:

NameBeschreibungDatentypnil
parameterNameBezeichnung des Parametersxsd:stringJa

Response:
0 bis n Arrayelemente von _PegelonlineGewaesser_-Instanzen sortiert nach Name.

nach oben

Abfrage getGewaesser

Beschreibung:
Generiert eine PegelonlineGewaesser-Instanzen. Liefert nil, falls ein Gewässer unter diesem Namen in PEGELONLINE nicht existiert.

Request-Parameter:

NameBeschreibungDatentypnil
gewaesserNameBezeichnung des Gewässersxsd:stringJa

Response:
Nil oder eine Instanz von PegelonlineGewaesser.

nach oben

Abfrage getMessstellenList

Beschreibung:
Generiert ein Array von PegelonlineMessstelle-Instanzen. In Abhängigkeit von den verwendeten Request-Parametern wird eine Teilmenge der verfügbaren Datensätze von Pegelonline zurückgeliefert (0 bis n Arrayelemente). Wird für parameterName nil übergeben, so wird die Ergebnismenge hinsichtlich dieses Parameters nicht eingeschränkt. Wird für gewaesserNamen nil übergeben, so wird die Ergebnismenge hinsichtlich dieses Parameters nicht eingeschränkt.

Request-Parameter:

NameBeschreibungDatentypnil
parameterNameBezeichnung des Parametersxsd:stringJa
gewaesserNamenArray von Bezeichnungen für Gewässerxsd:stringJa

Response:
0 bis n Arrayelemente von PegelonlineMessstelle-Instanzen sortiert nach Kilometerstand.

nach oben

Abfrage getMessstelle

Beschreibung:
Generiert eine PegelonlineMessstelle-Instanz. Liefert nil, falls eine Messstelle unter dieser Nummer oder Namen in pegelonline nicht existiert. Wird für die Messstellennummer keine Angabe gemacht (nil) so wird in diesem Fall der Messstellenname verwendet. Ist beides angegeben, so wird immer die Messstellennummer ausgewertet.

Request-Parameter:

NameBeschreibungDatentypnil
messstelleNummerNummer der Messstellexsd:stringJa
messstelleNameBezeichnung der Messstellexsd:stringJa

Response:
Nil oder eine Instanz von PegelonlineMessstelle.

nach oben

Abfrage getMessstellenParameter

Beschreibung:
Generiert ein Array von PegelonlineMessstelleParameter-Instanzen. Wird für die Messstellennummer keine Angabe gemacht (nil) so wird in diesem Fall der Messstellenname verwendet. Ist beides angegeben, so wird immer die Messstellennummer ausgewertet. Wird weder die Messstellennummer noch der Messstellenname spezifiziert (beides nil), so werden alle für die Veröffentlichung vorgesehenen MessstelleParameter zurückgegeben.

Request-Parameter:

NameBeschreibungDatentypnil
messstelleNummerNummer der Messstellexsd:stringJa
messstelleNameBezeichnung der Messstellexsd:stringJa

Response:
0 bis n Arrayelemente von PegelonlineMessstelleParameter-Instanzen.

nach oben

Abfrage getDatenverfuegbarkeit

Beschreibung:
Generiert eine PegelonlineDatenverfuegbarkeit-Instanz. Liefert den maximalen Zeitraum, für den öffentliche Messungen in Pegelonline existieren. Dies ist der maximale Zeitraum, der für die Abfragen getGanglininienURL oder getMessungenDatei verwendet werden kann. Liefert nil, falls keine Daten für die angegebenen Parameternamen und Messstellennamen existieren. Werden für die Messstellennummern keine Angabe gemacht (nil), so werden in diesem Fall die Messstellennamen ausgewertet. Ist beides angegeben, so werden immer die Messstellennummern ausgewertet. Es muss immer mindestens eins von beiden angegeben sein.

Request-Parameter:

NameBeschreibungDatentypnil
parameterNameBezeichnung des Parametersxsd:stringNein
messstellenNummernArray von Nummern für Messstellenxsd:stringJa
messstellenNamenArray von Bezeichnungen für Messstellenxsd:stringJa

Response:
Nil oder eine Instanz von PegelonlineDatenverfuegbarkeit.

nach oben

Abfrage getPegelinformationen

Beschreibung:
Eine PegelonlinePegelinformation beschreibt die aktuellste Messung an einem Pegel sowie weitere zugehörige Daten. Sind Vorhersagewerte (Niedrigwasser- und Hochwasservorhersagen) für den Pegel vorhanden und freigegeben, und handelt es sich um eine wasserstandsbezogene Pegelinformation, so werden die Vorhersagewerte ebenso zurück gegeben. Die Abfrage generiert ein Array von PegelonlinePegelinformation-Instanzen. In Abhängigkeit von den verwendeten Request-Parametern wird eine Teilmenge der verfügbaren Datensätze von Pegelonline zurückgeliefert (0 bis n Arrayelemente). Werden für die Messstellennummern keine Angabe gemacht (nil), so werden in diesem Fall die Messstellennamen ausgewertet. Ist beides angegeben, so werden immer die Messstellennummern ausgewertet.

Wird für parameterName nil übergeben, so wird die Ergebnismenge hinsichtlich dieses Parameters nicht eingeschränkt. Wird für messstellenNamen und messstellenNummern nil übergeben, so wird die Ergebnismenge hinsichtlich der Messstellen nicht eingeschränkt.

Request-Parameter:

NameBeschreibungDatentypnil
parameterNameBezeichnung des Parametersxsd:stringJa
messstellenNummernArray von Nummern für Messstellenxsd:stringJa
messstellenNamenArray von Bezeichnungen für Messstellenxsd:stringJa

Response:
0 bis n Arrayelemente von PegelonlinePegelinformation-Instanzen.

nach oben

Abfrage getMessungenAktuell

Beschreibung:
Über diese Abfrage können tagesaktuelle Messdaten der letzten 31 Tage bezogen werden.

Wird für die Messstellennummer keine Angabe gemacht (nil), so wird in diesem Fall der Messstellenname ausgewertet. Mindestens eins von beiden muss angegeben werden. Als Parameterbezeichung kann einer der aus der Abfrage getParameterList gewonnenen verwendet werden (z.B. 'WASSERSTAND ROHDATEN'). Über die Verfügbarkeit von Zeitreihendaten für eine Messstelle und einen Parameter gibt die Abfrage getPegelinformationen Auskunft. Dort können auch weitere Informationen wie z.B. die Maßeinheit der gemessenen Daten ermittelt werden.

Request-Parameter:

NameBeschreibungDatentypnil
parameterNameBezeichnung des Parametersxsd:stringNein
messstellenNummerNummer der Messstellexsd:stringJa
messstellenNameBezeichnung der Messstellexsd:stringJa
startDer Startzeitpunkt (inklusive)xsd:dateTime (Hinweis)Nein
endeDer Endzeitpunkt (inklusive)xsd:dateTime (Hinweis)Nein

Response:
0 bis n Arrayelemente von PegelonlineMessung-Instanzen, sortiert nach dem Zeitpunkt der Messung. Das Tendenzattribut von PegelonlineMessung ist bei dieser Abfrage dann nicht gesetzt.

nach oben

Abfrage getGanglinienUrl

Beschreibung:
Generiert eine URL, welche verwendet werden kann, um die Ganglinienanzeige als HTML-Fragment über Pegelonline zu beziehen. Werden die Request-Parameter start und ende nicht angegeben, so wird immer der für die Gangliniendarstellung verwendete Default-Zeitraum (ein Monat ausgehend vom aktuellen Datum) verwendet. Werden für die Messstellennummern keine Angabe gemacht (nil), so werden in diesem Fall die Messstellennamen ausgewertet. Ist beides angegeben, so werden immer die Messstellennummern ausgewertet. Es muss immer mindestens eins von beiden angegeben sein.

Request-Parameter:

NameBeschreibungDatentypnil
parameterNameBezeichnung des Parameters; default ist „Wasserstand Rohdaten“xsd:stringJa
messstellenNummernArray von Nummern für Messstellenxsd:stringJa
messstellenNamenArray von Bezeichnungen für Messstellenxsd:stringJa
startDer Startzeitpunkt, wird auf Tagesgenauigkeit interpretiert.xsd:dateTime (Hinweis)Ja
endeDer Endzeitpunkt, wird auf Tagesgenauigkeit interpretiert.xsd:dateTime (Hinweis)Ja
einzelansichtWenn true, wird eine Ganglinien-URL generiert, durch die der Verlauf der Messungen in jeweils einem eigenen Image anzeigt wird; wenn false oder nil, so wird eine URL generiert, welche alle Ganglinien in einem Image anzeigt.xsd:booleanJa
designDesigntyp (Werte:'default', 'pegelonline-relaunch'; bei nil wird 'default' standardmäßig genommen)xsd:StringJa

Response:
Eine http-URL vom Typ xsd:string.

nach oben

Abfrage getGanglinienImage

Beschreibung:
Generiert ein Byte-Array, welches ein Image im GIF-Format enthält. Dieses Image kann z.B. in eine HTML-Seite eingebunden werden. Werden die Request-Parameter start und ende nicht angegeben, so wird immer der für die Gangliniendarstellung verwendete Default-Zeitraum (ein Monat ausgehend vom aktuellen Datum) verwendet. Werden für die Messstellennummern keine Angabe gemacht (nil), so werden in diesem Fall die Messstellennamen ausgewertet. Ist beides angegeben, so werden immer die Messstellennummern ausgewertet. Es muss immer mindestens eins von beiden angegeben sein. Unterhalb einer Laenge von 750 Pixeln oder einer Breite von 490 Pixeln werden Achsenbeschriftungen und Achseneinteilungen nicht mehr dargestellt.

Request-Parameter:

NameBeschreibungDatentypnil
parameterNameBezeichnung des Parameters; default ist „Wasserstand Rohdaten“xsd:stringJa
messstellenNummernArray von Nummern für Messstellenxsd:stringJa
messstellenNamenArray von Bezeichnungen für Messstellenxsd:stringJa
startDer Startzeitpunkt, wird auf Tagesgenauigkeit interpretiert.xsd:dateTime (Hinweis)Ja
endeDer Endzeitpunkt, wird auf Tagesgenauigkeit interpretiert.xsd:dateTime (Hinweis)Ja
laengeBreite des Image in Pixel; default ist 100 Pixelxsd:intJa
hoeheHöhe des Image in Pixel; default ist 80 Pixelxsd:intJa

Response:
Ein Byte-Array im GIF-Format vom Typ xsd:base64Binary.

nach oben

Abfrage getMessungenDatei

Beschreibung:
Liefert einen im ZIP-Format sich befindenden Byte-Strom von Messungen und dazugehörigen Stammdaten, wie sie auch über Pegelonline veröffentlicht wird. Werden die Request-Parameter start und ende nicht angegeben, so wird immer der für die Dateierstellung verwendete Default-Zeitraum (ein Monat ausgehend vom aktuellen Datum) verwendet. Werden für die Messstellennummern keine Angabe gemacht (nil), so werden in diesem Fall die Messstellennamen ausgewertet. Ist beides angegeben, so werden immer die Messstellennummern ausgewertet. Es muss immer mindestens eins von beiden angegeben sein.

Request-Parameter:

NameBeschreibungDatentypnil
parameterNameBezeichnung des Parametersxsd:stringNein
messstellenNummernArray von Nummern für Messstellenxsd:stringJa
messstellenNamenArray von Bezeichnungen für Messstellenxsd:stringJa
startDer Startzeitpunkt, wird auf Tagesgenauigkeit interpretiert.xsd:dateTime (Hinweis)Ja
endeDer Endzeitpunkt, wird auf Tagesgenauigkeit interpretiert.xsd:dateTime (Hinweis)Ja

Response:
Ein Byte-Array im ZIP-Format vom Typ xsd:base64Binary.

nach oben

Datentypen von Pegelonline Webservice-Aktuell

Datentyp PegelonlineParameter

Beschreibung:
Ein PegelonlineParameter beschreibt die Art der gemessenen Daten. Dabei kann es sich zum Beispiel um den Wasserstand am Pegel oder die dort gemessene Wassertemperatur handeln.

Members:

NameBeschreibungDatentyp
nameBezeichnung des Parametersxsd:string

nach oben

Datentyp PegelonlineGewaesser

Beschreibung:
Das PegelonlineGewaesser beschreibt das Gewässer, an dem der jeweilige Pegel liegt.

Members:

NameBeschreibungDatentyp
nameBezeichnung des Gewässersxsd:string

nach oben

Datentyp PegelonlineMessstelle

Beschreibung:
Eine PegelonlineMessstelle beschreibt eine Messstelle/Pegel an der Messungen vorgenommen werden.

Members:

NameBeschreibungDatentyp
nameKurze Bezeichnung der Messstellexsd:string
nummerNummer der Messstellexsd:string
kilometerstandRelative Position der Messstelle am Gewässerverlauf in Kilometernxsd:decimal
pegelonlineKoordinateKoordinate der MessstellePegelonlineKoordinate

nach oben

Datentyp PegelonlinePegelinformation

Beschreibung:
Eine PegelonlinePegelinformation beschreibt die zum Zeitpunkt der Abfrage aktuellste Messung an einer Messstelle sowie weitere zugehörige Daten. Dazu gehören der Parameter, das Gewässer, die Messstelle sowie der Pegelnullpunkt der Messstelle. Zusätzlich werden Vorhersagewerte (Niedrigwasser- und Hochwasservorhersagen) zurückgegeben, wenn diese für den Pegel existieren und zur Veröffentlichung freigegeben sind.

Members:

NameBeschreibungDatentyp
pegelonlineAktuelleMessungPegelonlineMessung-InstanzPegelonlineMessung
pegelonlineParameterPegelonlineParameter-InstanzPegelonlineParameter
pegelonlineGewaesserPegelonlineGewaesser-InstanzPegelonlineGewaesser
pegelonlineMessstellePegelonlineMessstelle-InstanzPegelonlineMessstelle
pegelonlinePegelnullpunktPegelonlinePegelnullpunkt-InstanzPegelonlinePegelnullpunkt
pegelonlineKoordinatePegelonlineKoordinate-InstanzPegelonlineKoordinate
pegelonlineVorhersagePegelonlineVorhersage-InstanzPegelonlineVorhersage
pegelonlineWSAWasser- und Schifffahrtsamt; kann nil sein, optionalPegelonlineWSA
masseinheitMaßeinheitxsd:string
aequidistanzmassÄquidistanter zeitlicher Abstand zwischen Messungen am Pegel in Minutenxsd:int

nach oben

Datentyp PegelonlineMessung

Beschreibung:
Eine Pegelonline Messung beschreibt eine Messung hinsichtlich ihres Zeitpunkts in MEZ, ihres Messwerts und der Tendenz des Pegelstandes (gleich bleibend, fallend, steigend). Ist Member in PegelonlinePegelinformation.

Members:

NameBeschreibungDatentyp
zeitpunktZeitpunkt der Messungxsd:dateTime (Hinweis)
messwertMesswert (ist nil bei einem ungültigen Messwert)xsd:decimal
tendenz-1 entspricht fallender Tendenz, 0 gleich bleibender Tendenz und 1 steigender Tendenz. -99 entspricht unbekannter Tendenz.xsd:byte

nach oben

Datentyp PegelonlineVorhersage

Beschreibung:
Eine PegelonlineVorhersage beschreibt eine Vorhersage hinsichtlich ihres Zeitpunkts in MEZ, ihres Wertes und des Typs (Niedrigwasser- oder Hochwasservorhersage). Ist Member in PegelonlinePegelinformation.

Members:

NameBeschreibungDatentyp
zeitpunktZeitpunkt der Vorhersagexsd:dateTime (Hinweis)
wertWertxsd:decimal
typeBei 'NW-V' handelt es sich um Vorhersage eines Niedrigwasserstandes, 'HW-V' entspricht Vorhersage eines Hochwasserstandes.xsd:string

nach oben

Datentyp PegelonlineDatenverfuegbarkeit

Beschreibung:
Die PegelonlineDatenverfuegbarkeit beschreibt den Zeitraum, in dem über Pegelonline Webservice-Aktuell Daten für die Abfrage getMessungenDatei existieren, sowie den maximalen Zeitraum, für den eine Ganglinien-URL (Abfrage getGanglinienUrl) erzeugt werden kann.

Members:

NameBeschreibungDatentyp
startStartzeitpunktxsd:dateTime (Hinweis)
endeEndzeitpunktxsd:dateTime (Hinweis)

nach oben

Datentyp PegelonlinePegelnullpunkt

Beschreibung:
Höhenlage des Nullpunktes der Pegellatte bezogen auf ein amtlich festgelegtes Höhensystem.

Members:

NameBeschreibungDatentyp
hoeheHöhe des Pegelnullpunktes in Meternxsd:decimal

nach oben

Datentyp PegelonlineKoordinate

Beschreibung:
Bei einer PegelonlineKoordinate handelt es sich um die Position der Messstelle bzw. des Gebers basierend auf einem bestimmten Koordinatensystems. Instanzen dieses Typs sind sowohl innerhalb von PegelonlineMessstelle (Position der Messstelle), als auch innerhalb von PegelonlinePegelinformation (hier Geber an der Messstelle, der Messungen des jeweiligen PegelonlineParameters vornimmt). Das Koordinatensystem in PegelonlinePegelinformation entspricht immer dem der PegelonlineMessstelle.

Members:

NameBeschreibungDatentyp
rechtswertRechtswert der Koordinatexsd:decimal
hochwertHochwert der Koordinatexsd:decimal
pegelonlineKoordinatensystemKoordinatensystem der KoordinatePegelonlineKoordinatensystem

nach oben

Datentyp PegelonlineKoordinatensystem

Beschreibung:
Ein PegelonlineKoordinatensystem enthält Angaben zum Koordinatensystem auf den sich Instanzen des Datentyps PegelonlineKoordinate beziehen.

Members:

NameBeschreibungDatentyp
bezugssystemBezugssystem des Koordinatensystemsxsd:string
ellipsoidEllipsoid des Koordinatensystemsxsd:string
epsgCodeEPSG-Code des Koordinatensystemsxsd:int
streifenZoneStreifen oder Zone des Koordinatensystemsxsd:string

nach oben

Datentyp PegelonlineMessstelleParameter

Beschreibung:
Ein PegelonlineMessstelleParameter enthält einen messstellenbezogene Parameter. Können über die Abfrage getMessstellenParameter bezogen werden.

Members:

NameBeschreibungDatentyp
nameKurzname des Parametersxsd:string
nameLangLangname des Parametersxsd:string
masseinheitMaßeinheit des Parametersxsd:string
pegelonlineMessstelleZum Parameter zugehörige PegelonlineMessstelle-InstanzPegelonlineMessstelle
wertWert des Parametersxsd:decimal

nach oben

Datentyp PegelonlineWSA

Beschreibung:
Eine PegelonlineWSA enthält Informationen zu einer Wasser- und Schifffahrtsamt. Kann über Abfrage getPegelinformation bezogen werden.

Members:

NameBeschreibungDatentyp
nameLangName des Amtesxsd:string
strasse Straße und Hausnummer des Amtesxsd:string
plzPostleitzahl der Direktionxsd:string
ortOrt der Direktionxsd:string

nach oben

HTML-Fragmente zur Integration in externen Webseiten

HTML zur Anzeige einer Ganglinie

Hierbei handelt es sich um ein HTML-Fragment mit hohem Javascript-Anteil aus der Webseite Pegelonline, mit dem dynamisch Grafiken generiert werden, die den Verlauf des Pegelstandes über die Zeit für ein oder mehrere Messstellen anzeigen. Dieses Fragment kann normal, innerhalb eines Frames oder eines Popup-Fensters in einer externen Webseite referenziert werden. Die jeweils gültige URL kann über die Abfrage getGanglinienUrl bezogen werden.

nach oben