openapi: 3.0.2
info:
  title: Meteonorm API
  version: 1.0.0
servers:
  - url: "https://api.meteonorm.com/v1"
    description: Production server
security:
  - bearerAuth: []
paths:
  /climate/tmy:
    get:
      tags:
        - climate
      operationId: retrieveClimateTMY
      summary: "/climate/tmy"
      description: >
        Typical meteorological year (TMY) for a location.
      parameters:
        - $ref: "#/components/parameters/LatitudeQueryParam"
        - $ref: "#/components/parameters/LongitudeQueryParam"
        - $ref: "#/components/parameters/AltitudeQueryParam"
        - $ref: "#/components/parameters/SurfaceAzimuthQueryParam"
        - $ref: "#/components/parameters/SurfaceTiltQueryParam"
        - $ref: "#/components/parameters/SituationQueryParam"
        - $ref: "#/components/parameters/HorizonQueryParam"
        - $ref: "#/components/parameters/ClimateParametersQueryParam"
        - $ref: "#/components/parameters/FixedAlbedoQueryParam"
        - $ref: "#/components/parameters/TurbidityQueryParam"
        - $ref: "#/components/parameters/ClimateFrequencyQueryParam"
        - $ref: "#/components/parameters/ResponseFormatQueryParam"
        - $ref: "#/components/parameters/RadiationMinuteModelQueryParam"
        - $ref: "#/components/parameters/DiffuseRadiationModelQueryParam"
        - $ref: "#/components/parameters/TiltRadiationModelQueryParam"
        - $ref: "#/components/parameters/RandomSeedQueryParam"
        - $ref: "#/components/parameters/ClearSkyModelQueryParam"
        - $ref: "#/components/parameters/ExtremeSettingQueryParam"
        - $ref: "#/components/parameters/DataVersionQueryParam"
        - $ref: "#/components/parameters/FutureScenarioQueryParam"
        - $ref: "#/components/parameters/FutureYearQueryParam"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClimateResponse"
            text/*:
              schema:
                type: string
                format: text
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: Service unavailable

  /forecast/basic:
    get:
      tags:
        - forecast
      operationId: retrieveForecastBasic
      summary: "/forecast/basic"
      description: >
        Solar forecast with medium accuracy. Based on global
        numerical weather prediction models.
      parameters:
        - $ref: "#/components/parameters/LatitudeQueryParam"
        - $ref: "#/components/parameters/LongitudeQueryParam"
        - $ref: "#/components/parameters/ForecastParametersQueryParam"
        - $ref: "#/components/parameters/ForecastStartTimeQueryParam"
        - $ref: "#/components/parameters/ForecastEndTimeQueryParam"
        - $ref: "#/components/parameters/SurfaceAzimuthQueryParam"
        - $ref: "#/components/parameters/SurfaceTiltQueryParam"
        - $ref: "#/components/parameters/HorizonQueryParam"
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForecastResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: Service unavailable

  /forecast/precision:
    get:
      tags:
        - forecast
      operationId: retrieveForecastPrecision
      summary: "/forecast/precision"
      description: >
        Solar forecast with high accuracy.
        For the next few hours, the forecast is based on our
        nowcasting technology.
      parameters:
        - $ref: "#/components/parameters/LatitudeQueryParam"
        - $ref: "#/components/parameters/LongitudeQueryParam"
        - $ref: "#/components/parameters/ForecastParametersQueryParam"
        - $ref: "#/components/parameters/ForecastStartTimeQueryParam"
        - $ref: "#/components/parameters/ForecastEndTimeQueryParam"
        - $ref: "#/components/parameters/ForecastPrecisionFrequencyQueryParam"
        - $ref: "#/components/parameters/SurfaceAzimuthQueryParam"
        - $ref: "#/components/parameters/SurfaceTiltQueryParam"
        - $ref: "#/components/parameters/HorizonQueryParam"
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForecastResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: Service unavailable

  /observation/realtime:
    get:
      tags:
        - observation
      operationId: retrieveObservationRealtime
      summary: "/observation/realtime"
      description: >
        Real-time irradiance data for the past 7 days, based on weather satellites.
        Updated every 15 minutes.
      parameters:
        - $ref: "#/components/parameters/LatitudeQueryParam"
        - $ref: "#/components/parameters/LongitudeQueryParam"
        - $ref: "#/components/parameters/ObservationParametersQueryParam"
        - $ref: "#/components/parameters/ObservationRealtimeStartTimeQueryParam"
        - $ref: "#/components/parameters/ObservationRealtimeEndTimeQueryParam"
        - $ref: "#/components/parameters/ObservationFrequencyQueryParam"
        - $ref: "#/components/parameters/SurfaceAzimuthQueryParam"
        - $ref: "#/components/parameters/SurfaceTiltQueryParam"
        - $ref: "#/components/parameters/HorizonQueryParam"
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ObservationResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: Service unavailable

  /observation/training:
    get:
      tags:
        - observation
      operationId: retrieveObservationTraining
      summary: "/observation/training"
      description: >
        Available time period: from 2010 until now.
      parameters:
        - $ref: "#/components/parameters/LatitudeQueryParam"
        - $ref: "#/components/parameters/LongitudeQueryParam"
        - $ref: "#/components/parameters/ObservationParametersQueryParam"
        - $ref: "#/components/parameters/ObservationTrainingStartTimeQueryParam"
        - $ref: "#/components/parameters/ObservationTrainingEndTimeQueryParam"
        - $ref: "#/components/parameters/ObservationFrequencyQueryParam"
        - $ref: "#/components/parameters/SurfaceAzimuthQueryParam"
        - $ref: "#/components/parameters/SurfaceTiltQueryParam"
        - $ref: "#/components/parameters/HorizonQueryParam"
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ObservationResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: Service unavailable

  /horizon:
    get:
      tags:
        - horizon
      operationId: retrieveHorizon
      summary: "/horizon"
      description: Retrieves the 360° horizon for a location
      parameters:
        - $ref: "#/components/parameters/LatitudeQueryParam"
        - $ref: "#/components/parameters/LongitudeQueryParam"
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HorizonResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: Service unavailable

  /altitude:
    get:
      tags:
        - horizon
      operationId: retrieveAltitude
      summary: "/altitude"
      description: >
        Retrieves the altitude in meters for a location.
      parameters:
        - $ref: "#/components/parameters/LatitudeQueryParam"
        - $ref: "#/components/parameters/LongitudeQueryParam"
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AltitudeResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: Service unavailable

components:
  parameters:
    LatitudeQueryParam:
      name: lat
      description: >
        Latitude in degrees (North is positive).
      in: query
      required: true
      schema:
        $ref: "#/components/schemas/Latitude"

    LongitudeQueryParam:
      name: lon
      description: Longitude in degrees (East is positive).
      in: query
      required: true
      schema:
        $ref: "#/components/schemas/Longitude"

    AltitudeQueryParam:
      name: altitude
      description: Altitude in meters above mean sea level or "auto".
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/AltitudeOption"

    SurfaceAzimuthQueryParam:
      name: surface_azimuth
      description: >
        Azimuth angle of the surface.
        <br/>
        • 0° = oriented towards the north</br>
        • 90° = oriented towards the east</br>
        • 180° = oriented towards the south</br>
        • 270° = oriented towards the west
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/SurfaceAzimuth"

    SurfaceTiltQueryParam:
      name: surface_tilt
      description: >
        Tilt angle of the surface.
        <br/>
        • 0° = horizontal<br/>
        • 90° = vertical
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/SurfaceTilt"

    HorizonQueryParam:
      name: horizon
      description: >
        Horizon of the requested location.
        <br/>
        • flat: Flat horizon (all horizon elevations are 0°).<br/>
        • auto: Horizon is determined automatically using a high-resolution digital elevation model with a spatial resolution of approx. 30m.<br/>
        • [comma-separated values]<br/>
        <br/>

        [comma-separated values]: provide 360 integer values representing elevation angles
        (in degrees) of the horizon in 360 directions.
        Elevation angles must be ≥0° and <90°.
        Index corresponds to azimuth:<br/>
          Index 0 = 0° (North)<br/>
          Index 90 = 90° (East)<br/>
          Index 180 = 180° (South)<br/>
          Index 270 = 270° (West)<br/>
        Each value indicates the elevation angle at the corresponding azimuth.
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/Horizon"

    SituationQueryParam:
      name: situation
      description: >
        Local terrain situation.
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/Situation"

    FixedAlbedoQueryParam:
      name: fixed_albedo
      description: >
        Fixed albedo to use. If not set, a default albedo of 0.2 is assumed and albedo changes due to snow fall are modelled.
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/Albedo"

    TurbidityQueryParam:
      name: turbidity
      description: >
        Monthly mean atmospheric Linke turbidity.<br/>
        <br/>
        • auto: turbidity is taken from the Meteonorm database.<br/>
        • [comma-separated values]: 12 floating point values representing monthly atmospheric turbidity.
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/Turbidity"

    DataVersionQueryParam:
      name: data_version
      description: >
        Version of Meteonorm climatological data to be used.
        Allows to compute TMYs based on the data of older Meteonorm versions.
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/DataVersion"

    FutureScenarioQueryParam:
      name: future_scenario
      description: >
        Future climate scenario.
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/FutureScenario"

    FutureYearQueryParam:
      name: future_year
      description: Central year for a 20-year reference period in the future.
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/FutureYear"

    ClimateFrequencyQueryParam:
      name: frequency
      description: Temporal resolution of the resulting time series.
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/ClimateFrequency"

    ForecastPrecisionFrequencyQueryParam:
      name: frequency
      description: Temporal resolution of the resulting time series.
      in: query
      required: false
      schema:
        description: Time series frequency
        type: string
        enum:
          - 1_hour
          - 15_minutes
          - 1_minute
        default: 15_minutes

    ObservationFrequencyQueryParam:
      description: Temporal resolution of the resulting time series.
      name: frequency
      in: query
      required: false
      schema:
        description: Time series frequency
        type: string
        enum:
          - 1_hour
          - 15_minutes
          - 1_minute
        default: 15_minutes

    RadiationMinuteModelQueryParam:
      name: radiation_minute_model
      description: >
        Radiation model to be used for minute computation.
        This option has only an effect when computing minute time series.
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/RadiationMinuteModel"

    DiffuseRadiationModelQueryParam:
      name: diffuse_radiation_model
      description: Algorithm to be used to compute diffuse irradiance from global irradiance.
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/DiffuseRadiationModel"

    TiltRadiationModelQueryParam:
      name: tilt_radiation_model
      description: Algorithm to be used to compute tilted irradiance.
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/TiltRadiationModel"

    RandomSeedQueryParam:
      name: random_seed
      description: >
        Random seed to be used for stochastic processes.
        Two identical requests with the same random seed will yield identical results.
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/RandomSeed"

    ClearSkyModelQueryParam:
      name: clear_sky_radiation_model
      description: Algorithm to be used to compute clear sky irradiance
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/ClearSkyModel"

    ExtremeSettingQueryParam:
      name: extreme_setting
      description: >
        Probability-of-exceedance (PoE) reference used to generate TMY GHI and temperature.<br/>
        <br/>
        • none: Uses median PoE50 values<br/>
        • (coming soon) poe_10_year: Uses annual PoE10 (90th percentile) values<br/>
        • (coming soon) poe_90_year: Uses annual PoE90 (10th percentile) values<br/>
        • (coming soon) poe_10_months: Uses monthly PoE10 values<br/>
        • (coming soon) poe_90_months: Uses monthly PoE90 values<br/>
        • (coming soon) worst_case_year: Uses a combination of PoE10 in summer and PoE90 in winter
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/ExtremeSetting"

    ResponseFormatQueryParam:
      name: response_format
      description: Response data format.
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/ResponseFormat"

    ObservationRealtimeStartTimeQueryParam:
      name: start
      description: >
        Start time (UTC) of observation/realtime time series.
        <br/><br/>
        Either an ISO 8601 date-time string in the format YYYY-mm-ddTHH:MMZ or
        YYYY-mm-ddTHH:MM:SSZ,
        or a relative date/time string (relative with respect to the current time).
        <br/>
        <br/>
        Examples:
        <br/>
        <br/>
        now<br/>
        -24hours<br/>
        -5days<br/>
        2025-05-15T12:00Z<br/>
        2025-05-15T12:00:00Z
      in: query
      required: false
      schema:
        type: string
        default: "-24hours"
        pattern: "^now|[-\\+]\\d+(hours|days)|[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2})?Z$"
        example: "2025-01-15T12:00Z"

    ObservationRealtimeEndTimeQueryParam:
      name: end
      description: >
        End time (UTC) of observation time series.
        <br/><br/>
        Either an ISO 8601 date-time string in the format YYYY-mm-ddTHH:MMZ or
        YYYY-mm-ddTHH:MM:SSZ,
        or a relative date/time string (relative with respect to the current time).
        <br/>
        <br/>
        Examples:
        <br/>
        <br/>
        now<br/>
        -3hours<br/>
        -1days<br/>
        2025-05-15T12:00Z<br/>
        2025-05-15T12:00:00Z
      in: query
      required: false
      schema:
        type: string
        default: "now"
        pattern: "^now|[-\\+]\\d+(hours|days)|[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2})?Z$"
        example: "2025-01-15T12:00Z"

    ObservationTrainingStartTimeQueryParam:
      name: start
      description: >
        Start time (UTC) of observation/training time series.
        <br/><br/>
        Either an ISO 8601 date-time string in the format YYYY-mm-ddTHH:MMZ or
        YYYY-mm-ddTHH:MM:SSZ,
        or a relative date/time string (relative with respect to the current time).
        <br/>
        <br/>
        Examples:
        <br/>
        <br/>
        2025-05-15T12:00Z<br/>
        2025-05-15T12:00:00Z
        -200days<br/>
      in: query
      required: false
      schema:
        type: string
        default: "-365days"
        pattern: "^now|[-\\+]\\d+(hours|days)|[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2})?Z$"
        example: "2025-01-15T12:00Z"

    ObservationTrainingEndTimeQueryParam:
      name: end
      description: >
        End time (UTC) of observation time series.
        <br/><br/>
        Either an ISO 8601 date-time string in the format YYYY-mm-ddTHH:MMZ or
        YYYY-mm-ddTHH:MM:SSZ,
        or a relative date/time string (relative with respect to the current time).
        <br/>
        <br/>
        Examples:
        <br/>
        <br/>
        2025-05-15T12:00Z<br/>
        2025-05-15T12:00:00Z
        -200days<br/>
      in: query
      required: false
      schema:
        type: string
        default: "-7days"
        pattern: "^now|[-\\+]\\d+(hours|days)|[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2})?Z$"
        example: "2025-01-15T12:00Z"

    ForecastStartTimeQueryParam:
      name: start
      description: >
        Start time (UTC) of the forecast time series.
        <br/><br/>
        Either an ISO 8601 date-time string in the format YYYY-mm-ddTHH:MMZ or
        YYYY-mm-ddTHH:MM:SSZ,
        or a relative date/time string (relative with respect to the current time).
        <br/><br/>
        Examples (note that the plus sign must be url-encoded):
        <br/><br/>
        now<br/>
        +12hours<br/>
        2025-05-15T12:00Z<br/>
        2025-05-15T12:00:00Z
      in: query
      required: false
      schema:
        type: string
        default: "now"
        pattern: "^now|[-\\+]\\d+(hours|days)|[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2})?Z$"
        example: "2025-01-15T12:00Z"

    ForecastEndTimeQueryParam:
      name: end
      description: >
        End time (UTC) of the forecast time series.
        <br/><br/>
        Either an ISO 8601 date-time string in the format YYYY-mm-ddTHH:MMZ or
        YYYY-mm-ddTHH:MM:SSZ,
        or a relative date/time string (relative with respect to the current time).
        <br/><br/>
        Examples (note that the plus sign must be url-encoded):
        <br/><br/>
        +3hours<br/>
        +72hours<br/>
        +7days<br/>
        2025-05-15T12:00Z<br/>
        2025-05-15T12:00:00Z
      in: query
      required: false
      schema:
        type: string
        default: "+3days"
        pattern: "^now|[-\\+]\\d+(hours|days)|[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2})?Z$"
        example: "2025-01-15T12:00Z"

    ClimateParametersQueryParam:
      name: parameters
      description: >
        Comma-separated list of parameter names, or the string "all".
        <br/><br/>
        Parameters:<br/>
        • global_horizontal_irradiance<br/>
        • global_horizontal_irradiance_with_shading<br/>
        • direct_horizontal_irradiance<br/>
        • direct_horizontal_irradiance_with_shading<br/>
        • diffuse_horizontal_irradiance<br/>
        • diffuse_horizontal_irradiance_with_shading<br/>
        • direct_normal_irradiance<br/>
        • direct_normal_irradiance_with_shading<br/>
        • global_tilted_irradiance<br/>
        • global_tilted_irradiance_with_shading<br/>
        • direct_tilted_irradiance<br/>
        • direct_tilted_irradiance_with_shading<br/>
        • diffuse_tilted_irradiance<br/>
        • diffuse_tilted_irradiance_with_shading<br/>
        • pv_production<br/>
        • pv_production_with_shading<br/>
        • global_clear_sky_irradiance<br/>
        • direct_horizontal_clear_sky_irradiance<br/>
        • diffuse_clear_sky_irradiance<br/>
        • direct_normal_clear_sky_irradiance<br/>
        • precipitation<br/>
        • temperature<br/>
        • dew_point_temperature<br/>
        • snow_depth<br/>
        • global_extraterrestrial_irradiance<br/>
        • global_extraterrestrial_normal_irradiance<br/>
        • downwelling_longwave_irradiance<br/>
        • upwelling_longwave_irradiance<br/>
        • vertical_longwave_irradiance<br/>
        • photo_active_irradiance<br/>
        • radiation_balance<br/>
        • global_illuminance<br/>
        • direct_illuminance<br/>
        • diffuse_illuminance<br/>
        • linke_turbidity_factor<br/>
        • aerosol_optical_depth<br/>
        • cloud_cover<br/>
        • albedo<br/>
        • surface_temperature<br/>
        • sky_temperature<br/>
        • wet_bulb_temperature<br/>
        • mixing_ratio<br/>
        • relative_humidity<br/>
        • precipitable_water<br/>
        • driving_rain<br/>
        • pressure<br/>
        • wind_speed<br/>
        • wind_direction<br/>
        • solar_elevation<br/>
        • solar_azimuth<br/>
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/ClimateParameters"

    ForecastParametersQueryParam:
      name: parameters
      description: >
        Comma-separated list of parameter names, or the string "all".
        <br/><br/>
        Parameters:<br/>
        • global_horizontal_irradiance<br/>
        • global_horizontal_irradiance_with_shading<br/>
        • direct_horizontal_irradiance<br/>
        • direct_horizontal_irradiance_with_shading<br/>
        • diffuse_horizontal_irradiance<br/>
        • diffuse_horizontal_irradiance_with_shading<br/>
        • direct_normal_irradiance<br/>
        • direct_normal_irradiance_with_shading<br/>
        • global_tilted_irradiance<br/>
        • global_tilted_irradiance_with_shading<br/>
        • direct_tilted_irradiance<br/>
        • direct_tilted_irradiance_with_shading<br/>
        • diffuse_tilted_irradiance<br/>
        • diffuse_tilted_irradiance_with_shading<br/>
        • pv_production<br/>
        • pv_production_with_shading<br/>
        • global_clear_sky_irradiance<br/>
        • precipitation<br/>
        • temperature<br/>
        • dew_point_temperature<br/>
        • snow_depth<br/>
        • cloud_cover<br/>
        • relative_humidity<br/>
        • pressure<br/>
        • wind_speed<br/>
        • wind_direction<br/>
        • wind_gusts<br/>
        • weather_symbol<br/>
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/ForecastParameters"

    ObservationParametersQueryParam:
      name: parameters
      description: >
        Comma-separated list of parameter names, or the string "all".
        <br/><br/>
        Parameters:<br/>
        • global_horizontal_irradiance<br/>
        • global_horizontal_irradiance_with_shading<br/>
        • direct_horizontal_irradiance<br/>
        • direct_horizontal_irradiance_with_shading<br/>
        • diffuse_horizontal_irradiance<br/>
        • diffuse_horizontal_irradiance_with_shading<br/>
        • direct_normal_irradiance<br/>
        • direct_normal_irradiance_with_shading<br/>
        • global_tilted_irradiance<br/>
        • global_tilted_irradiance_with_shading<br/>
        • direct_tilted_irradiance<br/>
        • direct_tilted_irradiance_with_shading<br/>
        • diffuse_tilted_irradiance<br/>
        • diffuse_tilted_irradiance_with_shading<br/>
        • pv_production<br/>
        • pv_production_with_shading<br/>
        • global_clear_sky_irradiance<br/>
        • temperature<br/>
        • snow_depth<br/>
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/ObservationParameters"

  schemas:
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: "#/components/schemas/Error"

    Error:
      type: object
      required:
        - message
      properties:
        message:
          type: string

    Latitude:
      type: number
      format: double
      minimum: -90
      maximum: 90
      example: 47.3768

    Longitude:
      type: number
      format: double
      minimum: -180
      maximum: 180
      example: 8.5417

    AltitudeOption:
      description: >
        Altitude in meters above sea level.

        • auto: Automatic
        • number: altitude in meters
      type: string
      pattern: '^(auto|-?[0-9]+(\.[0-9]+)?)$'
      default: "auto"
      example: 549

    Altitude:
      description: >
        Altitude in meters above sea level.
      type: number
      format: double
      minimum: -1000
      maximum: 10000

    SurfaceAzimuth:
      description: >
        Orientation of the solar panel. North Azimuth.
        <br/>
        Conventions:<br/>
        • 0° = oriented towards the north</br>
        • 90° = oriented towards the east</br>
        • 180° = oriented towards the south</br>
        • 270° = oriented towards the west
      type: number
      format: double
      minimum: 0
      maximum: 360
      default: 0
      example: 186

    SurfaceTilt:
      description: >
        Tilt angle of the solar panel.<br/>
        • 0° = horizontal<br/>
        • 90° = vertical
      type: number
      format: double
      minimum: 0
      maximum: 90
      default: 0

    TimeZone:
      description: >
        UTC offset in hours.
      type: number
      format: double
      enum:
        [
          -12.0,
          -11.0,
          -10.0,
          -9.5,
          -9.0,
          -8.0,
          -7.0,
          -6.0,
          -5.0,
          -4.5,
          -4.0,
          -3.5,
          -3.0,
          -2.0,
          -1.0,
          0.0,
          1.0,
          2.0,
          3.0,
          3.5,
          4.0,
          4.5,
          5.0,
          5.5,
          5.75,
          6.0,
          6.5,
          7.0,
          8.0,
          8.75,
          9.0,
          9.5,
          10.0,
          10.5,
          11.0,
          11.5,
          12.0,
          12.75,
          13.0,
          14.0,
        ]

    Horizon:
      description: >
        Horizon of the requested location.
        <br/>

        • flat: Flat horizon (all values are 0°).<br/>
        • auto: Horizon is determined automatically using a global 30m digital elevation model.<br/>
        • [comma-separated values]<br/>

        [comma-separated values]: provide 360 integer values representing elevation angles
        (in degrees) of the horizon in 360 directions.
        Elevation angles must be ≥0° and <90°.
        Index corresponds to azimuth:<br/>
          Index 0 = 0° (North)<br/>
          Index 90 = 90° (East)<br/>
          Index 180 = 180° (South)<br/>
          Index 270 = 270° (West)<br/>
        Each value indicates the elevation angle at the corresponding azimuth.
      type: string
      pattern: "^(auto|flat|[0-9]+(,[0-9]+){359})$"
      default: "flat"
      example: "0,0,0,2,4,4,6,10,...,9,7,8,6,5,3,0"

    HorizonAzimuth:
      description: >
        Azimuth angles (in degrees) corresponding to horizon elevation angles in "HorizonElevation".
        <br/><br/>
        0° = north, 90° = east, 180° = south, 270° = west.
      type: array
      items:
        type: integer
      minItems: 360
      maxItems: 360

    HorizonElevation:
      description: >
        360 integer values representing elevation angles (0° to 90°) of the horizon.
        Array indices correspond to azimuths, e.g., Index 0 corresponds to azimuth 0°.
        Each value indicates the elevation angle at the corresponding azimuth.

        The given example corresponds to a "20° mountain" in the north and a flat horizon
        in all other directions.
      type: array
      items:
        type: integer
      minItems: 360
      maxItems: 360
      example: "[20,20,20,19,18,17,...,0,0,0,0,0,0,...,18,19,20,20,20,20]"

    Situation:
      description: >
        Local terrain situation.
      type: string
      enum:
        - open
        - depression
        - cold_air_lake
        - sea_lake
        - city
        - slope_south
        - slope_west_east
        - valley
        - valley_foehn
        - valley_central_alps
        - valley_alpine_foothills
        - valley_slope_south
        - valley_slope_west_east
        - summit
      default: open

    Albedo:
      description: Local albedo
      type: number
      format: double
      minimum: 0.05
      maximum: 0.9
      default: 0.2

    Turbidity:
      description: >
        Monthly atmospheric turbidity.<br/>
        <br/>
        • auto: turbidity is taken from the Meteonorm database.<br/>
        • [comma-separated values]: 12 floating point values representing monthly atmospheric turbidity.
      type: string
      pattern: "^(auto|[0-9]*\\.?[0-9]+(,[0-9]*\\.?[0-9]+){11})$"
      default: "auto"
      example: "5.2,4,3,3.1,3.0,2.8,3.14,3.0,3,3,4,5"

    DataVersion:
      type: string
      enum:
        - latest
        - v9.0
        # - v8.2
      default: latest

    FutureScenario:
      type: string
      enum:
        - none
        - ssp1_26
        - ssp2_45
        - ssp3_70
      default: none

    FutureYear:
      type: integer
      minimum: 2030
      maximum: 2090
      default: 2050

    ClimateFrequency:
      type: string
      enum:
        - 1_hour
        - 1_minute
      default: 1_hour

    Frequency:
      type: string
      enum:
        - 1_hour
        - 15_minutes
        - 1_minute

    RadiationMinuteModel:
      type: string
      enum:
        - remund
      default: remund

    DiffuseRadiationModel:
      type: string
      enum:
        - perez
      default: perez

    TiltRadiationModel:
      type: string
      enum:
        - perez
      default: perez

    ClearSkyModel:
      type: string
      enum:
        - esra
        - solis
      default: esra

    RandomSeed:
      type: integer
      minimum: 0
      maximum: 1000
      default: 0

    ExtremeSetting:
      type: string
      enum:
        - none
        # - poe_10_year
        # - poe_90_year
        # - poe_10_months
        # - poe_90_months
        # - worst_case_year
      default: none

    ResponseFormat:
      type: string
      enum:
        - json
        # - csv
        # - energy_plus
        # - full
        # - meteonorm
        # - pleiades
        # - polysun
        # - pvsol
        # - pvsyst
        # - sam
        # - tmy3
        # - try
        # - wufi
      default: json

    ClimateParameters:
      type: string
      example: "global_horizontal_irradiance,global_tilted_irradiance,temperature"
      default: "global_horizontal_irradiance,diffuse_horizontal_irradiance,direct_normal_irradiance,temperature"

    ForecastParameters:
      type: string
      example: "global_horizontal_irradiance,global_tilted_irradiance,temperature"
      default: "global_horizontal_irradiance,temperature"

    ObservationParameters:
      type: string
      example: "global_horizontal_irradiance,global_tilted_irradiance,temperature"
      default: "global_horizontal_irradiance,temperature"

    ClimateResponse:
      description: >
        API response containing a time series.
      type: object
      required:
        - start_times
        - end_times
        - values
        - quality_parameters
        - meta
      properties:
        start_times:
          $ref: "#/components/schemas/TimePoints"
        end_times:
          $ref: "#/components/schemas/TimePoints"
        values:
          type: object
          required:
            - global_horizontal_irradiance
            - global_horizontal_irradiance_with_shading
            - direct_horizontal_irradiance
            - direct_horizontal_irradiance_with_shading
            - diffuse_horizontal_irradiance
            - diffuse_horizontal_irradiance_with_shading
            - direct_normal_irradiance
            - direct_normal_irradiance_with_shading
            - global_tilted_irradiance
            - global_tilted_irradiance_with_shading
            - direct_tilted_irradiance
            - direct_tilted_irradiance_with_shading
            - diffuse_tilted_irradiance
            - diffuse_tilted_irradiance_with_shading
            - pv_production
            - pv_production_with_shading
            - global_clear_sky_irradiance
            - direct_horizontal_clear_sky_irradiance
            - diffuse_clear_sky_irradiance
            - direct_normal_clear_sky_irradiance
            - precipitation
            - temperature
            - dew_point_temperature
            - snow_depth
            - global_extraterrestrial_irradiance
            - global_extraterrestrial_normal_irradiance
            - downwelling_longwave_irradiance
            - upwelling_longwave_irradiance
            - vertical_longwave_irradiance
            - photo_active_irradiance
            - radiation_balance
            - global_illuminance
            - direct_illuminance
            - diffuse_illuminance
            - linke_turbidity_factor
            - aerosol_optical_depth
            - cloud_cover
            - albedo
            - surface_temperature
            - sky_temperature
            - wet_bulb_temperature
            - mixing_ratio
            - relative_humidity
            - precipitable_water
            - driving_rain
            - pressure
            - wind_speed
            - wind_direction
            - solar_elevation
            - solar_azimuth
          properties:
            global_horizontal_irradiance:
              $ref: "#/components/schemas/Values"
            global_horizontal_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            direct_horizontal_irradiance:
              $ref: "#/components/schemas/Values"
            direct_horizontal_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            diffuse_horizontal_irradiance:
              $ref: "#/components/schemas/Values"
            diffuse_horizontal_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            direct_normal_irradiance:
              $ref: "#/components/schemas/Values"
            direct_normal_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            global_tilted_irradiance:
              $ref: "#/components/schemas/Values"
            global_tilted_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            direct_tilted_irradiance:
              $ref: "#/components/schemas/Values"
            direct_tilted_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            diffuse_tilted_irradiance:
              $ref: "#/components/schemas/Values"
            diffuse_tilted_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            pv_production:
              $ref: "#/components/schemas/Values"
            pv_production_with_shading:
              $ref: "#/components/schemas/Values"
            global_clear_sky_irradiance:
              $ref: "#/components/schemas/Values"
            direct_horizontal_clear_sky_irradiance:
              $ref: "#/components/schemas/Values"
            diffuse_clear_sky_irradiance:
              $ref: "#/components/schemas/Values"
            direct_normal_clear_sky_irradiance:
              $ref: "#/components/schemas/Values"
            precipitation:
              $ref: "#/components/schemas/Values"
            temperature:
              $ref: "#/components/schemas/Values"
            dew_point_temperature:
              $ref: "#/components/schemas/Values"
            snow_depth:
              $ref: "#/components/schemas/Values"
            global_extraterrestrial_irradiance:
              $ref: "#/components/schemas/Values"
            global_extraterrestrial_normal_irradiance:
              $ref: "#/components/schemas/Values"
            downwelling_longwave_irradiance:
              $ref: "#/components/schemas/Values"
            upwelling_longwave_irradiance:
              $ref: "#/components/schemas/Values"
            vertical_longwave_irradiance:
              $ref: "#/components/schemas/Values"
            photo_active_irradiance:
              $ref: "#/components/schemas/Values"
            radiation_balance:
              $ref: "#/components/schemas/Values"
            global_illuminance:
              $ref: "#/components/schemas/Values"
            direct_illuminance:
              $ref: "#/components/schemas/Values"
            diffuse_illuminance:
              $ref: "#/components/schemas/Values"
            linke_turbidity_factor:
              $ref: "#/components/schemas/Values"
            aerosol_optical_depth:
              $ref: "#/components/schemas/Values"
            cloud_cover:
              $ref: "#/components/schemas/Values"
            albedo:
              $ref: "#/components/schemas/Values"
            surface_temperature:
              $ref: "#/components/schemas/Values"
            sky_temperature:
              $ref: "#/components/schemas/Values"
            wet_bulb_temperature:
              $ref: "#/components/schemas/Values"
            mixing_ratio:
              $ref: "#/components/schemas/Values"
            relative_humidity:
              $ref: "#/components/schemas/Values"
            precipitable_water:
              $ref: "#/components/schemas/Values"
            driving_rain:
              $ref: "#/components/schemas/Values"
            pressure:
              $ref: "#/components/schemas/Values"
            wind_speed:
              $ref: "#/components/schemas/Values"
            wind_direction:
              $ref: "#/components/schemas/Values"
            solar_elevation:
              $ref: "#/components/schemas/Values"
            solar_azimuth:
              $ref: "#/components/schemas/Values"
          description: "Time series values."
        quality_parameters:
          type: object
          required:
            - start_year_of_irradiance_period_of_nearest_station
            - end_year_of_irradiance_period_of_nearest_station
            - irradiance_station_data_weight
            - uncertainty_of_irradiance_estimation
            - uncertainty_of_temperature_estimation
            - irradiance_year_to_year_variability
            - irradiance_yearly_poe10
            - irradiance_yearly_poe90
          properties:
            start_year_of_irradiance_period_of_nearest_station:
              type: integer
              description: "Start year of the irradiance data period at the nearest station."
            end_year_of_irradiance_period_of_nearest_station:
              type: integer
              description: "End year of the irradiance data period at the nearest station."
            irradiance_station_data_weight:
              type: number
              format: double
              description: "Weight of the station data in the global irradiance estimation."
            uncertainty_of_irradiance_estimation:
              type: number
              format: double
              description: "Uncertainty of the global irradiance estimation."
            uncertainty_of_temperature_estimation:
              type: number
              format: double
              description: "Uncertainty of the temperature estimation."
            irradiance_year_to_year_variability:
              type: number
              format: double
              description: "Year-to-year variability of the global irradiance."
            irradiance_yearly_poe10:
              type: number
              format: double
              description: >
                The yearly irradiance level associated with a 10% probability of exceedance (PoE10).

                This value corresponds to the 90th percentile of the irradiance distribution.
            irradiance_yearly_poe90:
              type: number
              format: double
              description: >
                The yearly irradiance level associated with a 90% probability of exceedance (PoE90).

                This value corresponds to the 90th percentile of the irradiance distribution.
        meta:
          $ref: "#/components/schemas/Metadata"

    ForecastResponse:
      description: >
        API response containing a time series.
      type: object
      required:
        - start_times
        - end_times
        - values
        - meta
      properties:
        start_times:
          $ref: "#/components/schemas/TimePoints"
        end_times:
          $ref: "#/components/schemas/TimePoints"
        values:
          type: object
          required:
            - global_horizontal_irradiance
            - global_horizontal_irradiance_with_shading
            - direct_horizontal_irradiance
            - direct_horizontal_irradiance_with_shading
            - diffuse_horizontal_irradiance
            - diffuse_horizontal_irradiance_with_shading
            - direct_normal_irradiance
            - direct_normal_irradiance_with_shading
            - global_tilted_irradiance
            - global_tilted_irradiance_with_shading
            - direct_tilted_irradiance
            - direct_tilted_irradiance_with_shading
            - diffuse_tilted_irradiance
            - diffuse_tilted_irradiance_with_shading
            - pv_production
            - pv_production_with_shading
            - global_clear_sky_irradiance
            - precipitation
            - temperature
            - dew_point_temperature
            - snow_depth
            - cloud_cover
            - relative_humidity
            - pressure
            - wind_speed
            - wind_direction
            - wind_gusts
            - weather_symbol
          properties:
            global_horizontal_irradiance:
              $ref: "#/components/schemas/Values"
            global_horizontal_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            direct_horizontal_irradiance:
              $ref: "#/components/schemas/Values"
            direct_horizontal_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            diffuse_horizontal_irradiance:
              $ref: "#/components/schemas/Values"
            diffuse_horizontal_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            direct_normal_irradiance:
              $ref: "#/components/schemas/Values"
            direct_normal_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            global_tilted_irradiance:
              $ref: "#/components/schemas/Values"
            global_tilted_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            direct_tilted_irradiance:
              $ref: "#/components/schemas/Values"
            direct_tilted_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            diffuse_tilted_irradiance:
              $ref: "#/components/schemas/Values"
            diffuse_tilted_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            pv_production:
              $ref: "#/components/schemas/Values"
            pv_production_with_shading:
              $ref: "#/components/schemas/Values"
            global_clear_sky_irradiance:
              $ref: "#/components/schemas/Values"
            precipitation:
              $ref: "#/components/schemas/Values"
            temperature:
              $ref: "#/components/schemas/Values"
            dew_point_temperature:
              $ref: "#/components/schemas/Values"
            snow_depth:
              $ref: "#/components/schemas/Values"
            cloud_cover:
              $ref: "#/components/schemas/Values"
            relative_humidity:
              $ref: "#/components/schemas/Values"
            pressure:
              $ref: "#/components/schemas/Values"
            wind_speed:
              $ref: "#/components/schemas/Values"
            wind_direction:
              $ref: "#/components/schemas/Values"
            wind_gusts:
              $ref: "#/components/schemas/Values"
            weather_symbol:
              type: array
              items:
                type: integer
          description: "Time series values."
        meta:
          $ref: "#/components/schemas/Metadata"

    ObservationResponse:
      description: >
        API response containing a time series.
      type: object
      required:
        - start_times
        - end_times
        - values
        - meta
      properties:
        start_times:
          $ref: "#/components/schemas/TimePoints"
        end_times:
          $ref: "#/components/schemas/TimePoints"
        values:
          type: object
          required:
            - global_horizontal_irradiance
            - global_horizontal_irradiance_with_shading
            - direct_horizontal_irradiance
            - direct_horizontal_irradiance_with_shading
            - diffuse_horizontal_irradiance
            - diffuse_horizontal_irradiance_with_shading
            - direct_normal_irradiance
            - direct_normal_irradiance_with_shading
            - global_tilted_irradiance
            - global_tilted_irradiance_with_shading
            - direct_tilted_irradiance
            - direct_tilted_irradiance_with_shading
            - diffuse_tilted_irradiance
            - diffuse_tilted_irradiance_with_shading
            - pv_production
            - pv_production_with_shading
            - global_clear_sky_irradiance
            - temperature
            - snow_depth
          properties:
            global_horizontal_irradiance:
              $ref: "#/components/schemas/Values"
            global_horizontal_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            direct_horizontal_irradiance:
              $ref: "#/components/schemas/Values"
            direct_horizontal_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            diffuse_horizontal_irradiance:
              $ref: "#/components/schemas/Values"
            diffuse_horizontal_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            direct_normal_irradiance:
              $ref: "#/components/schemas/Values"
            direct_normal_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            global_tilted_irradiance:
              $ref: "#/components/schemas/Values"
            global_tilted_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            direct_tilted_irradiance:
              $ref: "#/components/schemas/Values"
            direct_tilted_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            diffuse_tilted_irradiance:
              $ref: "#/components/schemas/Values"
            diffuse_tilted_irradiance_with_shading:
              $ref: "#/components/schemas/Values"
            pv_production:
              $ref: "#/components/schemas/Values"
            pv_production_with_shading:
              $ref: "#/components/schemas/Values"
            global_clear_sky_irradiance:
              $ref: "#/components/schemas/Values"
            temperature:
              $ref: "#/components/schemas/Values"
            snow_depth:
              $ref: "#/components/schemas/Values"
          description: "Time series values."
        meta:
          $ref: "#/components/schemas/Metadata"

    TimePoints:
      type: array
      description: >
        Start or end date/time of each time series interval.
      items:
        type: string
        format: date-time

    TimePoint:
      type: string
      format: date-time
      example: "2025-01-01T00:00:00Z"

    Metadata:
      type: object
      required:
        - frequency
        - parameters
        - lat
        - lon
        - altitude
        - surface_tilt
        - surface_azimuth
      properties:
        frequency:
          $ref: "#/components/schemas/Frequency"
        parameters:
          type: array
          items:
            $ref: "#/components/schemas/Parameter"
        lat:
          $ref: "#/components/schemas/Latitude"
        lon:
          $ref: "#/components/schemas/Longitude"
        altitude:
          $ref: "#/components/schemas/Altitude"
        surface_azimuth:
          $ref: "#/components/schemas/SurfaceAzimuth"
        surface_tilt:
          $ref: "#/components/schemas/SurfaceTilt"
        time_zone:
          $ref: "#/components/schemas/TimeZone"

    Parameter:
      type: object
      required:
        - description
        - name
        - unit
        - aggregation_method
      properties:
        description:
          type: string
          description: "Description of parameter"
          example: "Global horizontal irradiance"
        name:
          type: string
          description: "unique name of parameter"
          example: "global_horizontal_irradiance"
        unit:
          $ref: "#/components/schemas/Unit"
        aggregation_method:
          type: string
          enum:
            - average
            - instant
            - min
            - max
            - sum
          example: average

    Values:
      type: array
      items:
        type: number
        format: double
        nullable: true

    Unit:
      type: object
      required:
        - name
        - description
      properties:
        name:
          type: string
          description: "string representation of unit"
          example: "W/m**2"
        description:
          type: string
          description: "description of unit"
          example: "Watt per square meter"

    AltitudeResponse:
      description: >
        Altitude response
      type: object
      required:
        - altitude
      properties:
        altitude:
          $ref: "#/components/schemas/Altitude"

    HorizonResponse:
      type: object
      required:
        - azimuth
        - elevation
      properties:
        azimuth:
          $ref: "#/components/schemas/HorizonAzimuth"
        elevation:
          $ref: "#/components/schemas/HorizonElevation"

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Unauthorized:
      description: Missing or failed authentication
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    PaymentRequired:
      description: >
        Your token balance has been used up or is insufficient to perform this
        request. Buy additional tokens or switch to the next higher subscription
        model.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    TooManyRequests:
      description: >
        Too many requests.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
