openapi: 3.1.0
info:
  title: Solcast Aggregations TMY Data API
  description: The Solcast API provides live, forecast, historical, and typical meteorological year (TMY) solar irradiance, PV power, and weather data derived from a global fleet of weather satellites. Data covers rooftop PV, advanced PV, grid aggregations, and soiling loss models (Kimber and HSU) globally. Solcast is part of DNV's Green Data Products suite. Authentication uses an API key passed via the Authorization header.
  version: 1.0.0
  contact:
    name: Solcast Support
    url: https://solcast.com/contact
  license:
    name: Commercial
    url: https://solcast.com/terms-of-service
  x-logo:
    url: https://solcast.com/wp-content/uploads/2021/01/Solcast-Logo.svg
servers:
- url: https://api.solcast.com.au
  description: Solcast Production API
security:
- apiKeyAuth: []
tags:
- name: TMY Data
  description: Typical Meteorological Year data computed from 2007 to 2023 satellite observations.
paths:
  /data/tmy/radiation_and_weather:
    get:
      operationId: getTmyRadiationAndWeather
      summary: Get TMY Radiation and Weather
      description: Get the irradiance and weather for a Typical Meteorological Year (TMY) at the requested location, derived from satellite data and numerical weather models. The TMY is calculated with data from 2007 to 2023.
      tags:
      - TMY Data
      parameters:
      - name: latitude
        in: query
        required: true
        description: Latitude in decimal degrees, between -90 and 90 (north positive).
        schema:
          type: number
          format: float
          minimum: -90
          maximum: 90
        example: -33.856784
      - name: longitude
        in: query
        required: true
        description: Longitude in decimal degrees, between -180 and 180 (east positive).
        schema:
          type: number
          format: float
          minimum: -180
          maximum: 180
        example: 151.215297
      - name: output_parameters
        in: query
        required: false
        description: Comma-separated list of output parameters.
        schema:
          type: string
        example: ghi,dni,dhi,air_temp
      - name: period
        in: query
        required: false
        description: Time period between data points in ISO 8601 duration format.
        schema:
          type: string
        example: PT60M
      - name: format
        in: query
        required: false
        description: Response format.
        schema:
          type: string
          enum:
          - json
          - csv
        example: json
      responses:
        '200':
          description: Successful response with TMY irradiance and weather data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RadiationAndWeatherResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /data/tmy/rooftop_pv_power:
    get:
      operationId: getTmyRooftopPvPower
      summary: Get TMY Rooftop PV Power
      description: Get the basic rooftop PV power for a Typical Meteorological Year (TMY) at the requested location. The TMY is calculated with data from 2007 to 2023.
      tags:
      - TMY Data
      parameters:
      - name: latitude
        in: query
        required: true
        description: Latitude in decimal degrees, between -90 and 90 (north positive).
        schema:
          type: number
          format: float
        example: -33.856784
      - name: longitude
        in: query
        required: true
        description: Longitude in decimal degrees, between -180 and 180 (east positive).
        schema:
          type: number
          format: float
        example: 151.215297
      - name: capacity
        in: query
        required: false
        description: System capacity in kilowatts.
        schema:
          type: number
          format: float
        example: 5.0
      - name: tilt
        in: query
        required: false
        description: Panel tilt angle in degrees from horizontal.
        schema:
          type: number
          format: float
        example: 25
      - name: azimuth
        in: query
        required: false
        description: Panel azimuth in degrees.
        schema:
          type: number
          format: float
        example: 180
      - name: output_parameters
        in: query
        required: false
        description: Comma-separated list of output parameters.
        schema:
          type: string
        example: pv_power_rooftop
      - name: period
        in: query
        required: false
        description: Time period between data points in ISO 8601 duration format.
        schema:
          type: string
        example: PT60M
      - name: format
        in: query
        required: false
        description: Response format.
        schema:
          type: string
          enum:
          - json
          - csv
        example: json
      responses:
        '200':
          description: Successful response with TMY rooftop PV power data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PvPowerResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    PvPowerEstimated:
      type: object
      description: A single time period of PV power data.
      properties:
        period_end:
          type: string
          format: date-time
          description: The end time of the data period (UTC).
          example: '2023-01-01T01:00:00.0000000Z'
        period:
          type: string
          description: Duration of the time period in ISO 8601 format.
          example: PT30M
        pv_estimate:
          type: number
          format: float
          description: Estimated PV power output as a fraction of system capacity (0–1).
          example: 0.742
        pv_estimate10:
          type: number
          format: float
          description: PV estimate at 10th percentile (pessimistic scenario).
        pv_estimate90:
          type: number
          format: float
          description: PV estimate at 90th percentile (optimistic scenario).
        pv_power_rooftop:
          type: number
          format: float
          description: Estimated rooftop PV power output in kilowatts.
          example: 3.71
        pv_power_advanced:
          type: number
          format: float
          description: Advanced model PV power output in kilowatts.
    RadiationAndWeatherResponse:
      type: object
      description: Response wrapper for irradiance and weather time series data.
      properties:
        estimated_actuals:
          type: array
          items:
            $ref: '#/components/schemas/RadiationAndWeatherEstimated'
          description: Array of irradiance and weather data points ordered by period_end ascending.
        forecasts:
          type: array
          items:
            $ref: '#/components/schemas/RadiationAndWeatherEstimated'
          description: Array of forecast irradiance and weather data points ordered by period_end ascending.
    PvPowerResponse:
      type: object
      description: Response wrapper for PV power time series data.
      properties:
        estimated_actuals:
          type: array
          items:
            $ref: '#/components/schemas/PvPowerEstimated'
          description: Array of PV power estimated actuals ordered by period_end ascending.
        forecasts:
          type: array
          items:
            $ref: '#/components/schemas/PvPowerEstimated'
          description: Array of PV power forecast data points ordered by period_end ascending.
    ErrorResponse:
      type: object
      description: Standard error response body.
      properties:
        message:
          type: string
          description: Human-readable description of the error.
          example: Invalid latitude value provided.
        errors:
          type: object
          description: Field-level validation errors.
          additionalProperties:
            type: array
            items:
              type: string
    RadiationAndWeatherEstimated:
      type: object
      description: A single time period of irradiance and weather data.
      properties:
        period_end:
          type: string
          format: date-time
          description: The end time of the data period (UTC).
          example: '2023-01-01T01:00:00.0000000Z'
        period:
          type: string
          description: Duration of the time period in ISO 8601 format.
          example: PT30M
        ghi:
          type: number
          format: float
          description: Global Horizontal Irradiance in W/m².
          example: 850.2
        ghi90:
          type: number
          format: float
          description: GHI at 90th percentile (optimistic scenario) in W/m².
        ghi10:
          type: number
          format: float
          description: GHI at 10th percentile (pessimistic scenario) in W/m².
        ebh:
          type: number
          format: float
          description: Beam Horizontal Irradiance in W/m².
        dni:
          type: number
          format: float
          description: Direct Normal Irradiance in W/m².
          example: 750.5
        dhi:
          type: number
          format: float
          description: Diffuse Horizontal Irradiance in W/m².
          example: 99.7
        air_temp:
          type: number
          format: float
          description: Air temperature at 2m height in degrees Celsius.
          example: 28.3
        cloud_opacity:
          type: number
          format: float
          description: Cloud opacity as a fraction (0 = clear, 100 = fully overcast).
          example: 5.2
        wind_speed_10m:
          type: number
          format: float
          description: Wind speed at 10m height in m/s.
          example: 3.7
        wind_direction_10m:
          type: number
          format: float
          description: Wind direction at 10m height in degrees from north.
          example: 215.0
        clearsky_ghi:
          type: number
          format: float
          description: Clear-sky Global Horizontal Irradiance in W/m².
          example: 880.0
        clearsky_ebh:
          type: number
          format: float
          description: Clear-sky Beam Horizontal Irradiance in W/m².
        clearsky_dni:
          type: number
          format: float
          description: Clear-sky Direct Normal Irradiance in W/m².
        clearsky_dhi:
          type: number
          format: float
          description: Clear-sky Diffuse Horizontal Irradiance in W/m².
        precipitable_water:
          type: number
          format: float
          description: Total column precipitable water in kg/m².
        azimuth:
          type: number
          format: float
          description: Solar azimuth angle in degrees.
        zenith:
          type: number
          format: float
          description: Solar zenith angle in degrees.
        elevation:
          type: number
          format: float
          description: Solar elevation angle in degrees above the horizon.
        relative_humidity:
          type: number
          format: float
          description: Relative humidity at 2m height as a percentage.
        surface_pressure:
          type: number
          format: float
          description: Surface atmospheric pressure in hPa.
        snow_depth:
          type: number
          format: float
          description: Snow depth in metres.
        snow_water_equivalent:
          type: number
          format: float
          description: Snow water equivalent in kg/m².
        snow_soiling_rooftop:
          type: number
          format: float
          description: Estimated snow soiling loss factor for rooftop panels (0–1).
  responses:
    Unauthorized:
      description: Unauthorized — API key is missing, invalid, or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request — invalid parameters or missing required fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: Too many requests — API rate limit or quota exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnprocessableEntity:
      description: Unprocessable entity — request parameters are syntactically valid but semantically incorrect.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      description: 'Authenticate using your Solcast API key as a Bearer token in the Authorization header: `Authorization: Bearer {api_key}`. Obtain an API key at https://toolkit.solcast.com.au/register.'