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.

Measurements - Rooftop Site

An automated POST of regular power measurements for a site allows us to perform tuning for a site which will improve forecasts and observations over time. Shading and other factors that can impact power output at a PV site can be taken into account when showing forecasts or estimated actuals for the same site.

Be aware of your local timezone if you are not recording your measurements in UTC as when you convert localized times to ISO8601 you will need to be mindful of your timezone and if it is correctly marked in the datetime string format, this is of particular importance if you are recording localized times in Daylight Savings Time. This is important for the tuning aspect of the site and should agree with the latitude/longitude of the site day/night hours as expressed in UTC timezone (It is important to know what your timezone adjustment is when first integrating your measurement data).

It is important that when sending measurements that the time period from which the measurement was collected is submitted as the end time not the start time. The value of the total_power should be the period average of the specified period. For instantaneous values, set period to PT0S.

If incorrect measurements are sent, they are be replaced by resending values for the same period_end.

Request

POST /rooftop_sites/{resource_id}/measurements

/* Single measurement */
{
  "measurement": {
    "period_end": "2018-02-02T03:30:00.0000000Z",
    "period": "PT5M",
    "total_power": 1.23456
  }
}
/* Multiple measurements  */
{
  "measurements": [
    {
      "period_end":   "2018-02-02T03:30:00.0000000Z",
      "period": "PT5M",
      "total_power": 1.23456
     },
     {
      "period_end":   "2018-02-02T03:35:00.0000000Z",
      "period": "PT5M",
      "total_power": 1.98765
     }
  ] 
}

Url Parameters

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

Request Parameters

Parameter Description Required
measurement Single measurement posted to a single rooftop site Only required if measurements is empty
measurements Multiple measurement posted to a single rooftop site Only required if measurement is empty

Response

Attributes Type Description
measurement Measurement object Single measurement posted to a single rooftop site
measurements Array of measurement objects Multiple measurement posted to a single rooftop site

Measurement

Attributes Type Description
period_end DateTime End of the averaging period in ISO8601 datetime format in UTC timezone
period TimeSpan Length of averaging period in ISO8601 duration format.
total_power double Power output being measured averaged over the period ending at period_end

Error Codes

Code Description
400 The measurement does not pass validation (only for single measurement).
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.

World Solar Radiation Data

Solar irradiance forecasts and estimated actuals requested by location (latitude, longitude).

