openapi: "3.0.0"
info:
  contact:
    url: "https://www.pegelonline.wsv.de/"
    name: "Wasserstraßen- und Schifffahrtsverwaltung des Bundes (WSV)"
  version: "1.0.0"
  x-office: "Wasserstraßen- und Schifffahrtsverwaltung"
  title: "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.
    "
  termsOfService: "https://www.pegelonline.wsv.de/gast/nutzungsbedingungen"

servers:
  - url: "https://www.pegelonline.wsv.de/webservices/rest-api/v2"
tags:
  - name: station
    x-displayName: Station
  - name: measurement
    x-displayName: Measurement
  - name: water
    x-displayName: Water
paths:
  /stations.json:
    get:
      summary: Übersicht über alle Stationen (Pegel)
      description: Stationen (Pegel) sortiert nach Gewässername und Messstellenname.
      operationId: getStations
      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: []
            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: ""
            Berlin:
              value: Berlin
              description: "Stationen, die _Berlin_ enthalten"
        - in: query
          required: false
          name: latitude
          schema:
            type: number
            format: float
          description: Breitengrad einer geografischen Position (WGS84 in Dezimalnotation)
        - in: query
          required: false
          name: longitude
          schema:
            type: number
            format: float
          description: Längengrad einer geografischen Position (WGS84 in Dezimalnotation)
        - in: query
          required: false
          name: km
          schema:
            type: number
            format: float
          description: "Flusskilometer, die Angabe eines Gewässers (waters) ist notwendig"
        - 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."
  /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.
      operationId: getStationsById
      tags:
        - station
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Station"
      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.
      operationId: getMeasurementByStation
      tags:
        - measurement
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MeasurementResult"
        "404":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TimeseriesNotFound"
      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.
      operationId: getMeasurementDiagramByStation
      tags:
        - measurement
      responses:
        "200":
          description: OK
          content:
            image/png:
              schema:
                type: string
                format: binary
        "404":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TimeseriesNotFound"
      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

  /waters.json:
    get:
      summary: Zugriff auf die Ressource Water
      description: Alle Gewässer
      operationId: getWaters
      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)
        - in: query
          required: false
          name: includeStations
          schema:
            type: boolean
          description: Stationen mit zurückgeben
        - $ref: "#/components/parameters/includeTimeseries"
        - $ref: "#/components/parameters/includeCurrentMeasurement"
        - $ref: "#/components/parameters/includeCharacteristicValues"

  /stations/{station}/{timeseries}.json:
    get:
      summary: Zugriff auf eine Timeseries
      description: >-
        Liefert den aktuellen Wert der Station (Pegel). Kann auch als Unterressource von Timeseries angefordert werden.
      operationId: getCurrentMeasurmentByStation
      tags:
        - water
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Timeseries"
        "404":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TimeseriesNotFound"
      parameters:
        - $ref: "#/components/parameters/station"
        - $ref: "#/components/parameters/timeseriesPath"
        - $ref: "#/components/parameters/includeCurrentMeasurement"
        - $ref: "#/components/parameters/includeCharacteristicValues"
components:
  parameters:
    includeTimeseries:
      in: query
      required: false
      name: includeTimeseries
      schema:
        type: boolean
      description: "Informationen zu den Zeitreihen"
    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"
    includeCharacteristicValues:
      in: query
      required: false
      name: includeCharacteristicValues
      schema:
        type: boolean
      description: "kennzeichnende Wasserstände"
    timeseriesPath:
      in: path
      required: true
      name: timeseries
      schema:
        type: string
      description: "timeseries shortname"
      examples:
        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
    offset:
      name: offset
      in: query
      required: false
      schema:
        type: number
        format: integer
    timeseriesQuery:
      name: timeseries
      in: query
      required: false
      explode: false
      schema:
        type: string
      description: "Filter nach ausgewählten Zeitreihen"
      examples:
        Kein Filter:
          value: ""
        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:
        $ref: "#/components/schemas/Station"
    Station:
        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."
        currentMeasurement:
          $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:
          type: number
          example: 323
        trend:
          type: number
          example: -1
        stateMnwMhw:
          type: string
          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: object
      properties:
        shortname:
          type: string
          format: datetime
          example: RHEIN
          description: "Kurzbezeichnung, maximal 40 Zeichen."
        longname:
          type: string
          example: RHEIN
          description: "Langbezeichnung, maximal 255 Zeichen."
    TimeseriesNotFound:
      type: object
      properties:
        status:
          type: integer
          example: 404
        msg:
          type: string
          example: "Timeseries does not exist."
    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
            description: "Kurzbeschreibung, maximal 55 Zeichen."
          longDescription:
            type: string
            description: "Langbeschreibung, maximal 500 Zeichen."