Bright Sky Weather API

openapi: 3.2.0
info:
  title: Bright Sky Weather 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: Weather
paths:
  /weather:
    get:
      summary: Hourly weather (including forecasts)
      description: 'Returns a list of hourly weather records (and/or forecasts) for the time

        range given by `date` and `last_date`.


        To set the location for which to retrieve records (and/or forecasts), you

        must supply both `lat` and `lon` _or_ one of `dwd_station_id`,

        `wmo_station_id`, or `source_id`.'
      operationId: getWeather
      parameters:
      - name: date
        in: query
        required: true
        schema:
          type: string
          format: date-time
          description: Timestamp of first weather record (or forecast) to retrieve, in ISO 8601 format. May contain time and/or UTC offset.
          examples:
          - '2023-08-07'
          - 2023-08-07T08:00+02:00
          title: Date
        description: Timestamp of first weather record (or forecast) to retrieve, in ISO 8601 format. May contain time and/or UTC offset.
      - name: last_date
        in: query
        required: false
        schema:
          type: string
          format: date-time
          description: Timestamp of last weather record (or forecast) to retrieve, in ISO 8601 format. Will default to `date + 1 day`.
          examples:
          - '2023-08-08'
          - 2023-08-07T23:00+02:00
          title: Last Date
        description: Timestamp of last weather record (or forecast) to retrieve, in ISO 8601 format. Will default to `date + 1 day`.
      - 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: max_dist
        in: query
        required: false
        schema:
          type: integer
          maximum: 500000
          minimum: 0
          description: Maximum distance of record location from the location given by `lat` and `lon`, in meters. Only has an effect when using `lat` and `lon`.
          examples:
          - 10000
          default: 50000
          title: Max Dist
        description: Maximum distance of record location from the location given by `lat` and `lon`, in meters. Only has an effect when using `lat` and `lon`.
      - name: dwd_station_id
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: DWD station ID, typically five alphanumeric characters. You can supply multiple station IDs separated by commas, ordered from highest to lowest priority.
          examples:
          - '01766'
          - 00420,00053,00400
          title: Dwd Station Id
        description: DWD station ID, typically five alphanumeric characters. You can supply multiple station IDs separated by commas, ordered from highest to lowest priority.
      - name: wmo_station_id
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: WMO station ID, typically five alphanumeric characters. You can supply multiple station IDs separated by commas, ordered from highest to lowest priority.
          examples:
          - '10315'
          - G005,F451,10389
          title: Wmo Station Id
        description: WMO station ID, typically five alphanumeric characters. You can supply multiple station IDs separated by commas, ordered from highest to lowest priority.
      - name: source_id
        in: query
        required: false
        schema:
          type: array
          items:
            type: integer
          description: Bright Sky source ID, as retrieved from the [`/sources` endpoint](/operations/getSources). You can supply multiple source IDs separated by commas, ordered from highest to lowest priority.
          examples:
          - '1234'
          - 1234,2345
          title: Source Id
        description: Bright Sky source ID, as retrieved from the [`/sources` endpoint](/operations/getSources). You can supply multiple source IDs separated by commas, ordered from highest to lowest priority.
      - 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.
      - name: units
        in: query
        required: false
        schema:
          enum:
          - dwd
          - si
          type: string
          description: "Physical units in which meteorological parameters will be returned. Set to `si` to use <a href=\"https://en.wikipedia.org/wiki/International_System_of_Units\">SI units</a> (except for precipitation, which is always measured in millimeters). The default `dwd` option uses a set of units that is more common in meteorological applications and civil use:\n<table>\n  <tr><td></td><td>DWD</td><td>SI</td></tr>\n  <tr><td>Cloud cover</td><td>%</td><td>%</td></tr>\n  <tr><td>Dew point</td><td>°C</td><td>K</td></tr>\n  <tr><td>Precipitation</td><td>mm</td><td><s>kg / m²</s> <strong>mm</strong></td></tr>\n  <tr><td>Precipitation probability</td><td>%</td><td>%</td></tr>\n  <tr><td>Pressure</td><td>hPa</td><td>Pa</td></tr>\n  <tr><td>Relative humidity</td><td>%</td><td>%</td></tr>\n  <tr><td>Solar irradiation</td><td>kWh / m²</td><td>J / m²</td></tr>\n  <tr><td>Sunshine</td><td>min</td><td>s</td></tr>\n  <tr><td>Temperature</td><td>°C</td><td>K</td></tr>\n  <tr><td>Visibility</td><td>m</td><td>m</td></tr>\n  <tr><td>Wind (gust) direction</td><td>°</td><td>°</td></tr>\n  <tr><td>Wind (gust) speed</td><td>km / h</td><td>m / s</td></tr>\n</table>"
          default: dwd
          title: Units
        description: "Physical units in which meteorological parameters will be returned. Set to `si` to use <a href=\"https://en.wikipedia.org/wiki/International_System_of_Units\">SI units</a> (except for precipitation, which is always measured in millimeters). The default `dwd` option uses a set of units that is more common in meteorological applications and civil use:\n<table>\n  <tr><td></td><td>DWD</td><td>SI</td></tr>\n  <tr><td>Cloud cover</td><td>%</td><td>%</td></tr>\n  <tr><td>Dew point</td><td>°C</td><td>K</td></tr>\n  <tr><td>Precipitation</td><td>mm</td><td><s>kg / m²</s> <strong>mm</strong></td></tr>\n  <tr><td>Precipitation probability</td><td>%</td><td>%</td></tr>\n  <tr><td>Pressure</td><td>hPa</td><td>Pa</td></tr>\n  <tr><td>Relative humidity</td><td>%</td><td>%</td></tr>\n  <tr><td>Solar irradiation</td><td>kWh / m²</td><td>J / m²</td></tr>\n  <tr><td>Sunshine</td><td>min</td><td>s</td></tr>\n  <tr><td>Temperature</td><td>°C</td><td>K</td></tr>\n  <tr><td>Visibility</td><td>m</td><td>m</td></tr>\n  <tr><td>Wind (gust) direction</td><td>°</td><td>°</td></tr>\n  <tr><td>Wind (gust) speed</td><td>km / h</td><td>m / s</td></tr>\n</table>"
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeatherResponse'
        '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:
      - Weather
