Bright Sky Internals API

openapi: 3.2.0
info:
  title: Bright Sky Internals 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: Internals
paths:
  /sources:
    get:
      tags:
      - Internals
      summary: Weather sources (stations)
      description: 'Return a list of all Bright Sky sources matching the given location

        criteria, ordered by distance.


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

        `wmo_station_id`, or `source_id`.'
      operationId: getSources
      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: 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.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourcesResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /synop:
    get:
      tags:
      - Internals
      summary: Raw SYNOP observations
      description: 'Returns a list of ten-minutely SYNOP observations for the time range given

        by `date` and `last_date`. Note that Bright Sky only stores SYNOP

        observations from the past 30 hours.


        To set the weather station for which to retrieve records, you must supply

        one of `dwd_station_id`, `wmo_station_id`, or `source_id`. The `/synop`

        endpoint does not support `lat` and `lon`; use the

        `/sources` endpoint if you need to retrieve a

        SYNOP station ID close to a given location.


        SYNOP observations are stored as they were reported, which in particular

        implies that many parameters are only available at certain timestamps. For

        example, most stations report `sunshine_60` only on the full hour, and

        `sunshine_30` only at 30 minutes past the full hour (i.e. also not on the

        full hour). Check out the

        `/current_weather` endpoint for an

        opinionated compilation of recent SYNOP records into a single "current

        weather" record.'
      operationId: getSynop
      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: 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/SynopResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
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
    SynopResponse:
      properties:
        weather:
          items:
            $ref: '#/components/schemas/SynopRecord'
          type: array
          title: Weather
        sources:
          items:
            $ref: '#/components/schemas/Source'
          type: array
          title: Sources
      type: object
      title: SynopResponse
    SynopRecord:
      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_10:
          type: number
          title: Precipitation 10
          description: Total precipitation during previous 10 minutes
          examples:
          - 0.8
          nullable: true
        precipitation_30:
          type: number
          title: Precipitation 30
          description: Total precipitation during previous 30 minutes
          examples:
          - 1.2
          nullable: true
        precipitation_60:
          type: number
          title: Precipitation 60
          description: Total precipitation during previous 60 minutes
          examples:
          - 1.8
          nullable: true
        solar_10:
          type: number
          title: Solar 10
          description: Solar irradiation during previous 10 minutes
          examples:
          - 0.081
          nullable: true
        solar_30:
          type: number
          title: Solar 30
          description: Solar irradiation during previous 30 minutes
          examples:
          - 0.207
          nullable: true
        solar_60:
          type: number
          title: Solar 60
          description: Solar irradiation during previous 60 minutes
          examples:
          - 0.48
          nullable: true
        sunshine_30:
          type: integer
          title: Sunshine 30
          description: Sunshine duration during previous 30 minutes
          examples:
          - 28
          nullable: true
        sunshine_60:
          type: integer
          title: Sunshine 60
          description: Sunshine duration during previous 60 minutes
          examples:
          - 52
          nullable: true
        wind_direction_10:
          type: integer
          title: Wind Direction 10
          description: Mean wind direction during previous 10 minutes, 10 m above the ground
          examples:
          - 70
          nullable: true
        wind_direction_30:
          type: integer
          title: Wind Direction 30
          description: Mean wind direction during previous 30 minutes, 10 m above the ground
          examples:
          - 70
          nullable: true
        wind_direction_60:
          type: integer
          title: Wind Direction 60
          description: Mean wind direction during previous 60 minutes, 10 m above the ground
          examples:
          - 70
          nullable: true
        wind_speed_10:
          type: number
          title: Wind Speed 10
          description: Mean wind speed during previous 10 minutes, 10 m above the ground
          examples:
          - 12.6
          nullable: true
        wind_speed_30:
          type: number
          title: Wind Speed 30
          description: Mean wind speed during previous 30 minutes, 10 m above the ground
          examples:
          - 12.6
          nullable: true
        wind_speed_60:
          type: number
          title: Wind Speed 60
          description: Mean wind speed during previous 60 minutes, 10 m above the ground
          examples:
          - 12.6
          nullable: true
        wind_gust_direction_10:
          type: integer
          title: Wind Gust Direction 10
          description: Direction of maximum wind gust during previous 10 minutes, 10 m above the ground
          examples:
          - 50
          nullable: true
        wind_gust_direction_30:
          type: integer
          title: Wind Gust Direction 30
          description: Direction of maximum wind gust during previous 30 minutes, 10 m above the ground
          examples:
          - 50
          nullable: true
        wind_gust_direction_60:
          type: integer
          title: Wind Gust Direction 60
          description: Direction of maximum wind gust during previous 60 minutes, 10 m above the ground
          examples:
          - 50
          nullable: true
        wind_gust_speed_10:
          type: number
          title: Wind Gust Speed 10
          description: Speed of maximum wind gust during previous 10 minutes, 10 m above the ground
          examples:
          - 33.5
          nullable: true
        wind_gust_speed_30:
          type: number
          title: Wind Gust Speed 30
          description: Speed of maximum wind gust during previous 30 minutes, 10 m above the ground
          examples:
          - 33.5
          nullable: true
        wind_gust_speed_60:
          type: number
          title: Wind Gust Speed 60
          description: Speed of maximum wind gust during previous 60 minutes, 10 m above the ground
          examples:
          - 33.5
          nullable: true
        sunshine_10:
          type: integer
          title: Sunshine 10
          description: Sunshine duration during previous 10 minutes
          examples:
          - 8
          nullable: true
      type: object
      title: SynopRecord
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SourcesResponse:
      properties:
        sources:
          items:
            $ref: '#/components/schemas/Source'
          type: array
          title: Sources
      type: object
      title: SourcesResponse
    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