Bright Sky Alerts API

openapi: 3.2.0
info:
  title: Bright Sky Alerts API
  description: 'Bright Sky is a free and open-source weather API. It aims to provide an easy-to-use gateway to weather data that the DWD – Germany''s meteorological service – publishes on their open data server.


    The public instance at `https://api.brightsky.dev/` is free-to-use for all purposes, **no API key required**! Please note that the DWD''s Terms of Use apply to all data you retrieve through the API.


    > This documentation is generated from an OpenAPI specification. The current version is available from https://api.brightsky.dev/openapi.json.


    ## Quickstart


    * Check out `/current_weather` if you want to know what the weather''s like _right now_.

    * Check out `/weather` for hourly weather observations and forecasts.

    * Check out `/radar` if you''re looking for a high-resolution rain radar.

    * Check out `/alerts` if you''re interested in weather alerts.


    ... or keep reading below for some background information.


    ## Good to Know


    * **Geographical coverage**: due to its nature as German meteorological service, the observations published by the DWD have a strong focus on Germany. The _forecasts_ cover the whole world, albeit at a much lower density outside of Germany.

    * **Historical coverage**: Bright Sky serves historical data going back to January 1st, 2010. If you need data that goes further back, check out our infrastructure repository to easily set up your own instance of Bright Sky!

    * **Source IDs**: Bright Sky''s _source IDs_ are a technical artifact and – unlike the DWD station IDs and WMO station IDs – have no meaning in the real world. When making requests to Bright Sky, try to avoid them and supply lat/lon or station IDs instead.


    ## Useful Links


    * Bright Sky source code and issue tracking

    * Bright Sky infrastructure configuration

    * DWD Open Data landing page

    * Additional explanation files for DWD Open Data, including:

    * List of main observation stations

    * List of additional observation stations

    * List of MOSMIX stations

    * List of meteorological parameters

    * DWD Open Data FAQ (German)

    * DWD Copyright information


    ## Data Sources


    All data available through Bright Sky is taken or derived from data on the DWD open data server:


    * **Current weather / SYNOP**:

    * https://opendata.dwd.de/weather/weather_reports/synoptic/germany/json/

    * **Hourly weather**:

    * Historical: https://opendata.dwd.de/climate_environment/CDC/observations_germany/climate/

    * Current day: https://opendata.dwd.de/weather/weather_reports/poi/

    * Forecasts: https://opendata.dwd.de/weather/local_forecasts/mos/

    * **Radar**:

    * https://opendata.dwd.de/weather/radar/composite/rv/

    * **Alerts**:

    * https://opendata.dwd.de/weather/alerts/cap/COMMUNEUNION_DWD_STAT/'
  contact:
    name: Jakob de Maeyer
    url: https://brightsky.dev/
    email: jakob@brightsky.dev
  license:
    name: MIT License
    identifier: MIT
  version: 2.2.12
servers:
- url: https://api.brightsky.dev
tags:
- name: Alerts
paths:
  /alerts:
    get:
      summary: Alerts
      description: 'Returns a list of weather alerts for the given location, or all weather

        alerts if no location given.


        If you supply either `warn_cell_id` or both `lat` and `lon`, Bright Sky

        will return additional information on that cell in the `location` field.

        Warn cell IDs are municipality (_Gemeinde_) cell IDs.


        ### Notes


        * The DWD divides Germany''s area into roughly 11,000 "cells" based on

        municipalities (_Gemeinden_), and issues warnings for each of these

        cells. Most warnings apply to many cells.

        * Bright Sky will supply information on the cell that a given lat/lon

        belongs to in the `location` field.

        * There is also a set of roughly 400 cells based on districts

        (_Landkreise_) that is not supported by Bright Sky.

        * The complete list of cells can be found on the DWD GeoServer (see below).


        ### Additional resources


        * Live demo of a simple interactive alerts map

        * Source for alerts map demo

        * Map view of all current alerts by the DWD

        * List of municipality cells

        * List of district cells (*not used by Bright Sky!*)

        * Raw data on the Open Data Server

        * DWD Documentation on alert fields and their allowed contents (English)

        * DWD Documentation on alert fields and their allowed contents (German)'
      operationId: getAlerts
      parameters:
      - name: lat
        in: query
        required: false
        schema:
          type: number
          maximum: 90
          minimum: -90
          description: Latitude in decimal degrees.
          examples:
          - 52.52
          - 51.55
          title: Lat
        description: Latitude in decimal degrees.
      - name: lon
        in: query
        required: false
        schema:
          type: number
          maximum: 180
          minimum: -180
          description: Longitude in decimal degrees.
          examples:
          - 13.4
          - 9.9
          title: Lon
        description: Longitude in decimal degrees.
      - name: warn_cell_id
        in: query
        required: false
        schema:
          type: integer
          description: Municipality warn cell ID.
          examples:
          - 803159016
          - 705515101
          title: Warn Cell Id
        description: Municipality warn cell ID.
      - name: tz
        in: query
        required: false
        schema:
          type: string
          description: Timezone in which record timestamps will be presented, as <a href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones">tz database name</a>. Will also be used as timezone when parsing `date` and `last_date`, unless these have explicit UTC offsets. If omitted but `date` has an explicit UTC offset, that offset will be used as timezone. Otherwise will default to UTC.
          examples:
          - Europe/Berlin
          - Australia/Darwin
          - Etc/UTC
          title: Tz
        description: Timezone in which record timestamps will be presented, as <a href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones">tz database name</a>. Will also be used as timezone when parsing `date` and `last_date`, unless these have explicit UTC offsets. If omitted but `date` has an explicit UTC offset, that offset will be used as timezone. Otherwise will default to UTC.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertsResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Alerts