This is a JSON compatible replacement for the /radiation/* endpoints, see migration notes for more info.

Forecasts by location

This endpoint takes a location and returns a radiation forecast. The time window is by default 48 hours but can be extended up to 7 days.

{
  "forecasts": [{
      "ghi": 690,
      "ghi90": 802,
      "ghi10": 537,
      "ebh": 407,
      "dni": 501,
      "dni10": 334,
      "dni90": 792,
      "dhi": 283,
      "air_temp": 37,
      "zenith": 37,
      "azimuth": 72,
      "cloud_opacity": 35,
      "period_end": "2017-01-30T05:00:00.0000000Z",
      "period": "PT30M"
    }, {
      "ghi": 422,
      "ghi90": 707,
      "ghi10": 141,
      "ebh": 56,
      "dni": 78,
      "dni10": 3,
      "dni90": 722,
      "dhi": 366,
      "air_temp": 37,
      "zenith": 43,
      "azimuth": 78,
      "cloud_opacity": 81,
      "period_end": "2017-01-30T05:30:00.0000000Z",
      "period": "PT30M"
    }
  ]
}

Request

GET /world_radiation/forecasts

Url Parameters

Parameter Description Required
latitude The latitude of the location (EPSG:4326) eg, -35.123 Yes
longitude The longitude of the location (EPSG:4326) eg, 149.123 Yes
hours Time window of the response in hours (default 48, max 168) No

Response

Attributes Description
forecasts Array of forecasts for the requested location

Forecast

Attributes Description Details
ghi int Global Horizontal Irradiance (W/m2) - centre value (mean)
ghi90 int Global Horizontal Irradiance (W/m2) - 90th percentile value (high scenario)
ghi10 int Global Horizontal Irradiance (W/m2) - 10th percentile value (low scenario)
dni int Direct Normal Irradiance (W/m2) - centre value (mean)
dni10 int Direct Normal Irradiance (W/m2) - 10th percentile value (low scenario)
dni90 int Direct Normal Irradiance (W/m2) - 90th percentile value (high scenario)
dhi int Diffuse Horizontal Irradiance
air_temp int Air temperature (degrees Celsius)
zenith int Solar zenith angle (degrees). Zero means directly upwards/overhead. Varies from 0 to 180. A value of 90 means the sun is at the horizon.
azimuth double Solar azimuth angle (degrees). Zero means true north. Vaies from -180 to 180. A value of 90 means the sun is in the east.
cloud_opacity int The 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
400 Latitude, longitude or hours are invalid, see response_status for further details
404 The location is outside our coverage area.

GHI only

This endpoint limits the output to GHI only forecasts.

Request

GET /world_radiation/forecasts/ghi

{
  "forecasts": [{
      "ghi": 690,
      "ghi90": 802,
      "ghi10": 537,
      "period_end": "2017-01-30T05:00:00.0000000Z",
      "period": "PT30M"
    }, {
      "ghi": 422,
      "ghi90": 707,
      "ghi10": 141,
      "period_end": "2017-01-30T05:30:00.0000000Z",
      "period": "PT30M"
    }
  ]
}

Url Parameters

Parameter Description Required
latitude The latitude of the location (EPSG:4326) eg, -35.123 Yes
longitude The longitude of the location (EPSG:4326) eg, 149.123 Yes
hours Time window of the response in hours (default 48, max 168) No

Response

Attributes Description
forecasts Array of forecasts for the requested location

Forecast

Attributes Description Details
ghi int Global Horizontal Irradiance (W/m2) - centre value (mean)
ghi90 int Global Horizontal Irradiance (W/m2) - 90th percentile value (high scenario)
ghi10 int Global Horizontal Irradiance (W/m2) - 10th percentile value (low 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 Latitude, longitude or hours are invalid, see response_status for further details
404 The location is outside our coverage area.

Estimated actuals by location

This endpoint takes a location and returns satellite derived observations ("estimated actuals"). The time window is by default 48 hours but can be extended up to 7 days.

{
  "estimated_actuals": [{
      "ghi": 640,
      "ebh": 516,
      "dni": 803,
      "dhi": 124,
      "cloud_opacity": 0,
      "period_end": "2017-01-29T23:00:00.0000000Z",
      "period": "PT30M"
    }, {
      "ghi": 543,
      "ebh": 430,
      "dni": 769,
      "dhi": 113,
      "cloud_opacity": 0,
      "period_end": "2017-01-29T22:30:00.0000000Z",
      "period": "PT30M"
    }
  ]
}

Request

GET /world_radiation/estimated_actuals

Url Parameters

Parameter Description Required
latitude The latitude of the location (EPSG:4326) eg, -35.123 Yes
longitude The longitude of the location (EPSG:4326) eg, 149.123 Yes
hours Time window of the response in hours (default 48, max 168) No

Response

Attributes Description
estimated_actuals Array of estimated actuals for the requested location

Estimated Actuals

Attributes Description Details
ghi int Global Horizontal Irradiance (W/m2) - centre value (mean)
dni int Direct Normal Irradiance (W/m2) - centre value (mean)
dhi int Diffuse Horizontal Irradiance
cloud_opacity int The 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
400 Latitude, longitude or hours are invalid, see response_status for further details
404 The location is outside our coverage area.

GHI Only

This endpoint limits the output to GHI only estimated actuals.

Request

GET /world_radiation/estimated_actuals/ghi

{
  "estimated_actuals": [{
      "ghi": 640,
      "period_end": "2017-01-29T23:00:00.0000000Z",
      "period": "PT30M"
    }, {
      "ghi": 543,
      "period_end": "2017-01-29T22:30:00.0000000Z",
      "period": "PT30M"
    }
  ]
}

Url Parameters

Parameter Description Required
latitude The latitude of the location (EPSG:4326) eg, -35.123 Yes
longitude The longitude of the location (EPSG:4326) eg, 149.123 Yes
hours Time window of the response in hours (default 48, max 168) No

Response

Attributes Description
estimated_actuals Array of estimated actuals for the requested location

Estimated Actuals

Attributes Description Details
ghi int Global Horizontal Irradiance (W/m2) - centre value (mean)
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 Latitude, longitude or hours are invalid, see response_status for further details
404 The location is outside our coverage area.

Migrating from our beta radiation endpoint

Since the launch of the Solcast API in early 2017 we offered an easy way to get solar radiation forecasts or estimated actuals by just providing a location (longitude, latitude). To make the migration to this replacement API easier, we've maintained JSON compatibility and as well as listened to feedback on making the API easier to use for different use cases.

A breaking change to JSON users will be the default length of time window that is returned from this API call. Previously we always returned 7 days worth of data however, this will be reduced to 48 hours along with a way to either decrease or increase this time window by providing an optional hours parameter. For example, &hours=72 will return most recent 3 day time window where as &hours=4 will return the most recent 4 hour time window.

If you are using this endpoint in an automated way with either XML or CSV, we recommend (and only support) migrating to using the JSON format response type (by use of the Accept: application/json header or &format=json), see Data Formats and notes in JSON Only Support section for more info. If you need assistance migrating, please reach out on our community forums.

If you are using JSON and 48 hours still works for your usage scenario, you will need to update the URL from /radiation/forecasts to /world_radiation/forecasts, or for estimated actuals, /radiation/estimated_actuals to /world_radiation/estimated_actuals. Everything else is the same for JSON clients. While the original /radiation/* endpoints will continue to operate, we will be sending out notifications to clients currently using the beta endpoints and let them know of specific dates for when they will need to migrate.

World PV Power Data

World PV power data requested by location (latitude, longitude). This endpoint uses live radiation data to return modelled PV forecasts or estimated actuals based on the parameters specified in the request.

This is a JSON compatible replacement for the /pv_power/forecasts and /pv_power/estimated_actuals endpoints, see migration notes for more info.

World PV power forecasts by location

This endpoint takes a location along with PV system capacity and other optional parameters to produce a PV power forecast based on satellite derived radiation. The time window is by default 48 hours but can be extended up to 7 days.

{
  "forecasts": [{
      "period_end": "2019-08-01T04:00:00.0000000Z",
      "period": "PT30M",
      "pv_estimate": 3084.34529720409
    },
    {
      "period_end": "2019-08-01T04:30:00.0000000Z",
      "period": "PT30M",
      "pv_estimate": 2835.17088260779
    }]
}

Request

GET /world_pv_power/forecasts

Url Parameters

Parameter Description Required
latitude The latitude of the location (EPSG:4326) eg, -35.123 Yes
longitude The longitude of the location (EPSG:4326) eg, 149.123 Yes
capacity The capacity of the system, units in kilowatts. Must be greater than zero. Yes
tilt The angle (degrees) that the PV system is tilted off the horizontal. Must be between 0 and 90. A tilt of 0 means the system is facing directly upwards, and 90 means the system is vertical and facing the horizon. The default value is 23. No
azimuth The angle (degrees) from true north that the PV system is facing, if titled. Must be between -180 and 180. An azimuth of 0 means the system is facing true north. Positive values are anticlockwise, so azimuth is -90 for an east-facing system and 135 for a southwest-facing system. The default value is 0 (north facing) in the southern hemisphere, 180 (south-facing) in the northern hemisphere. No
install_date The date (yyyy-MM-dd) of installation of the PV system. We use this to estimate your loss_factor based on the ageing of your system. If you provide us with a loss_factor directly, we will ignore this date. No
loss_factor A factor by which to reduce your output forecast from the full capacity based on characteristics of the PV array or inverter. This is effectively the non-temperature loss effects on the nameplate rating of the PV system, including inefficiency and soiling. For a 1kW PV system anything that reduces 1000W/m2 solar radiation from producing 1000W of power output (assuming temperature is 25C) No
hours Time window of the response in hours (default 48, max 168) No

Response

Attributes Description
forecasts Array of power forecasts for the requested location

Power Forecast

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 Invalid parameters, see response_status for more details
404 The location is outside our coverage area.

World PV power estimated actuals by location

This endpoint takes a location and returns satellite derived observations ("estimated actuals") for a specific location and PV system parameters. The time window is by default 48 hours but can be extended up to 7 days.

{
  "estimated_actuals": [{
      "period_end": "2019-08-01T04:00:00.0000000Z",
      "period": "PT30M",
      "pv_estimate": 3078.02380941897
    }, {
      "period_end": "2019-08-01T03:30:00.0000000Z",
      "period": "PT30M",
      "pv_estimate": 3318.10586932724
    }
  ]
}

Request

GET /world_pv_power/estimated_actuals

Url Parameters

Parameter Description Required
latitude The latitude of the location (EPSG:4326) eg, -35.123 Yes
longitude The longitude of the location (EPSG:4326) eg, 149.123 Yes
capacity The capacity of the system, units in kilowatts. Must be greater than zero. Yes
tilt The angle (degrees) that the PV system is tilted off the horizontal. Must be between 0 and 90. A tilt of 0 means the system is facing directly upwards, and 90 means the system is vertical and facing the horizon. The default value is 23. No
azimuth The angle (degrees) from true north that the PV system is facing, if titled. Must be between -180 and 180. An azimuth of 0 means the system is facing true north. Positive values are anticlockwise, so azimuth is -90 for an east-facing system and 135 for a southwest-facing system. The default value is 0 (north facing) in the southern hemisphere, 180 (south-facing) in the northern hemisphere. No
install_date The date (yyyy-MM-dd) of installation of the PV system. We use this to estimate your loss_factor based on the ageing of your system. If you provide us with a loss_factor directly, we will ignore this date. No
loss_factor A factor by which to reduce your output forecast from the full capacity based on characteristics of the PV array or inverter. This is effectively the non-temperature loss effects on the nameplate rating of the PV system, including inefficiency and soiling. For a 1kW PV system anything that reduces 1000W/m2 solar radiation from producing 1000W of power output (assuming temperature is 25C) No
hours Time window of the response in hours (default 48, max 168) No

Response

Attributes Description
estimated_actuals Array of power estimated actuals for the requested location and PV system paramters.

Power Estimated Actuals

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 Invalid parameters, see response_status for more details
404 The location is outside our coverage area.

Migrating from our beta PV power endpoint

Since the launch of the Solcast API in early 2017 we offered an easy way to get PV power forecasts or estimated actuals by just providing a location (longitude, latitude) and details about your system. To make the migration to this replacement API easier, we've maintained JSON compatibility and as well as listened to feedback on making the API easier to use for different use cases.

Breaking changes

Default return time window breaking change to JSON users will be the default length of time window that is returned from this API call. Previously we always returned 7 days worth of data however, this will be reduced to 48 hours along with a way to either decrease or increase this time window by providing an optional hours parameter. For example, &hours=72 will return most recent 3 day time window where as &hours=4 will return the most recent 4 hour time window. install_date format change will throw a 400 if format is incorrect.

If you are using this endpoint in an automated way with either XML or CSV, we recommend (and only support) migrating to using the JSON format response type (by use of the Accept: application/json header or &format=json), see Data Formats and notes in JSON Only Support section for more info. If you need assistance migrating, please reach out on our community forums.

If you are using JSON and 48 hours still works for your usage scenario and not using the install_date parameter, you will only
need to update the URL from /pv_power/forecasts to /world_pv_power/forecasts, or for estimated actuals, /pv_power/estimated_actuals to /world_pv_power/estimated_actuals. Everything else is the same for JSON clients. While the original /pv_power endpoints will continue to operate, we will be sending out notifications to clients currently using the beta endpoints and let them know of specific dates for when they will need to migrate.