Fluvigil Rivers API

openapi: 3.2.0
info:
  title: Fluvigil Public Rivers 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: Rivers
paths:
  /rivers/{slug}:
    get:
      summary: A river with its gauges in order of the river's course
      operationId: getRiver
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      - name: locale
        in: query
        description: Language of the labels around the notices; the approved wording of a provider stays German.
        schema:
          type: string
          enum:
          - de
          - en
      responses:
        '200':
          description: The river; every gauge carries its own `sourceNotice`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  river:
                    type: object
                    properties:
                      slug:
                        type: string
                      water:
                        type: string
                      stations:
                        type: array
                        items:
                          $ref: '#/components/schemas/StationListItem'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Rivers
components:
  schemas:
    FloodWarning:
      type: object
      description: 'A flood warning published for a whole river section. It describes the reach the gauge stands in, never the gauge''s own level, and the official warning stays with the named service.

        '
      properties:
        provider:
          type: string
          enum:
          - vigicrues
        providerLabel:
          type: string
          description: Credit line of the warning service.
        sectionCode:
          type: string
          description: The provider's section code, e.g. SA13.
        sectionName:
          type: string
        level:
          type: integer
          minimum: 1
          maximum: 4
          description: 1 no particular vigilance, 2 vigilance, 3 strong flood, 4 exceptional flood.
        levelLabel:
          type: string
        severity:
          type: string
          enum:
          - low
          - normal
          - elevated
          - high
          - veryHigh
          - unknown
        publishedAt:
          type:
          - string
          - 'null'
          format: date-time
        infoUrl:
          type: string
        assignmentSource:
          type: string
          enum:
          - list
          - geometry
          description: 'Whether the provider''s own station list named this gauge on this section (''list''), or it was matched to the nearest section by geographic distance because the list did not (''geometry'') — a weaker match, worth treating with more caution.

            '
    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`
    LevelClassification:
      type: object
      description: 'Deterministic plain-language interpretation of the current level, anchored on what the threshold means (reporting level / statistical reference). Never asserts location-specific effects, which are Land-dependent and not verifiable per station.

        '
      properties:
        severity:
          type: string
          enum:
          - low
          - normal
          - elevated
          - high
          - veryHigh
          - unknown
        headline:
          type: string
        description:
          type: string
    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
    StationListItem:
      type: object
      properties:
        id:
          type: string
        source:
          $ref: '#/components/schemas/GaugeSource'
        measurementType:
          type: string
          enum:
          - river
          - groundwater
          - sea_level
          - reservoir
        waterClass:
          $ref: '#/components/schemas/WaterClass'
        levelDatum:
          type:
          - string
          - 'null'
          enum:
          - swiss_sea_level
          - adriatic_sea_level
          - normal_null
          - dvr90
          - null
          description: 'Height datum of a gauge that reports an absolute elevation instead of a level over its gauge zero; null for a level over gauge zero. Such a gauge stores the elevation times the detail''s `valueDivisor` in `latestValueCentimeters` and carries no flood classification.

            '
        name:
          type: string
        water:
          type:
          - string
          - 'null'
        latitude:
          type: number
        longitude:
          type: number
        federalState:
          type:
          - string
          - 'null'
        infoLink:
          type:
          - string
          - 'null'
        sourceNotice:
          oneOf:
          - $ref: '#/components/schemas/SourceNotice'
          - type: 'null'
          description: 'The notice the gauge''s provider demands wherever its values are shown; null where none can be built, and the gauge then delivers no value. Pass it on with the values.

            '
        latestValueCentimeters:
          type:
          - number
          - 'null'
        latestMeasuredAt:
          type:
          - string
          - 'null'
          format: date-time
        refreshCadenceHours:
          type:
          - integer
          - 'null'
          minimum: 1
          description: 'How often the gauge''s source publishes new values, in hours, when that is slower than the gauge type''s own freshness window (24 for a daily export). A value counts as outdated only after twice this interval; null when the type''s window applies.

            '
        levelState:
          type:
          - string
          - 'null'
          description: PEGELONLINE MNW/MHW classification
        lhpClass:
          type:
          - integer
          - 'null'
          minimum: -1
          maximum: 4
        lhpClassName:
          type:
          - string
          - 'null'
        isActive:
          type: boolean
        floodWarning:
          oneOf:
          - $ref: '#/components/schemas/FloodWarning'
          - type: 'null'
          description: 'The warning of the river section this gauge stands on, for countries that publish their flood warning per section instead of per gauge (France, Vigicrues). Null for every other gauge and for a French gauge on no monitored section.

            '
        levelClassification:
          allOf:
          - $ref: '#/components/schemas/LevelClassification'
          description: 'Coarse plain-language summary for map/list use, derived without a threshold join (from lhpClass / levelState). The station detail carries the precise, threshold-based classification inside `levelContext`.

            '
    WaterClass:
      type: string
      enum:
      - river
      - lake
      - coast
      - groundwater
      description: 'The group a gauge belongs to on the map and in filters: rivers, lakes and reservoirs, coast and tide, groundwater. Stored per gauge; a tidal river section is `river` by `measurementType` and `coast` by class.

        '
    GaugeSource:
      type: string
      description: Key of the data source a station comes from.
      enum:
      - pegelonline
      - lhp
      - gld
      - ltv
      - nlwkn
      - ch
      - at
      - cz
      - lu
      - it-bz
      - fr
      - dk-dmi
      - dk
      - nl
      - pl
      - be
  responses:
    NotFound:
      description: Station does not exist.
    RateLimited:
      description: The hourly request budget for the tier is exhausted.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key