Fluvigil Flood Situation API

openapi: 3.2.0
info:
  title: Fluvigil Public Flood Situation API
  version: 2.0.0
  license:
    name: Proprietary — use is governed by the terms of service
    url: https://fluvigil.de/terms
  description: 'Water levels and flood classifications of gauging stations in Germany and its neighbouring countries. Data sources: PEGELONLINE (WSV), Länderübergreifendes Hochwasserportal (LHP, CC BY 4.0 — attribution required) and the German state portals, plus the official hydrological services of Switzerland (BAFU), Austria (state services, eHYD), Czechia (ČHMÚ), Luxembourg (AGE), France (SIE / Hub''Eau), Denmark (Danmarks Miljøportal), the Netherlands (Rijkswaterstaat), Poland (IMGW-PIB) and Berlin (Wasserportal); weather by Deutscher Wetterdienst (via Bright Sky). Every station''s source and its attribution are listed on the site.

    Every provider attaches conditions to its data (credit line, licence, notices that the values are raw data or no official warning). A station whose provider is cleared for publication carries them as `sourceNotice` in the station list, the station detail, the river page, the neighbours and in every response that returns its values (readings, state, statistics, year-over-year, history context, analogue, forecast, report text, the flood situation and the routing simulation). Anyone passing these values on has to pass the notice on with them; the terms of service require every consumer of the API to show the notice with the values it displays. `form` says whether the provider allows a shortened notice (`textShort`) or only the full one (`full-only`, today Salzburg, which must never be shortened); `parts` names every source involved, the source of the values first. The text is German (the approved wording of the provider is never translated); the station detail also accepts `?locale=en` for the English labels around it.

    Changes in 2.0.0 (breaking): `GET /stations/timeline` is removed. Its replacement, `GET /stations/state-timeline`, replays the stored state history, answers with severity codes for station ids in column order and leaves out the coordinates, which `GET /stations/map` supplies. A client of the removed path switches to the new one and reads positions from the map list; calls to the old path now answer 404.

    Changes: `sourceNotice` is no longer limited to Salzburg. It is present for every source with a cleared licence, and its `id` is the key of the source record (for example `pegelonline`, `ch`, `niederoesterreich`) instead of always `salzburg`; a client that compares `id` with the literal `salzburg` to decide whether a notice exists has to test for `null` instead. The fields `sourceLine`, `rawData`, `disclaimer`, `noOfficialWarning` and `termsPath` are unchanged. An LHP gauge whose value cannot be attributed to the state portal that delivered it (not recorded yet) has no value until the next value sync; it keeps its flood class and the notice of the LHP.

    Anonymous access is allowed at free-tier limits (90-day readings range, 600 requests/hour per IP). An API key (created in the account area, sent as `X-Api-Key` or `Authorization: Bearer pm_...`) applies the limits of the account''s tier; exceeding the hourly budget returns 429.'
servers:
- url: /api/v1
security:
- {}
- apiKey: []
tags:
- name: Flood Situation
paths:
  /flood-situation/latest:
    get:
      summary: National flood situation, newest report
      operationId: getLatestFloodSituation
      description: Gauges in flood (LHP class 1 or higher), counted by class and by state, with the most affected gauges listed. The newest daily report is returned; before the first one exists the situation is computed live. Each listed gauge carries the `sourceNotice` it is delivered under, with the source of its value and the flood-class feed as two parts. A gauge without a notice keeps its class but has no `valueCentimeters`.
      parameters:
      - $ref: '#/components/parameters/Locale'
      responses:
        '200':
          description: The report and its summary text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FloodSituationResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Flood Situation
  /flood-situation/{date}:
    get:
      summary: National flood situation of one day
      operationId: getFloodSituationByDate
      description: The daily report of the given date (`YYYY-MM-DD`). Same shape as the newest report; the notice of every listed gauge is resolved when the report is read, so it reflects the current licence state while the stored levels are those of the report time.
      parameters:
      - name: date
        in: path
        required: true
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - $ref: '#/components/parameters/Locale'
      responses:
        '200':
          description: The report and its summary text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FloodSituationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Flood Situation
