NAV Navbar
json

Introduction

Welcome to the first draft of our documentation of Solcast’s our ​‘sites’ ​based ​API​ for ​rooftop and​ utility scale​ solar systems. This API can provide both ​forecasts​ and estimates of the actual power output (​estimated actuals​) from solar PV systems. The API is structured by a ‘sites’ based framework, where users will be provided with unique identifier for each registered PV site, which can be used to retrieve the ​forecasts​ or ​estimated actuals​ for that site. This sites based framework allows Solcast to provide you with access to our ​‘tuning’ ​technologies, which use measured power output data from a PV site to individualise and improve forecasts. This sites-based framework also allows Solcast to provide real-time reporting on forecast accuracy, so that you can track our performance and validate our product with ease.

Lastly, before we get started, do us a favour - if you find any errors, or something is unclear, or just have some helpful feedback, please let us know at ​support@solcast.com.au​. Oh, and we’re assuming you’ve ​already signed-up for the API​ moving forward, so do that now if you haven’t!

Data Formats

All ​GET ​endpoints support ​HTML ​(​preview​), ​JSON​, ​CSV ​and ​XML ​data formats by one of the following methods:

Exploration of data can use any of these data formats however only JSON should be used for integrations as not all formats are support on all endpoints.

JSON only support

The Solcast API can serialize multiple formats including JSON, XML and CSV. Though these different formats are available, JSON is the only serialization format that works everywhere across our API. XML and CSV should not be used for automated integration. XML/CSV can be handy for exploring our data however production systems should use JSON only for integration.

If you are using XML or CSV in an integration, move the integration to the respective JSON endpoint as soon as possible. Changes that are backwards compatible for JSON (like the addition of a property) can be brittle for CSV or XML which can cause problems for projects with existing integrations. If you are a customer and need help with this migration, please reach out to support@solcast.com.au.

Authentication

Authentication for these endpoints can be done via one of the following methods using your user specific ​API​ key which is accessible from your ​ account page on the Solcast website​. An API​ key will be a 32 character text string e.g. ​01234567890123457890123456789012

Name Description
Query string Add the ​api_key​ query string parameter to the URL of your request, eg ​&api_key=your_api_key​
Bearer token Add the following ​Authorization​ header of your request: ​Authorization: Bearer​ ​your_api_key​
Basic Use ​Basic authentication​ and provide your ​API​ key as the username with an empty password. For more information, see ​Basic access Authentication
Digest Use ​Digest based authentication​ and provide your ​API​ key as the username with an empty password. For more information, see ​Digest access Authentication

Rate Limits

The Solcast API supports a default rate limit of 600 requests per minute per user. If you exceed this limit, your request to the API will receive a 429 status code, indicating you have exceeded your rate limit.

When this occurs, the response from the Solcast API will contain a few headers that aim to help you handle rate limiting:

  1. x-rate-limit specifies what the rate limit is per minute.
  2. x-rate-remaining specifies how many additional requests you can make until the rate limit is exceeded.
  3. x-rate-limit-reset specifies when (UTC in Unix Time format) the limit will reset.

Rooftop Sites

Rooftop sites are PV sites that have a fixed tilt and capacity under 1MW. This API is suited to small to medium PV sites, usually on a rooftop of a residential home or a commercial building.

Forecasts - Rooftop Site

This endpoint will retrieve the forecasts for a single rooftop site.

{
  "forecasts": [
    {
      "pv_estimate": "9.5",
      "pv_estimate10": "6",
      "pv_estimate90": "13.8",
      "period_end": "2018-01-01T01:00:00.00000Z",
      "period": "PT30M"
    },
    {
      "pv_estimate": "10",
      "pv_estimate10": "8",
      "pv_estimate90": "12",
      "period_end": "2018-01-01T12:30:00.00000Z",
      "period": "PT30M"
    }
  ]
}

Request

GET /rooftop_sites/{resource_id}/forecasts

Url Parameters

Parameter Description Required
resource_id The resource id of the rooftop site Yes

Response

Attributes Description
forecasts Array of forecasts for the rooftop site.

Forecast

