openapi: "3.0.0"
info:
  version: "1.0.0"
  title: "Wasserstraßen- und Schifffahrtsverwaltung: Pegel-Online API"
  description:
    "API für das bundesweite Messstellennetz der Wasserstraßen- und Schifffahrtsverwaltung des Bundes.


    Die API stellt drei verschiedene Ressourcen zur Verfügung: __Station__, __Measurement__, __Water__.

    ### Authentifizierung / Autorisierung / API Limitierung

    Es ist keine Authentifizierung oder Autorisierung notwendig. Aktuell besteht keine API Limitierung.

    ### Allgemeine Query-Parameter

    Zusätzlich zu den angegebenen Parametern sind ebenfalls allgemeine Parameter für alle Schnittstellen verfügbar ([Dokumentation](https://www.pegelonline.wsv.de/webservice/dokuRestapi;jsessionid=A294589CCEF6630142D2589F49BFA2EC#urlParameter)).

    - `charset`: Gibt die Kodierung der Response an. Standard ist hier _UTF-8_. Möglich ist z.B. auch _ISO-8859-1_.

    - `prettyprint`: Kann die zur besseren Lesbarkeit standardmäßig aktivierte Teilung der Response in mehreren Zeilen deaktivieren: _prettyprint=false_. Diese Einstellung wird für den produktiven Einsatz empfohlen.

    - `limit/offset`: Einschränkung der Anzahl der Ergebnisse. Hiermit kann 'Pagination' realisiert werden. `limit` gibt dabei die Anzahl der zurückgegebenen Elemente an. `offset` ermöglicht einen Offset vom Startwert. Beispiel: _limit=10&offset=20_ bedeutet, dass 10 Elemente beginnend mit dem 21. Element zurückgegeben werden.
    "

servers:
  - url: "https://www.pegelonline.wsv.de/webservices/rest-api/v2/"

paths:
  /stations.json:
    get:
      summary: Übersicht über alle Stationen (Pegel)
      description: Stationen (Pegel) sortiert nach Gewässername und Messstellenname.
      tags:
        - Station
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StationOverviewResult"
      parameters:
        - $ref: "#/components/parameters/includeTimeseries"
        - $ref: "#/components/parameters/includeCurrentMeasurement"
        - $ref: "#/components/parameters/includeCharacteristicValues"
        - in: query
          required: false
          name: waters
          explode: false
          schema:
            type: array
            items:
              type: string
          description: Gewässer, filtert Stationen für bestimmte Gewässer
          examples:
            Kein Filter:
              value: null
            Rhein:
              value: RHEIN
              description: Stationen, die am Gewässer Rhein liegen
        - in: query
          required: false
          name: ids
          explode: false
          schema:
            type: array
            items:
              type: string
          description: >-
            Filter nach Stationen, möglich sind der Pegelname, Pegelnummer oder die
            UUID
        - $ref: "#/components/parameters/timeseriesQuery"
        - in: query
          required: false
          name: fuzzyId
          schema:
            type: string
          examples:
            Kein Filter:
              value: null
            Berlin:
              value: Berlin
              description: Stationen, die den _Berlin_ enthalten
        - in: query
          required: false
          name: latitude
          schema:
            type: number
            format: float
          description: Breitengrad einer geografischen Position (WGS84 in Dezimalnotation)
          examples:
            Kein Filter:
              value: null
            Beispiel Breitengrad:
              value: 52.44
        - in: query
          required: false
          name: longitude
          schema:
            type: number
            format: float
          description: Längengrad einer geografischen Position (WGS84 in Dezimalnotation)
          examples:
            Kein Filter:
              value: null
            Beispiel Längengrad:
              value: 13.57
        - in: query
          required: false
          name: km
          schema:
            type: number
            format: float
          description: Flusskilometer, die Angabe eines Gewässers (waters) ist notwendig
          examples:
            Kein Filter:
              value: null
            Flusskilometer 680:
              value: 680
        - in: query
          required: false
          name: radius
          schema:
            type: number
            format: float
          description: >-
            Suchradius für Stationen um die geografische Position oder den
            angegebenen Flusskilometer. Longitude und / oder Latitude oder km
            sind notwendig.
          examples:
            Kein Filter:
              value: null
            Radius 30km:
              value: 30
  /stations/{station}.json:
    get:
      summary: Zugriff auf eine bestimmte Station (Pegel)
      description: >-
        Zugriff auf eine Station (Pegel) ist mittels des Namens, der Pegelnummer sowie
        der UUID möglich. Es wird die Verwendung der UUID empfohlen.
      tags:
        - Station
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StationOverviewResult"
      parameters:
        - $ref: "#/components/parameters/station"
        - $ref: "#/components/parameters/includeTimeseries"
        - $ref: "#/components/parameters/includeCurrentMeasurement"
        - $ref: "#/components/parameters/includeCharacteristicValues"

  /stations/{station}/{timeseries}/measurements.json:
    get:
      summary: Zugriff auf die Ressource Measurement
      description: >-
        Es handeln sich dabei um die gemessenen Rohwerte. Es können maximal
        Werte der letzten 31 Tage bezogen werden.
      tags:
        - Measurement
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MeasurementResult"
      parameters:
        - $ref: "#/components/parameters/station"
        - $ref: "#/components/parameters/timeseriesPath"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/end"
  /stations/{station}/{timeseries}/measurements.png:
    get:
      summary: Zugriff auf die Ressource Measurement - Rückgabe als Diagramm (PNG)
      description: >-
        Es handelt sich dabei um die gemessenen Rohwerte. Es können maximal
        Werte der letzten 31 Tage bezogen werden.
      tags:
        - Measurement
      responses:
        "200":
          description: OK
          content:
            image/png:
              schema:
                type: string
                format: binary
      parameters:
        - $ref: "#/components/parameters/station"
        - $ref: "#/components/parameters/timeseriesPath"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/end"
        - in: query
          required: false
          name: width
          schema:
            type: number
            format: integer
          description: Breite der grafischen Darstellung
          example: 900
        - in: query
          required: false
          name: height
          schema:
            type: number
            format: integer
          description: Höhe der grafischen Darstellung
          example: 400
        - in: query
          required: false
          name: enableSecondaryYAxis
          schema:
            type: boolean
          description: Aktivierung einer zweiten Y-Achse auf der rechten Seite
          example: null

  /waters.json:
    get:
      summary: Zugriff auf die Ressource Water
      description: Alle Gewässer
      tags:
        - Water
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WaterResult"
      parameters:
        - in: query
          required: false
          name: ids
          explode: false
          schema:
            type: array
            items:
              type: string
          description: Beschränkung auf ausgewählte Gewässer IDs
        - in: query
          required: false
          name: stations
          schema:
            type: string
          description: Beschränkung auf ausgewählte Stationen (Pegel)
          example: null
        - in: query
          required: false
          name: includeStations
          schema:
            type: boolean
          description: Stationen mit zurückgeben
          example: null
        - $ref: "#/components/parameters/includeTimeseries"
        - $ref: "#/components/parameters/includeCurrentMeasurement"
        - $ref: "#/components/parameters/includeCharacteristicValues"
  /stations/{station}/{timeseries}.json:
    get:
      summary: Zugriff auf CurrentMeasurment
      description: >-
        Liefert den aktuellen Wert der Station (Pegel). Kann auch als Unterressource von Timeseries angefordert werden.
      tags:
        - Water
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WaterResult"
      parameters:
        - $ref: "#/components/parameters/station"
        - $ref: "#/components/parameters/timeseriesPath"
components:
  parameters:
    includeTimeseries:
      in: query
      required: false
      name: includeTimeseries
      schema:
        type: boolean
      description: Informationen zu den Zeitreihen
      example: null
    station:
      in: path
      required: true
      name: station
      schema:
        type: string
      description: UUID / Name / Pegelnummer der Station.
      examples:
        UUID:
          value: 593647aa-9fea-43ec-a7d6-6476a76ae868
          description: UUID der Station
        Name:
          value: EITZE
        Pegelnummer:
          value: 48900237
    includeCurrentMeasurement:
      in: query
      name: includeCurrentMeasurement
      required: false
      schema:
        type: boolean
      description: Aktuell gemessener Wert
      example: null
    includeCharacteristicValues:
      in: query
      required: false
      name: includeCharacteristicValues
      schema:
        type: boolean
      description: kennzeichnende Wasserstände
      example: null
    timeseriesPath:
      in: path
      required: true
      name: timeseries
      schema:
        type: string
      description: timeseries shortname
      examples:
        Kein Filter:
          value: null
        Wasserstand Rohdaten:
          value: W
        Lufttemperatur:
          value: LT
        Wassertemperatur:
          value: WT
        Abfluss Rohdaten:
          value: Q
        Elektrische Leitfähigkeit Rohdaten:
          value: LF
        Durchfahrtshöhe:
          value: DFH
        Trübung:
          value: TR
        Windgeschwindigkeit:
          value: WG
        Windrichtung:
          value: WR
        Niederschlag:
          value: NIDERSCHLAG
        Niederschlagsintensität:
          value: NIEDRSCHLAGSINTENSITÄT
        Wellenperiode:
          value: TP
        Signifikante Wellenhöhe:
          value: SIGH
        Maximale Wellenhöhe:
          value: MAXH
        Sauerstoffgehalt:
          value: O2
        pH-Wert:
          value: PH
        Fließgeschwindkeit:
          value: VA
        Chlorid:
          value: CL
    start:
      in: query
      required: false
      name: start
      schema:
        type: string
        format: datetime
      description: >-
        Zeitpunkt codiert im [ISO_8601](https://de.wikipedia.org/wiki/ISO_8601) Format. Angabe eines Datums oder einer Period (_P_, z.B. "P8D" für die Messwerte der letzten 8 Tage) sind möglich.
      examples:
        Datum:
          value: "2022-02-06T09:00:00+01:00"
        Period:
          value: P8D
          description: Messwerte der letzten 8 Tage
    end:
      name: end
      in: query
      required: false
      schema:
        type: string
        format: datetime
      description: >-
        Endzeitpunkt codiert im [ISO_8601](https://de.wikipedia.org/wiki/ISO_8601) Format. Kann auch leer gelassen werden, dann wird automatisch der aktuelle Zeitstempel verwendet.
      example: ""
    charset:
      name: charset
      in: query
      required: false
      schema:
        type: string
      description: Kodierung der Response
      example: UTF-8
    prettyprint:
      name: prettyprint
      in: query
      required: false
      schema:
        type: boolean
      description: >-
        Bessere Lesbarkeit der Response durch Aufteilen in mehreren Zeilen. Für
        den produktiven Einsatz wird `false` empfohlen.
      example: false
    limit:
      name: limit
      in: query
      required: false
      schema:
        type: number
        format: integer
      example: null
    offset:
      name: offset
      in: query
      required: false
      schema:
        type: number
        format: integer
      example: null
    timeseriesQuery:
      name: timeseries
      in: query
      required: false
      explode: false
      schema:
        type: string
      description: Filter nach ausgewählten Zeitreihen
      examples:
        Kein Filter:
          value: null
        Wasserstand Rohdaten:
          value: W
        Lufttemperatur:
          value: LT
        Wassertemperatur:
          value: WT
        Abfluss Rohdaten:
          value: Q
        Elektrische Leitfähigkeit Rohdaten:
          value: LF
        Durchfahrtshöhe:
          value: DFH
        Trübung:
          value: TR
        Windgeschwindigkeit:
          value: WG
        Windrichtung:
          value: WR
        Niederschlag:
          value: NIDERSCHLAG
        Niederschlagsintensität:
          value: NIEDRSCHLAGSINTENSITÄT
        Wellenperiode:
          value: TP
        Signifikante Wellenhöhe:
          value: SIGH
        Maximale Wellenhöhe:
          value: MAXH
        Sauerstoffgehalt:
          value: O2
        pH-Wert:
          value: PH
        Fließgeschwindkeit:
          value: VA
        Chlorid:
          value: CL

  schemas:
    StationOverviewResult:
      type: array
      items:
        type: object
        properties:
          uuid:
            type: string
            example: 47174d8f-1b8e-4599-8a59-b580dd55bc87
            description: Eindeutige unveränderliche ID
          number:
            type: string
            example: 48900237
            description: Pegelnummer
          shortname:
            type: string
            example: EITZE
            description: Pegelname (max. 40 Zeichen)
          longname:
            type: string
            example: EITZE
            description: Pegelname (max. 255 Zeichen)
          km:
            type: number
            format: float
            example: 9.56
            description: Flusskilometer
          agency:
            type: string
            example: VERDEN
            description: Wasserstraßen- und Schifffahrtsamt
          longitude:
            type: number
            format: float
            example: 9.276769435375872
            description: Längengrad in WGS84 Dezimalnotation
          latitude:
            type: number
            format: float
            example: 52.90406544743417
            description: Breitengrad in WGS84 Dezimalnotation
          water:
            type: object
            description: Angaben zum Gewässer
            properties:
              shortname:
                type: string
                example: ALLER
              longname:
                type: string
                example: ALLER
          timeseries:
            type: array
            items:
              $ref: "#/components/schemas/Timeseries"
    Timeseries:
      type: object
      properties:
        shortname:
          type: string
          example: W
          description: Kurzbezeichnung
        longname:
          type: string
          example: WASSERSTAND ROHDATEN
          description: Langbezeichnung
        unit:
          type: string
          example: cm
          description: Maßeinheit
        equidistance:
          type: number
          format: float
          example: 15
          description: Abstand der Messwerte in Minuten.
        currrentMeasurement:
          $ref: "#/components/schemas/CurrentMeasurement"
        gaugeZero:
          type: object
          properties:
            unit:
              type: string
              example: m. ü. NN
              description: >-
                Einheit des Pegelnullpunkts (immer in Metern über einem
                Normalhöhennull ([Dokumentation](https://www.pegelonline.wsv.de/gast/hilfe#hilfe_hoehensystem))
            value:
              type: number
              format: float
              example: 8
              description: Höhe als Dezimalwert
            validFrom:
              type: string
              format: date
              example: "1985-03-13"
              description: Beginn der Gültigkeit. [ISO_8601](https://de.wikipedia.org/wiki/ISO_8601) Datum.
        characteristicValues:
          type: array
          items:
            $ref: "#/components/schemas/CharacteristicValues"
    CharacteristicValues:
      type: object
      description: Diese Beschreibungen variieren.

    CurrentMeasurement:
      type: object
      properties:
        timestamp:
          example: "2022-03-02T10:30:00+01:00"
        value:
          example: 323
        trend:
          example: -1
        stateMnwMhw:
          example: normal
        stateNswHsw:
          example: unknown

    MeasurementResult:
      type: array
      items:
        type: object
        properties:
          timestamp:
            type: string
            format: datetime
            example: "2022-02-06T10:15:00+01:00"
            description: Zeitpunkt im [ISO_8601](https://de.wikipedia.org/wiki/ISO_8601) Format codiert
          value:
            type: number
            format: float
            example: 333
            description: >-
              Wert als Dezimalzahl in der Einheit, welche durch die Timeseries
              der Station vorgegeben ist.
    WaterResult:
      type: array
      items:
        type: object
        properties:
          shortname:
            type: string
            format: datetime
            example: RHEIN
            description: Kurzbezeichnung, maximal 40 Zeichen.
          longname:
            type: string
            example: RHEIN
            description: Langbezeichnung, maximal 255 Zeichen.
    Comment:
      description: >-
        Liegt z.B. eine Fehlfunktion oder ein Ausfall an der Messstelle vor, so
        ist dies hier mit einer Textbeschreibung erläutert.
      type: array
      items:
        type: object
        properties:
          shortDescription:
            type: string
            example: null
            description: Kurzbeschreibung, maximal 55 Zeichen.
          longDescription:
            type: string
            example: null
            description: Langbeschreibung, maximal 500 Zeichen.