components:
  schemas:
    Source:
      properties:
        id:
          type: integer
          title: Id
          description: Bright Sky source ID
          examples:
          - 6007
        dwd_station_id:
          type: string
          title: Dwd Station Id
          description: DWD weather station ID
          examples:
          - '01766'
          nullable: true
        wmo_station_id:
          type: string
          title: Wmo Station Id
          description: WMO weather station ID
          examples:
          - '10315'
          nullable: true
        station_name:
          type: string
          title: Station Name
          description: DWD weather station name
          examples:
          - Münster/Osnabrück
          nullable: true
        observation_type:
          type: string
          enum:
          - historical
          - current
          - synop
          - forecast
          title: Observation Type
          description: Source type
        first_record:
          type: string
          format: date-time
          title: First Record
          description: Timestamp of first available record for this source
          examples:
          - 2010-01-01T00:00+02:00
        last_record:
          type: string
          format: date-time
          title: Last Record
          description: Timestamp of latest available record for this source
          examples:
          - 2023-08-07T12:40+02:00
        lat:
          type: number
          title: Lat
          description: Station latitude, in decimal degrees
          examples:
          - 52.1344
        lon:
          type: number
          title: Lon
          description: Station longitude, in decimal degrees
          examples:
          - 7.6969
        height:
          type: number
          title: Height
          description: Station height, in meters
          examples:
          - 47.8
        distance:
          type: integer
          title: Distance
          description: Distance of weather station to the requested `lat` and `lon` (if given), in meters
          examples:
          - 16365
      type: object
      title: Source
    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
    WeatherResponse:
      properties:
        weather:
          items:
            $ref: '#/components/schemas/WeatherRecord'
          type: array
          title: Weather
        sources:
          items:
            $ref: '#/components/schemas/Source'
          type: array
          title: Sources
      type: object
      title: WeatherResponse
    WeatherRecord:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: ISO 8601-formatted timestamp of this weather record
          examples:
          - '2023-08-07T12:30:00+00:00'
        source_id:
          type: integer
          title: Source Id
          description: Bright Sky source ID for this record
          examples:
          - 238685
        cloud_cover:
          type: number
          title: Cloud Cover
          description: Total cloud cover at timestamp
          examples:
          - 12.1
          nullable: true
        condition:
          type: string
          enum:
          - dry
          - fog
          - rain
          - sleet
          - snow
          - hail
          - thunderstorm
          title: Condition
          description: Current weather conditions. Unlike the numerical parameters, this field is not taken as-is from the raw data (because it does not exist), but is calculated from different fields in the raw data as a best effort. Not all values are available for all source types.
          nullable: true
        dew_point:
          type: number
          title: Dew Point
          description: Dew point at timestamp, 2 m above ground
          examples:
          - -2.5
          nullable: true
        icon:
          type: string
          enum:
          - clear-day
          - clear-night
          - partly-cloudy-day
          - partly-cloudy-night
          - cloudy
          - fog
          - wind
          - rain
          - sleet
          - snow
          - hail
          - thunderstorm
          title: Icon
          description: Icon alias suitable for the current weather conditions. Unlike the numerical parameters, this field is not taken as-is from the raw data (because it does not exist), but is calculated from different fields in the raw data as a best effort. Not all values are available for all source types.
          nullable: true
        pressure_msl:
          type: number
          title: Pressure Msl
          description: Atmospheric pressure at timestamp, reduced to mean sea level
          examples:
          - 1015.1
          nullable: true
        relative_humidity:
          type: integer
          title: Relative Humidity
          description: Relative humidity at timestamp
          examples:
          - 40
          nullable: true
        temperature:
          type: number
          title: Temperature
          description: Air temperature at timestamp, 2 m above the ground
          examples:
          - 10.6
          nullable: true
        visibility:
          type: integer
          title: Visibility
          description: Visibility at timestamp
          examples:
          - 50000
          nullable: true
        fallback_source_ids:
          additionalProperties: true
          type: object
          title: Fallback Source Ids
          description: Object mapping meteorological parameters to the source IDs of alternative sources that were used to fill up missing values in the main source
          examples:
          - pressure_msl: 11831
            wind_speed_30: 11831
        precipitation:
          type: number
          title: Precipitation
          description: Total precipitation during previous 60 minutes
          examples:
          - 1.8
          nullable: true
        solar:
          type: number
          title: Solar
          description: Solar irradiation during previous 60 minutes
          examples:
          - 0.563
          nullable: true
        sunshine:
          type: integer
          title: Sunshine
          description: Sunshine duration during previous 60 minutes
          examples:
          - 58
          nullable: true
        wind_direction:
          type: integer
          title: Wind Direction
          description: Mean wind direction during previous hour, 10 m above the ground
          examples:
          - 70
          nullable: true
        wind_speed:
          type: number
          title: Wind Speed
          description: Mean wind speed during previous hour, 10 m above the ground
          examples:
          - 12.6
          nullable: true
        wind_gust_direction:
          type: integer
          title: Wind Gust Direction
          description: Direction of maximum wind gust during previous hour, 10 m above the ground
          examples:
          - 50
          nullable: true
        wind_gust_speed:
          type: number
          title: Wind Gust Speed
          description: Speed of maximum wind gust during previous hour, 10 m above the ground
          examples:
          - 33.5
          nullable: true
        precipitation_probability:
          type: integer
          title: Precipitation Probability
          description: Probability of more than 0.1 mm of precipitation in the previous hour (only available in forecasts)
          examples:
          - 46
          nullable: true
        precipitation_probability_6h:
          type: integer
          title: Precipitation Probability 6H
          description: Probability of more than 0.2 mm of precipitation in the previous 6 hours (only available in forecasts at 0:00, 6:00, 12:00, and 18:00 UTC)
          examples:
          - 75
          nullable: true
      type: object
      title: WeatherRecord
    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