Attributes Description Details
pv_estimate double PV power estimated in kilowatts (kW)
pv_estimate10 double PV power estimate in kilowatts (kW) 10th percentile (low scenario)
pv_estimate90 double PV power estimate in kilowatts (kW) 90th percentile (high scenario)
period_end datetime End of the averaging period in ISO8601 datetime format in UTC timezone
period string Length of the averaging period in ISO8601 duration format

Error Codes

Code Description
400 The rooftop site missing capacity, please specify capacity or provide historic data for tuning.
404 The rooftop site cannot be found or is not accessible.

Estimated Actuals - Rooftop Site

This endpoint will retrieve the estimated actuals for a single rooftop site.

{
  "estimated_actuals": [
    {
      "pv_estimate": "10",
      "period_end": "2018-01-01T01:00:00.00000Z",
      "period": "PT30M"
    },
    {
      "pv_estimate": "9",
      "period_end": "2018-01-01T12:30:00.00000Z",
      "period": "PT30M"
    }
  ]
}

Request

GET /rooftop_sites/{resource_id}/estimated_actuals

Url Parameters

Parameter Description Required
resource_id The resource id of the rooftop site Yes

Response

Attributes Description
estimated_actuals The estimated actuals for the rooftop site

Estimated actual

Attributes Description Details
pv_estimate double PV power estimated in kilowatts (kW)
period_end datetime End of the averaging period in ISO8601 datetime format in UTC timezone
period string Length of the averaging period in ISO8601 duration format

Error Codes

Code Description
400 The rooftop site missing capacity, please specify capacity or provide historic data for tuning.
404 The rooftop site cannot be found or is not accessible.

Utility Scale Sites

Utility scale sites are PV sites that don’t have limitation of capacity and have a range of additional features to support power utility PV sites such as tracking, inverter availability, and much more.

Forecasts - Utility Scale Site

This endpoint will retrieve the forecasts for a single utility scale site.

{
  "forecasts": [
    {
      "pv_estimate": "9.5",
      "pv_estimate10": "6",
      "pv_estimate90": "13.8",
      "period_end": "2018-01-01T01:05:00.00000Z",
      "period": "PT5M"
    },
    {
      "pv_estimate": "10",
      "pv_estimate10": "8",
      "pv_estimate90": "12",
      "period_end": "2018-01-01T01:00:00.00000Z",
      "period": "PT5M"
    }
  ]
}

Request

GET /utility_scale_sites/{resource_id}/forecasts

Url Parameters

Parameter Description Required
resource_id The resource id of the utility scale site Yes

Query Parameters

Parameter Description Default
Period Length of the averaging period in ISO8601 duration format PT30M
Hours An offset to which the number of forecasts will be included in the response 168

Response

Attributes Description
forecasts The forecasts for the utility scale site

Forecast

Attributes Description Details
pv_estimate double PV power estimated in megawatts (MW)
pv_estimate10 double PV power estimate in megawatts (MW) 10th percentile (low scenario)
pv_estimate90 double PV power estimate in megawatts (MW) 90th percentile (high scenario)
period_end datetime End of the averaging period in ISO8601 datetime format in UTC timezone
period string Length of the averaging period in ISO8601 duration format

Error Codes

Code Description
404 The utility scale site cannot be found or is not accessible.
404 Forecasts cannot be found for the site at the specified period.

Estimated Actuals - Utility Scale Site

This endpoint will retrieve the estimated actuals for a single utility scale site.

{
  "estimated_actuals": [
    {
      "pv_estimate": "10",
      "period_end": "2018-01-01T01:05:00.00000Z",
      "period": "PT5M"
    },
    {
      "pv_estimate": "9",
      "period_end": "2018-01-01T01:00:00.00000Z",
      "period": "PT5M"
    }
  ]
}

Request

GET /utility_scale_sites/{resource_id}/estimated_actuals

Url Parameters

Parameter Description Required
resource_id The resource id of the utility scale site Yes

Query Parameters

Parameter Description Default
Period Length of the averaging period in ISO8601 duration format PT30M
Hours An offset to which the number of estimated actuals will be included in the response 168

Response

Attributes Description
estimated_actuals The estimated actuals for the utility scale site

Estimated actual

Attributes Description Details
pv_estimate double PV power estimated in megawatts (MW)
period_end datetime End of the averaging period in ISO8601 datetime format in UTC timezone
period string Length of the averaging period in ISO8601 duration format

Error Codes

Code Description
404 The utility scale site cannot be found or is not accessible.

Weather Sites

Solar irradiance and other weather data.

Forecasts - Weather site

This endpoint will retrieve the forecasts for a single weather site.

{
  "forecasts": [
    {
      "ghi": "10",
      "ghi90": "12",
      "ghi10": "8",
      "ebh": "10",
      "dni": "10",
      "dni90": "12",
      "dni10": "8",
      "air_temp": "20",
      "zenith": "90",
      "azimuth": "45.1234",
      "cloud_opacity": "12",
      "period_end": "2018-01-01T01:00:00.00000Z",
      "period": "PT30"
    },
    {
      "ghi": "10",
      "ghi90": "12",
      "ghi10": "8",
      "ebh": "10",
      "dni": "10",
      "dni90": "12",
      "dni10": "8",
      "air_temp": "20",
      "zenith": "90",
      "azimuth": "45.1234",
      "cloud_opacity": "12",
      "period_end": "2018-01-01T12:30:00.00000Z",
      "period": "PT30"
    }
  ]
}

Request

GET /weather_sites/{resource_id}/forecasts

Url Parameters

Parameter Description Required
resource_id The resource id of the weather site Yes

Response

Attributes Description
forecasts The forecasts for the weather site

Forecasts (radiation data)

Attributes Description Details
ghi int Global Horizontal Irradiance (W/m2) - centre value (mean).
ghi90 int Global Horizontal Irradiance (W/m2) 90th percentile (high scenario)
ghi10 int Global Horizontal Irradiance (W/m2) 10th percentile (low scenario)
ebh int Direct (Beam) Horizontal Irradiance
dni int Direct Normal Irradiance (W/m2)
dni90 int Direct Normal Irradiance (W/m2) 90th percentile (high scenario)
dni10 int Direct Normal Irradiance (W/m2) 10th percentile (low scenario)
dhi int Diffuse Horizontal Irradiance
air_temp int The temperature of the air in the given location (10 meters above ground level)
zenith int The angle between a line perpendicular to the earth's surface and the sun (90 deg = sunrise and sunset; 0 deg = sun directly overhead)
azimuth float The angle between a line pointing due north to the sun's current position in the sky. Negative to the East. Positive to the West. 0 at due North.
cloud_opacity int The measurement of how opaque the clouds are to solar radiation in the given location. Attenuation of incoming light due to cloud. Varies from 0 (no cloud) to 100 (full attenuation of incoming light).
period_end datetime End of the averaging period in ISO8601 datetime format in UTC timezone
period string Length of the averaging period in ISO8601 duration format

Error Codes

Code Description
404 The weather site cannot be found or is not accessible.

Estimated Actuals - Weather site

This endpoint will retrieve the estimated actuals for a single weather site.

{
  "estimated_actuals": [
    {
      "ghi": "10",
      "ebh": "10",
      "dni": "10",
      "dhi": "10",
      "cloud_opacity": "12",
      "period_end": "2018-01-01T01:05:00.00000Z",
      "period": "PT5M"
    },
      {
        "ghi": "10",
        "ebh": "10",
        "dni": "10",
        "dhi": "10",
        "cloud_opacity": "12",
        "period_end": "2018-01-01T01:00:00.00000Z",
        "period": "PT5M"
      }
  ]
}

Request

GET /weather_sites/{resource_id}/estimated_actuals

Url Parameters

Parameter Description Required
resource_id The resource id of the weather site Yes

Response

Attributes Description
estimated_actuals The estimated actuals for the weather site

Estimated actual (radiation data)

Attributes Description Details
ghi int Global Horizontal Irradiance (W/m2) - centre value (mean).
ebh int Direct (Beam) Horizontal Irradiance
dni int Direct Normal Irradiance (W/m2) - centre value (mean).
dhi int Diffuse Horizontal Irradiance
cloud_opacity int The measurement of how opaque the clouds are to solar radiation in the given location.
period_end datetime End of the averaging period in ISO8601 datetime format in UTC timezone
period string Length of the averaging period in ISO8601 duration format

Error Codes

Code Description
404 The weather site cannot be found or is not accessible.