components:
  responses:
    BadRequest:
      description: Invalid query parameters.
    NotFound:
      description: Station does not exist.
    RateLimited:
      description: The hourly request budget for the tier is exhausted.
  schemas:
    SourceNoticePart:
      type: object
      description: The conditions of one source involved in the values a gauge shows.
      properties:
        id:
          type: string
          description: 'Key of the source record the notice part comes from: a station source (`pegelonline`, `ch`, `lhp`, ...), a state value source (`ni-nlwkn`, `th-hnz`, ...), or `salzburg` / `niederoesterreich` for those two Austrian variants.

            '
        form:
          type: string
          enum:
          - short-allowed
          - full-only
          description: '`full-only` when the provider approved paragraphs that must never be shortened'
        permissionBasis:
          type: string
          enum:
          - licence
          - statutory-access
          - written-consent
          - licence-and-consent
        licence:
          type:
          - object
          - 'null'
          description: The licence the permission rests on; null for statutory access and written consent alone.
          properties:
            name:
              type: string
            url:
              type: string
        sourceName:
          type: string
        sourceUrl:
          type: string
        rightsHolder:
          type: string
        fetchedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: When Fluvigil fetched the values (UTC); null where not known
        stampedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: The provider's own time stamp ("Stand") where its licence keeps it visible
        stationLink:
          type:
          - string
          - 'null'
          description: Origin page of this gauge where the provider demands it
        text:
          type: string
          description: The full notice as plain text
        textShort:
          type:
          - string
          - 'null'
          description: The shortened notice; null for `full-only`
    FloodSituationResponse:
      description: The report (`reportDate`, `generatedAt`, `totalInFlood`, counts `byClass` and `byState`, the most affected gauges in `topStations`) and its summary text (null while none exists).
      type: object
      properties:
        report:
          type: object
          properties:
            reportDate:
              type: string
            generatedAt:
              type: string
              format: date-time
            totalInFlood:
              type: integer
            byClass:
              type: array
              items:
                type: object
                properties:
                  lhpClass:
                    type: integer
                  count:
                    type: integer
            byState:
              type: array
              items:
                type: object
                properties:
                  federalState:
                    type: string
                  floodCount:
                    type: integer
                  maxClass:
                    type: integer
            topStations:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  slug:
                    type:
                    - string
                    - 'null'
                  name:
                    type: string
                  water:
                    type:
                    - string
                    - 'null'
                  lhpClass:
                    type: integer
                  lhpClassName:
                    type:
                    - string
                    - 'null'
                  valueCentimeters:
                    type:
                    - number
                    - 'null'
                    description: Level at the time of the report; null where the gauge has no notice.
                  measuredAt:
                    type:
                    - string
                    - 'null'
                    format: date-time
                    description: When that level was measured (UTC); null where the level is withheld, the gauge reported no time, or the report was stored before the time was kept.
                  sourceNotice:
                    oneOf:
                    - $ref: '#/components/schemas/SourceNotice'
                    - type: 'null'
        summaryText:
          type:
          - string
          - 'null'
    SourceNotice:
      description: 'Conditions a data provider attaches to its gauges, set wherever a gauge''s values are delivered. The fields of `SourceNoticePart` describe the source of the values; `parts` lists every source involved (the value source first, the station source after it where they differ), and `form` is `full-only` as soon as one part is. `sourceLine`, `rawData`, `disclaimer`, `noOfficialWarning` and `termsPath` are the older plain-text fields and stay for existing clients; the three that a provider does not demand are null.

        '
      allOf:
      - $ref: '#/components/schemas/SourceNoticePart'
      - type: object
        properties:
          parts:
            type: array
            description: The notice of every source involved, each with the fields from `id` to `textShort`.
            items:
              $ref: '#/components/schemas/SourceNoticePart'
          sourceLine:
            type: string
            description: Credit line of the provider
          rawData:
            type:
            - string
            - 'null'
            description: Notice that the values are preliminary or unchecked raw data
          disclaimer:
            type:
            - string
            - 'null'
            description: Liability disclaimer with the pointer to the terms
          noOfficialWarning:
            type:
            - string
            - 'null'
            description: Statement that the presentation is no official warning
          termsPath:
            type: string
            description: Path of the terms page holding the full liability disclaimer
  parameters:
    Locale:
      name: locale
      in: query
      description: Language of the generated summary and of the labels around the notice.
      schema:
        type: string
        enum:
        - de
        - en
        default: de
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key