openapi: 3.1.0
info:
  title: Solcast Aggregations Live 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: Live Data
  description: Real-time solar irradiance, PV power, and weather estimated actuals (last 7 days, updated every 5 minutes).
paths:
  /data/live/radiation_and_weather:
    get:
      operationId: getLiveRadiationAndWeather
      summary: Get Live Radiation and Weather
      description: Get irradiance and weather estimated actuals for near real-time and the past 7 days for the requested location, derived from satellite (clouds and irradiance over non-polar continental areas) and numerical weather models (other data). Data is updated every 5 minutes.
      tags:
      - Live 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: true
        description: Comma-separated list of output parameters to return (e.g., ghi,dni,dhi,air_temp, wind_speed_10m,cloud_opacity,clearsky_ghi).
        schema:
          type: string
        example: ghi,dni,dhi,air_temp,wind_speed_10m
      - name: period
        in: query
        required: false
        description: Time period between data points in ISO 8601 duration format (e.g., PT5M for 5 minutes, PT30M for 30 minutes, PT60M for 60 minutes).
        schema:
          type: string
        example: PT30M
      - name: format
        in: query
        required: false
        description: Response format. Defaults to json.
        schema:
          type: string
          enum:
          - json
          - csv
        example: json
      responses:
        '200':
          description: Successful response with irradiance and weather time series.
          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/live/rooftop_pv_power:
    get:
      operationId: getLiveRooftopPvPower
      summary: Get Live Rooftop PV Power
      description: Get basic rooftop PV power estimated actuals for the present time up to 7 days of past data for the requested location. Data is derived from satellite observations and numerical weather models. No site registration required.
      tags:
      - Live 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: 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 (0 = flat, 90 = vertical).
        schema:
          type: number
          format: float
          minimum: 0
          maximum: 90
        example: 25
      - name: azimuth
        in: query
        required: false
        description: Panel azimuth in degrees (0/360 = north, 90 = east, 180 = south, 270 = west).
        schema:
          type: number
          format: float
          minimum: 0
          maximum: 360
        example: 180
      - name: output_parameters
        in: query
        required: false
        description: Comma-separated list of output parameters (e.g., pv_power_rooftop,pv_estimate).
        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: PT30M
      - name: format
        in: query
        required: false
        description: Response format.
        schema:
          type: string
          enum:
          - json
          - csv
        example: json
      responses:
        '200':
          description: Successful response with rooftop PV power time series.
          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'
  /data/live/advanced_pv_power:
    get:
      operationId: getLiveAdvancedPvPower
      summary: Get Live Advanced PV Power
      description: Get high-specification PV power estimated actuals for the present time up to 7 days of past data for a registered PV power site. Uses Solcast's advanced PV model. Requires a resource_id from a registered site.
      tags:
      - Live Data
      parameters:
      - name: resource_id
        in: query
        required: true
        description: Unique resource identifier for a registered Solcast PV power site.
        schema:
          type: string
        example: ba75-e17a-7374-95ed
      - name: output_parameters
        in: query
        required: false
        description: Comma-separated list of output parameters.
        schema:
          type: string
        example: pv_power_advanced
      - name: period
        in: query
        required: false
        description: Time period between data points in ISO 8601 duration format.
        schema:
          type: string
        example: PT30M
      - name: format
        in: query
        required: false
        description: Response format.
        schema:
          type: string
          enum:
          - json
          - csv
        example: json
      responses:
        '200':
          description: Successful response with advanced PV power time series.
          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'
  /data/live/soiling/kimber:
    get:
      operationId: getLiveSoilingKimber
      summary: Get Live Soiling (Kimber Model)
      description: Get hourly live soiling loss estimates using the Kimber model. Returns a time series of estimated cumulative soiling or cleanliness state for the requested location based on pvlib's Kimber soiling model.
      tags:
      - Live 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: depo_veloc_pm10
        in: query
        required: false
        description: Deposition velocity for PM10 particles (m/s).
        schema:
          type: number
          format: float
      - name: initial_soiling
        in: query
        required: false
        description: Initial soiling fraction (0.0 = clean, 1.0 = fully soiled).
        schema:
          type: number
          format: float
        example: 0.0
      - name: format
        in: query
        required: false
        description: Response format.
        schema:
          type: string
          enum:
          - json
          - csv
        example: json
      responses:
        '200':
          description: Successful response with soiling time series.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SoilingResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /data/live/soiling/hsu:
    get:
      operationId: getLiveSoilingHsu
      summary: Get Live Soiling (HSU Model)
      description: Get hourly live soiling loss estimates using Solcast's HSU model. Returns a time series of estimated cumulative soiling or cleanliness state for the requested location.
      tags:
      - Live 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: depo_veloc_pm10
        in: query
        required: false
        description: Deposition velocity for PM10 particles (m/s).
        schema:
          type: number
          format: float
      - name: initial_soiling
        in: query
        required: false
        description: Initial soiling fraction (0.0 = clean, 1.0 = fully soiled).
        schema:
          type: number
          format: float
        example: 0.0
      - name: format
        in: query
        required: false
        description: Response format.
        schema:
          type: string
          enum:
          - json
          - csv
        example: json
      responses:
        '200':
          description: Successful response with soiling time series.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SoilingResponse'
        '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.
    SoilingEstimated:
      type: object
      description: A single time period of soiling loss 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: PT60M
        soiling_loss:
          type: number
          format: float
          description: Cumulative soiling loss as a fraction (0 = clean, 1 = fully soiled).
          example: 0.032
        cleanliness:
          type: number
          format: float
          description: Panel cleanliness as a fraction (1 = clean, 0 = fully soiled).
          example: 0.968
    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.
    SoilingResponse:
      type: object
      description: Response wrapper for soiling loss time series data.
      properties:
        estimated_actuals:
          type: array
          items:
            $ref: '#/components/schemas/SoilingEstimated'
          description: Array of soiling estimated actuals ordered by period_end ascending.
        forecasts:
          type: array
          items:
            $ref: '#/components/schemas/SoilingEstimated'
          description: Array of soiling 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'
    TooManyRequests:
      description: Too many requests — API rate limit or quota exceeded.
      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'
    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.'