components:
  schemas:
    Location:
      properties:
        warn_cell_id:
          type: integer
          title: Warn Cell Id
          description: Municipality warn cell ID of given location
          examples:
          - 803159016
        name:
          type: string
          title: Name
          description: Municipality name
          examples:
          - Stadt Göttingen
        name_short:
          type: string
          title: Name Short
          description: Shortened municipality name
          examples:
          - Göttingen
        district:
          type: string
          title: District
          description: District name
          examples:
          - Göttingen
        state:
          type: string
          title: State
          description: Federal state name
          examples:
          - Niedersachsen
        state_short:
          type: string
          title: State Short
          description: Shortened federal state name
          examples:
          - NI
      type: object
      title: Location
    Alert:
      properties:
        id:
          type: integer
          title: Id
          description: Bright Sky-internal ID for this alert
          examples:
          - 279977
        alert_id:
          type: string
          title: Alert Id
          description: Unique CAP message identifier
          examples:
          - 2.49.0.0.276.0.DWD.PVW.1691344680000.2cf9fad6-dc83-44ba-9e88-f2827439da59
        status:
          type: string
          enum:
          - actual
          - test
          title: Status
          description: Alert status
        effective:
          type: string
          format: date-time
          title: Effective
          description: Alert issue time
          examples:
          - '2023-08-06T17:58:00+00:00'
        onset:
          type: string
          format: date-time
          title: Onset
          description: Expected event begin time
          examples:
          - '2023-08-07T08:00:00+00:00'
        expires:
          type: string
          format: date-time
          title: Expires
          description: Expected event end time
          examples:
          - '2023-08-07T19:00:00+00:00'
          nullable: true
        category:
          type: string
          enum:
          - met
          - health
          title: Category
          description: Alert category, meteorological message (`met`) or public health related message (`health`)
          nullable: true
        response_type:
          type: string
          enum:
          - prepare
          - allclear
          - none
          - monitor
          title: Response Type
          description: Code denoting type of action recommended for target audience
          nullable: true
        urgency:
          type: string
          enum:
          - immediate
          - future
          title: Urgency
          description: Alert time frame
          nullable: true
        severity:
          type: string
          enum:
          - minor
          - moderate
          - severe
          - extreme
          title: Severity
          description: Alert severity
          nullable: true
        certainty:
          type: string
          enum:
          - observed
          - likely
          title: Certainty
          description: Alert certainty
          nullable: true
        event_code:
          type: integer
          title: Event Code
          description: DWD event code
          examples:
          - 51
          nullable: true
        event_en:
          type: string
          title: Event En
          description: Label for DWD event code (English)
          examples:
          - wind gusts
          nullable: true
        event_de:
          type: string
          title: Event De
          description: Label for DWD event code (German)
          examples:
          - WINDBÖEN
          nullable: true
        headline_en:
          type: string
          title: Headline En
          description: Alert headline (English)
          examples:
          - Official WARNING of WIND GUSTS
        headline_de:
          type: string
          title: Headline De
          description: Alert headline (German)
          examples:
          - Amtliche WARNUNG vor WINDBÖEN
        description_en:
          type: string
          title: Description En
          description: Alert description (English)
          examples:
          - 'There is a risk of wind gusts (level 1 of 4).

            Max. gusts: 50-60 km/h; Wind direction: west; Increased gusts: near showers and in exposed locations < 70 km/h'
        description_de:
          type: string
          title: Description De
          description: Alert description (German)
          examples:
          - Es treten Windböen mit Geschwindigkeiten zwischen 50 km/h (14 m/s, 28 kn, Bft 7) und 60 km/h (17 m/s, 33 kn, Bft 7) aus westlicher Richtung auf. In Schauernähe sowie in exponierten Lagen muss mit Sturmböen bis 70 km/h (20 m/s, 38 kn, Bft 8) gerechnet werden.
        instruction_en:
          type: string
          title: Instruction En
          description: Additional instructions and safety advice (English)
          examples:
          - 'NOTE: Be aware of the following possible dangers: The downpours can cause temporary traffic disruption.'
          nullable: true
        instruction_de:
          type: string
          title: Instruction De
          description: Additional instructions and safety advice (German)
          examples:
          - 'ACHTUNG! Hinweis auf mögliche Gefahren: Während des Platzregens sind kurzzeitig Verkehrsbehinderungen möglich.'
          nullable: true
      type: object
      title: Alert
    NotFoundResponse:
      properties:
        detail:
          type: string
          title: Detail
          default: Error details
      type: object
      title: NotFoundResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AlertsResponse:
      properties:
        alerts:
          items:
            $ref: '#/components/schemas/Alert'
          type: array
          title: Alerts
        location:
          $ref: '#/components/schemas/Location'
          nullable: true
      type: object
      title: AlertsResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError