Stage: int, Release: 1184, Branch: master, Commit: c5261181, Gebaut: 24.10.2024, 13:12:00
WSV
PEGELONLINE PEGELONLINE Webservices PEGELONLINE

PEGELONLINE SOAP Webservice Dokumentation

Versionshistorie

VersionStatus
Version 2.4.0aktuell
Version 2.3.1gewartet
Version 2.2.1nicht mehr verfügbar
Version 2.1.0nicht mehr verfügbar
Version 2.0.2nicht mehr verfügbar
Version 1.3.0nicht mehr verfügbar

Spezifikation Version 2.4.0

Stand 19.03.2019


Änderungshistorie

Änderungen zwischen Version 2.3.1 und 2.4.0

Änderungen zwischen Version 2.3.0 und 2.3.1

Änderungen zwischen Version 2.2.0 und 2.3.0

Ä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


Einführung

Der PEGELONLINE SOAP Webservice ist 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.

Der SOAP-basierte Webservice ist über die URL

http://pegelonline.wsv.de/webservices/version2_4/2009/05/12/PegelonlineWebservice (Version 2.4)

im Internet verfügbar.

Der namespace von PEGELONLINE SOAP Webservice ist http://pegelonline.wsv.de/webservices/version2_4/2009/05/12

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.

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.



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.

Datenabfragen über PEGELONLINE SOAP Webservice

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.


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.


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.


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.


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.


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.


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.


Abfrage getPegelinformationen

Beschreibung:
Eine PegelonlinePegelinformation beschreibt die aktuellste Messung an einem Pegel sowie weitere zugehörige Daten. 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.


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.

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.


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.


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.


Datentypen von Pegelonline SOAP Webservice

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


Datentyp PegelonlineGewaesser

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

Members:

NameBeschreibungDatentyp
nameBezeichnung des Gewässersxsd:string


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


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.

Members:

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


Datentyp PegelonlineMessung

Beschreibung:
Eine Pegelonline Messung beschreibt eine Messung hinsichtlich ihres Zeitpunkts in MEZ und ihres Messwerts des Pegelstandes. Ist Member in PegelonlinePegelinformation.

Members:

NameBeschreibungDatentyp
zeitpunktZeitpunkt der Messungxsd:dateTime (Hinweis)
messwertMesswert (ist nil bei einem ungültigen Messwert)xsd:decimal


Datentyp PegelonlineDatenverfuegbarkeit

Beschreibung:
Die PegelonlineDatenverfuegbarkeit beschreibt den Zeitraum, in dem über Pegelonline SOAP Webservice 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)


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


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


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


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


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
wsaNameName des WSAxsd:string
wsaUrlURL des WSAxsd:string


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.