openapi: 3.1.0
info:
  title: Solcast 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).
  - name: Forecast Data
    description: Solar irradiance, PV power, and weather forecasts up to 14 days ahead.
  - name: Historic Data
    description: Historical solar radiation and weather data from 2007-01-01 up to 7 days before present.
  - name: TMY Data
    description: Typical Meteorological Year data computed from 2007 to 2023 satellite observations.
  - name: Aggregations
    description: Live and forecast aggregated generation data for grid collections and sub-aggregations.
  - name: PV Power Sites
    description: CRUD management of registered PV power sites for use with the advanced PV power model.
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'
  /data/forecast/radiation_and_weather:
    get:
      operationId: getForecastRadiationAndWeather
      summary: Get Forecast Radiation and Weather
      description: >-
        Get irradiance and weather forecasts from the present time up to 14 days
        ahead for the requested location, derived from satellite observations
        (nowcasted for approx. 4 hours ahead) and numerical weather models.
        Data is available at 5- to 60-minute granularity.
      tags:
        - Forecast 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
        - name: hours
          in: query
          required: false
          description: Number of forecast hours to retrieve (up to 336 for 14 days).
          schema:
            type: integer
            minimum: 1
            maximum: 336
          example: 48
        - 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 forecast 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/forecast/rooftop_pv_power:
    get:
      operationId: getForecastRooftopPvPower
      summary: Get Forecast Rooftop PV Power
      description: >-
        Get basic rooftop PV power forecasts from the present time up to 14 days
        ahead for the requested location. No site registration required.
      tags:
        - Forecast 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.
          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: true
          description: Comma-separated list of output parameters.
          schema:
            type: string
          example: pv_power_rooftop
        - name: hours
          in: query
          required: false
          description: Number of forecast hours to retrieve (up to 336).
          schema:
            type: integer
          example: 48
        - 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 forecast 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/forecast/advanced_pv_power:
    get:
      operationId: getForecastAdvancedPvPower
      summary: Get Forecast Advanced PV Power
      description: >-
        Get high-specification PV power forecasts from the present time up to 14 days
        ahead for a registered PV power site using Solcast's advanced PV model.
      tags:
        - Forecast 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: hours
          in: query
          required: false
          description: Number of forecast hours to retrieve (up to 336).
          schema:
            type: integer
          example: 48
        - 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 forecast 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/forecast/soiling/kimber:
    get:
      operationId: getForecastSoilingKimber
      summary: Get Forecast Soiling (Kimber Model)
      description: >-
        Get hourly soiling loss forecasts using the Kimber model for the requested location.
      tags:
        - Forecast 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
        - name: format
          in: query
          required: false
          description: Response format.
          schema:
            type: string
            enum:
              - json
              - csv
          example: json
      responses:
        '200':
          description: Successful response with soiling forecast 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/forecast/soiling/hsu:
    get:
      operationId: getForecastSoilingHsu
      summary: Get Forecast Soiling (HSU Model)
      description: >-
        Get hourly soiling loss forecasts using Solcast's HSU model for the requested location.
      tags:
        - Forecast 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
        - name: format
          in: query
          required: false
          description: Response format.
          schema:
            type: string
            enum:
              - json
              - csv
          example: json
      responses:
        '200':
          description: Successful response with soiling forecast 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/forecast/aggregations:
    get:
      operationId: getForecastAggregations
      summary: Get Forecast Aggregations
      description: >-
        Get forecast aggregation data for up to 7 days ahead for a requested grid
        collection or sub-aggregation. Used for portfolio and grid management.
      tags:
        - Aggregations
      parameters:
        - name: collection_id
          in: query
          required: true
          description: Unique identifier for the grid aggregation collection.
          schema:
            type: string
        - name: aggregation_id
          in: query
          required: false
          description: Unique identifier for a specific sub-aggregation within the collection.
          schema:
            type: string
        - 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 aggregation forecast time series.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /data/historic/radiation_and_weather:
    get:
      operationId: getHistoricRadiationAndWeather
      summary: Get Historic Radiation and Weather
      description: >-
        Get historical irradiance and weather estimated actuals for up to 31 days of
        data at a time for a requested location. Data is available from 2007-01-01T00:00Z
        up to 7 days before present.
      tags:
        - Historic 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: start
          in: query
          required: true
          description: Start of requested period (ISO 8601 date or datetime, e.g., 2023-01-01 or 2023-01-01T00:00Z).
          schema:
            type: string
          example: '2023-01-01'
        - name: end
          in: query
          required: false
          description: End of requested period (mutually exclusive with duration).
          schema:
            type: string
          example: '2023-01-31'
        - name: duration
          in: query
          required: false
          description: >-
            ISO 8601 duration for the historic data, within 31 days of start
            (mutually exclusive with end). E.g., P7D for 7 days.
          schema:
            type: string
          example: P7D
        - 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 historic 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/historic/rooftop_pv_power:
    get:
      operationId: getHistoricRooftopPvPower
      summary: Get Historic Rooftop PV Power
      description: >-
        Get historical basic rooftop PV power estimated actuals for the requested location.
        Data is available from 2007-01-01 up to 7 days before present.
        Requests up to 31 days at a time.
      tags:
        - Historic 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: start
          in: query
          required: true
          description: Start of requested period (ISO 8601 date or datetime).
          schema:
            type: string
          example: '2023-01-01'
        - name: end
          in: query
          required: false
          description: End of requested period (mutually exclusive with duration).
          schema:
            type: string
          example: '2023-01-31'
        - name: duration
          in: query
          required: false
          description: ISO 8601 duration within 31 days of start (mutually exclusive with end).
          schema:
            type: string
          example: P7D
        - 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 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: 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 historic 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/historic/advanced_pv_power:
    get:
      operationId: getHistoricAdvancedPvPower
      summary: Get Historic Advanced PV Power
      description: >-
        Get historical high-specification PV power estimated actuals for a registered
        PV power site. Data available from 2007-01-01 up to 7 days before present.
        Requests up to 31 days at a time.
      tags:
        - Historic 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: start
          in: query
          required: true
          description: Start of requested period (ISO 8601 date or datetime).
          schema:
            type: string
          example: '2023-01-01'
        - name: end
          in: query
          required: false
          description: End of requested period (mutually exclusive with duration).
          schema:
            type: string
          example: '2023-01-31'
        - name: duration
          in: query
          required: false
          description: ISO 8601 duration within 31 days of start (mutually exclusive with end).
          schema:
            type: string
          example: P7D
        - 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 historic 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/historic/soiling/kimber:
    get:
      operationId: getHistoricSoilingKimber
      summary: Get Historic Soiling (Kimber Model)
      description: >-
        Get hourly historical soiling loss estimates using the Kimber model. Returns
        a time series of estimated historical cumulative soiling / cleanliness state
        for the requested location.
      tags:
        - Historic 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: start
          in: query
          required: true
          description: Start of requested period (ISO 8601 date or datetime).
          schema:
            type: string
          example: '2023-01-01'
        - name: end
          in: query
          required: false
          description: End of requested period (mutually exclusive with duration).
          schema:
            type: string
          example: '2023-01-31'
        - name: duration
          in: query
          required: false
          description: ISO 8601 duration within 31 days of start (mutually exclusive with end).
          schema:
            type: string
          example: P7D
        - 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
        - name: format
          in: query
          required: false
          description: Response format.
          schema:
            type: string
            enum:
              - json
              - csv
          example: json
      responses:
        '200':
          description: Successful response with historic 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/historic/soiling/hsu:
    get:
      operationId: getHistoricSoilingHsu
      summary: Get Historic Soiling (HSU Model)
      description: >-
        Get hourly historical soiling loss estimates using Solcast's HSU model.
        Returns a time series of estimated historical cumulative soiling / cleanliness
        state for the requested location.
      tags:
        - Historic 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: start
          in: query
          required: true
          description: Start of requested period (ISO 8601 date or datetime).
          schema:
            type: string
          example: '2023-01-01'
        - name: end
          in: query
          required: false
          description: End of requested period (mutually exclusive with duration).
          schema:
            type: string
          example: '2023-01-31'
        - name: duration
          in: query
          required: false
          description: ISO 8601 duration within 31 days of start (mutually exclusive with end).
          schema:
            type: string
          example: P7D
        - 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
        - name: format
          in: query
          required: false
          description: Response format.
          schema:
            type: string
            enum:
              - json
              - csv
          example: json
      responses:
        '200':
          description: Successful response with historic 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/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'
  /data/live/aggregations:
    get:
      operationId: getLiveAggregations
      summary: Get Live Aggregations
      description: >-
        Get live aggregation data for up to 7 days of data at a time for a requested
        grid collection or sub-aggregation. Used for grid and portfolio management.
      tags:
        - Aggregations
      parameters:
        - name: collection_id
          in: query
          required: true
          description: Unique identifier for the grid aggregation collection.
          schema:
            type: string
        - name: aggregation_id
          in: query
          required: false
          description: Unique identifier for a specific sub-aggregation within the collection.
          schema:
            type: string
        - 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 live aggregation time series.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /resources/pv_power_sites:
    get:
      operationId: listPvPowerSites
      summary: List PV Power Sites
      description: >-
        List all registered PV power sites associated with the authenticated account.
        Sites are used with the advanced PV power model.
      tags:
        - PV Power Sites
      parameters:
        - name: format
          in: query
          required: false
          description: Response format.
          schema:
            type: string
            enum:
              - json
              - csv
          example: json
      responses:
        '200':
          description: Successful response with list of PV power sites.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PvPowerSiteListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /resources/pv_power_site:
    get:
      operationId: getPvPowerSite
      summary: Get PV Power Site
      description: >-
        Retrieve specifications and metadata for a specific registered PV power site
        identified by its resource_id.
      tags:
        - PV Power Sites
      parameters:
        - name: resource_id
          in: query
          required: true
          description: Unique identifier for the PV power site.
          schema:
            type: string
          example: ba75-e17a-7374-95ed
        - name: format
          in: query
          required: false
          description: Response format.
          schema:
            type: string
            enum:
              - json
              - csv
          example: json
      responses:
        '200':
          description: Successful response with PV power site details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PvPowerSite'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      operationId: createPvPowerSite
      summary: Create PV Power Site
      description: >-
        Create a new PV power site for use with Solcast's advanced PV power model.
        Returns a unique resource_id for subsequent data queries.
      tags:
        - PV Power Sites
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PvPowerSiteCreate'
      responses:
        '201':
          description: PV power site created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PvPowerSite'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    patch:
      operationId: patchPvPowerSite
      summary: Patch PV Power Site
      description: >-
        Partially update specifications of an existing PV power site. Only provided
        fields are updated; all other fields remain unchanged.
      tags:
        - PV Power Sites
      parameters:
        - name: resource_id
          in: query
          required: true
          description: Unique identifier for the PV power site to update.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PvPowerSiteUpdate'
      responses:
        '200':
          description: PV power site updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PvPowerSite'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    put:
      operationId: updatePvPowerSite
      summary: Update PV Power Site
      description: >-
        Fully overwrite specifications of an existing PV power site. All current
        field values are replaced with the provided values.
      tags:
        - PV Power Sites
      parameters:
        - name: resource_id
          in: query
          required: true
          description: Unique identifier for the PV power site to overwrite.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PvPowerSiteCreate'
      responses:
        '200':
          description: PV power site overwritten successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PvPowerSite'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      operationId: deletePvPowerSite
      summary: Delete PV Power Site
      description: >-
        Permanently delete a registered PV power site. This action cannot be undone.
      tags:
        - PV Power Sites
      parameters:
        - name: resource_id
          in: query
          required: true
          description: Unique identifier for the PV power site to delete.
          schema:
            type: string
      responses:
        '200':
          description: PV power site deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  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.
  schemas:
    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).
    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.
    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.
    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.
    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
    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.
    AggregationDataPoint:
      type: object
      description: A single time period of aggregation 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: Aggregated PV power estimate for the collection in kilowatts.
          example: 125000.5
        pv_estimate10:
          type: number
          format: float
          description: Aggregated PV estimate at 10th percentile.
        pv_estimate90:
          type: number
          format: float
          description: Aggregated PV estimate at 90th percentile.
    AggregationResponse:
      type: object
      description: Response wrapper for aggregation time series data.
      properties:
        estimated_actuals:
          type: array
          items:
            $ref: '#/components/schemas/AggregationDataPoint'
          description: Array of live aggregation data points.
        forecasts:
          type: array
          items:
            $ref: '#/components/schemas/AggregationDataPoint'
          description: Array of forecast aggregation data points.
    PvPowerSite:
      type: object
      description: A registered Solcast PV power site with its specifications.
      properties:
        resource_id:
          type: string
          description: Unique identifier for the PV power site assigned by Solcast.
          example: ba75-e17a-7374-95ed
        name:
          type: string
          description: User-defined name for the site.
          example: My Rooftop Solar
        latitude:
          type: number
          format: float
          description: Site latitude in decimal degrees.
          example: -33.856784
        longitude:
          type: number
          format: float
          description: Site longitude in decimal degrees.
          example: 151.215297
        capacity:
          type: number
          format: float
          description: System capacity in kilowatts.
          example: 10.0
        tilt:
          type: number
          format: float
          description: Panel tilt angle in degrees from horizontal.
          example: 25
        azimuth:
          type: number
          format: float
          description: Panel azimuth in degrees (0/360 = north, 180 = south).
          example: 180
        install_date:
          type: string
          format: date
          description: Date the PV system was installed (YYYY-MM-DD).
          example: '2020-06-01'
        ac_capacity:
          type: number
          format: float
          description: AC inverter capacity in kilowatts.
        dc_capacity:
          type: number
          format: float
          description: DC system capacity in kilowatts.
        loss_factor:
          type: number
          format: float
          description: System loss factor as a fraction (0–1).
          example: 0.9
        tracking_type:
          type: string
          description: Tracking type (e.g., fixed, horizontal_single_axis, vertical_single_axis, two_axis).
          example: fixed
          enum:
            - fixed
            - horizontal_single_axis
            - vertical_single_axis
            - two_axis
        created_at:
          type: string
          format: date-time
          description: Timestamp when the site was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the site was last updated.
      required:
        - resource_id
        - name
        - latitude
        - longitude
    PvPowerSiteCreate:
      type: object
      description: Payload for creating or replacing a PV power site.
      properties:
        name:
          type: string
          description: User-defined name for the site.
          example: My Rooftop Solar
        latitude:
          type: number
          format: float
          description: Site latitude in decimal degrees, between -90 and 90.
          example: -33.856784
        longitude:
          type: number
          format: float
          description: Site longitude in decimal degrees, between -180 and 180.
          example: 151.215297
        capacity:
          type: number
          format: float
          description: System capacity in kilowatts.
          example: 10.0
        tilt:
          type: number
          format: float
          description: Panel tilt angle in degrees from horizontal (0 = flat).
          example: 25
        azimuth:
          type: number
          format: float
          description: Panel azimuth in degrees.
          example: 180
        install_date:
          type: string
          format: date
          description: Date the PV system was installed (YYYY-MM-DD).
          example: '2020-06-01'
        loss_factor:
          type: number
          format: float
          description: System loss factor as a fraction (0–1).
          example: 0.9
        tracking_type:
          type: string
          description: Tracking type.
          example: fixed
          enum:
            - fixed
            - horizontal_single_axis
            - vertical_single_axis
            - two_axis
      required:
        - name
        - latitude
        - longitude
    PvPowerSiteUpdate:
      type: object
      description: Payload for partially updating a PV power site (PATCH).
      properties:
        name:
          type: string
          description: User-defined name for the site.
        capacity:
          type: number
          format: float
          description: System capacity in kilowatts.
        tilt:
          type: number
          format: float
          description: Panel tilt angle in degrees from horizontal.
        azimuth:
          type: number
          format: float
          description: Panel azimuth in degrees.
        install_date:
          type: string
          format: date
          description: Date the PV system was installed (YYYY-MM-DD).
        loss_factor:
          type: number
          format: float
          description: System loss factor as a fraction (0–1).
        tracking_type:
          type: string
          description: Tracking type.
          enum:
            - fixed
            - horizontal_single_axis
            - vertical_single_axis
            - two_axis
    PvPowerSiteListResponse:
      type: object
      description: Response containing a list of registered PV power sites.
      properties:
        pv_power_sites:
          type: array
          items:
            $ref: '#/components/schemas/PvPowerSite'
          description: List of registered PV power sites.
    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
  responses:
    BadRequest:
      description: Bad request — invalid parameters or missing required fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized — API key is missing, invalid, or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Not found — the requested resource does not exist.
      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'
    TooManyRequests:
      description: Too many requests — API rate limit or quota exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'