Steadysun API

The Steadysun API provides an easy way to integrate your forecast data with any external system. The API closely follows REST semantics, uses JSON to encode objects, and relies on standard HTTP codes to signal operation outcomes.

Getting Started

To begin using the API, a paid subscription is required. For more details or to request a quote contact us.

Authentification

Steadysun uses simple token-based authentication.

All API requests must be authenticated and made over HTTPS.
The token must be added in the header.
You must authenticate to the API by providing your API token in the HTTP authorization token header.

Key

Value

Authorization

Token {your token}

Asset Management

The set of requests in this section allows you to manage the assets of your subscription contract.
In the STEADYSUN API, a power plant is called a PV System.
In the STEADYSUN API, a Portfolio gathering several plants is called a Group.
You will find ready-to-use examples in Python.

Main API url
https://steadyweb.steady-sun.com/api/v1/

POST One PV System

To add one power plant (or PV System), its parameters have to be specified in a POST request with following requirements.

Requested parameters:

Title : limited to 128 characters
Name : limited to 32 characters
Latitude and longitude coordinates must be specified in decimal degrees (°).
Altitude is in meters (m).
Requested variables (or "fields") must be specified by their respective id; the correspondance between fields and their id can be retrieved via this request.
PV type corresponds to the power plant type (fixed, 1-axis tracker or 2-axis tracker). fixed=1, 1-axis tracker=2, 2-axis tracker=3. If you select a tracker PV type, you can specify the additional 'tracker_config' parameter.
The requested forecast length (or "horizon") must be specified in minutes.

For each PVSytem, one can specify a number of solar arrays. A PVSystem must have at least one array and only fixed systems can have multiple arrays. A PVSystem can have multiple arrays facing in different directions for example. Each array depends on the following parameters:

Orientation of the array is the azimuth of the main axis of the panels, in degrees (°). 0° corresponds to North, 180° corresponds to South.
Inclination of the panels is in degrees (°) taken between the ground and the panel. 0° is horizontal.
Power (pvmodules_pdc0) is in Watts (W).

Optional array parameters:
These describe in more detail the behavior of the panels and rely mainly on the public pvlib library.

Module Technology corresponds to whether the panels are bifacial or standard. If you select 'bifacial', you must specify the additional 'bifacial_config' parameter.
Module Material indicates the type of semiconductor used in the panels. Available choices are 'monosi', 'cigs', 'asi', 'cdte', 'xsi', 'multisi', 'polysi'. Details about these options can be found on the pvlib documentation.
Racking is the manner that the panels are mounted to their structure: Available choices are 'open_rack', 'close_mount' (typically meaning that the panels are installed on an existing roof), 'insulated_back' (typically meaning that the panels are completely integrated in a roof).
Module type is the type of interface protecting the panel. Available choices are 'glass_polymer' or 'glass_glass'.
The 'power_temp_coeff' is the loss coefficient of efficiency versus temperature, in %/°C, typically between -2 and 0 %/°C.

Other optional parameters:

The 'tracker_config' is only relevant in case of a tracker PV type. If none is provided, some default parameters are assumed which can be found in the exemple below. Otherwise: 'max angle' is the maximum angle in degrees that the panel can tilt to, 'backtrack' designates whether backtracking is enabled on the panels, 'gcr' is the ground covering ratio of the panels between 0 and 1, 'slope_azimuth' is the orientation of the rotation axis of the panel in degrees, 'slope_tilt' is the inclination of the rotation axis of the panel in degrees.
The 'bifacial_config' is only relevant in case of bifacial panels. If none is provided, some default parameters are assumed which can be found in the example below. Otherwise: 'bifaciality' is the power ratio between the backside and the frontside (between 0 and 1), 'gcr' is the ground covering ratio of the panels (between 0 and 1) and 'pvrow_height' and 'pvrow_width' are in m.
The inverter_parameters are the parameters of AC/DC conversion unit. 'pdc0' is the peak power of AC of the inverter, in Watts. It is typically the same as or bigger than the sum of all 'pvmodules_pdc0', but it can be less in case of a power plant with curtailement. 'eta_inv_norm' is the efficiency of the power conversion (between 0 and 1).

API endpoint https://steadyweb.steady-sun.com/api/v1/pvsystem/

Some parameters are indicated via integers. Here below is list of values and their corresponding integer.

Parameters

Value

Integer (int)

pv_type

fixed

single_axis

double_axis

module_technology

standard

bifacial

module_material

monosi

cigs

asi

cdte

xsi

multisi

polysi

racking

open_rack

close_mount

insulated_back

module_type

glass_polymer

glass_glass

# Imports
import requests
import json

# Configure API authentification
headers = {
'Content-type':'application/json',
'Accept':'application/json',
'Authorization':'Token {your token}'
}
url = "https://steadyweb.steady-sun.com/api/v1/pvsystem/"

# Plant configuration
latitude = 45.19       # in decimal degrees
longitude = 5.82      # in decimal degrees

config = {
    "title": "My_Test_Site",
    "name": "My_Test_Site",    # this field is required
    "requested_fields": [     # this field is required
    {"field": 13, "with_quantiles": True },
    {"field": 78, "with_quantiles": True}
   ],
  "location": {              # this field is required
    "type": "Point",
    "coordinates": [longitude, latitude]
   },
   "altitude": 215.0,             # in m, this field is required
   "pv_type": 2, # this field is required
   "horizon": 1440, # in minutes, this field is required
   "arrays": [
   {
    "pvmodules_pdc0": 10000,  # of AC, in W, this field is required
    "orientation": 180,           # in °, this field is required
    "inclination": 20,       # in °, this field is required
    "module_technology": 1,    # => "standard"
    "module_material": 1,      # => "monosi"
    "racking": 1,             # => "open_rack"
    "module_type": 1,         # => "glass_polymer"
    "power_temp_coeff": -0.4,
    }
  ],
  "installation_date": "2023-02-23",
  "is_active": True,
  "tracker_config": {               # only if you have a tracker
    "max_angle": 90,
     "backtrack": True,
     "gcr": 0.34,
     "slope_azimuth": 0,
     "slope_tilt": 0,
  },
  "bifacial_config": {               # only if you have bifacial panels
     "bifaciality": 0.8,
     "gcr": 0.34,
"pvrow_height": 2,
"pvrow_width": 4,
  },
    "inverter_parameters":{
     "pdc0": 10000,
     "eta_inv_norm": 0.97,
  }
}

json_object = json.dumps(config)
result = requests.post(url, headers=headers, data=json_object)

print(json.loads(result.text))

Language

Python

To ensure the PVSystem was created properly, check the answer of the server: it must be 201. The answer should also return a dictionary with the information and especially the uuid of the pvsystem you just created.

POST Multiple PV Systems

To post multiple PV Systems, simply iterate the creation of a single PV System. Here below, ten PV systems with random latitude/longitude coordinates are posted on the API, considering the same 'config' as in the previous example.

API endpoint https://steadyweb.steady-sun.com/api/v1/pvsystem/

import numpy as np
import requests
import json

headers = {
'Content-type':'application/json',
'Accept':'application/json',
'Authorization':'Token {your token}',
}
url = "https://steadyweb.steady-sun.com/api/v1/pvsystem/"

for site in range(0,10):
  latitude = np.random.random() + 45
  longitude = np.random.random()+ 5
  config["title"] = f"My_Test_Site_{site}",
  config["name"] = f"My_Test_Site_{site}",
  config["location"] = {
    "type": "Point",
    "coordinates": [longitude, latitude],
  }
json_object = json.dumps(config)
result = requests.post(url, headers=headers, data=json_object)

print(json.loads(result.text))

Language

Python

GET PV System

To retrieve all the PV Systems you have already created, execute the following script.

API endpoint https://steadyweb.steady-sun.com/api/v1/pvsystem/

import requests
import json

headers = {
'Content-type':'application/json',
'Accept':'application/json',
'Authorization':'Token {your token}'
}
url = "https://steadyweb.steady-sun.com/api/v1/pvsystem/"

result = requests.get(url, headers=headers)

print(json.loads(result.text))

Language

Python

GET GROUP

For now, creation of groups and the handling of the hierarchy of various pvsystems is not open to users.
However, a user can request to Steadysun's team these creations.
To retrieve all the groups that have been already created, execute the following script.

API enpoint https://steadyweb.steady-sun.com/api/v1/group/

import requests
import json

headers = {
'Content-type':'application/json',
'Accept':'application/json',
'Authorization':'Token {your token}'
}
url = "https://steadyweb.steady-sun.com/api/v1/group/"

result = requests.get(url, headers=headers)

print(json.loads(result.text))

Language

Python

PATCH or PUT One PV System

API users can modify the characteristics of their PV Systems, by using a PATCH or PUT request (PUT request must be exhaustive and contain all the fields in the request's content, even if those that are not modified. PATCH requests only require the modified fields in the request's content). Simply extend the endpoint URL by using the specific PV System's UUID (retrieved via a GET request) and provide in the data a dictionnary of properties you would like to change.
NB: When modifying an array parameter, the list of arrays must always be exhaustive.

API endpoint https://steadyweb.steady-sun.com/api/v1/pvsystem/

import requests
import json

headers = {
'Content-type':'application/json',
'Accept':'application/json',
'Authorization':'Token {your token}'
}

plant_uuid = "replace-this-with-uuid" # Fill in the plant's UUID
url = f"https://steadyweb.steady-sun.com/api/v1/pvsystem/{plant_uuid}"

config={
"pv_type": 2,    # changing the PVSystem type to a single-axis tracker
"arrays": [
  {
   "pvmodules_pdc0": 20000, # doubling the power of array
   "orientation": 180, #
   "inclination": 20, #
   "module_technology": 1, # the folowing fields are not modified
"module_material": 1, # but must be specified either way
   "racking": 1, #
   "module_type": 1, #
   "power_temp_coeff": -0.4, #
  }
],
"inverter_parameters": {    # modifying inverter_parameters as well
  "pdc0": 21000, # to account for the change of power
  "eta_inv_norm": 0.98,
}
}

json_object = json.dumps()
result = requests.patch(url, headers=headers, data=json_object)

print(json.loads(result.text))

Language

Python

PATCH or PUT Multiple PV Systems

To patch multiple PV Systems, simply iterate through th process of patching a single PV System. Here below for example, three PV systems are patched on the API given the list of their respective UUIDs. Their 'is_active' attribute is modified to 'False', effectively deactivating the systems in Steadysun's backend and thus stopping their forecasts.

API endpoint https://steadyweb.steady-sun.com/api/v1/pvsystem/

import requests
import json

headers = {
"Content-type": "application/json",
"Accept": "application/json",
"Authorization": "Token {your token}",
}
uuids_list = [ # Fill in the plants' UUID
"replace-this-with-uuid1",
"replace-this-with-uuid2",
"replace-this-with-uuid3",
]

for plant_uuid in uuids_list:
url = f"https://steadyweb.steady-sun.com/api/v1/pvsystem/{plant_uuid}"
config = {"is_active" = False}
json_object = json.dumps(config)

result = requests.post(url, headers=headers, data=json_object)
print(json.loads(result.text))

Language

Python

Get forecasts

GET Forecasts for PV System

To get the forecast of a PV System, extend the endpoint URL by using the specific PV System's UUID (retrieved via a GET request). The API takes in several additional parameters that the user can tune to modify the retrieved forecasts. The available parameters are described in the Parameters section.

API endpoint https://steadyweb.steady-sun.com/api/v1/forecast/pvsystem

import pandas as pd
import requests

headers = {'Authorization':'Token {your token}'}

plant_uuid = "replace-this-with-uuid" # Fill in the plant's UUID
url = f"https://steadyweb.steady-sun.com/api/v1/forecast/pvsystem/{plant_uuid}"

parameters = {'time_step':60, 'horizon':2880}
api_data = requests.get(url=url,params=parameters,headers=headers).json()

forecast = pd.DataFrame(
data=api_data['data'],
index=api_data['index'],
columns=api_data['columns'],
)
print(forecast)

Language

Python

GET Forecasts for GROUP

Similar to retrieving a PV System forecast, to get the forecast of a whole group, extend the endpoint URL by using the specific Group's UUID (retrieved via a GET request). The API takes in several additional parameters that the user can tune to modify the retrieved forecasts. The available parameters are described in the Parameters section.

API endpoint https://steadyweb.steady-sun.com/api/v1/forecast/group

import pandas as pd
import requests

headers = {'Authorization':'Token {your token}'}

group_uuid = "replace-this-with-uuid" # Fill in the group's UUID
url = f"https://steadyweb.steady-sun.com/api/v1/forecast/group/{group_uuid}"

parameters = {'time_step':60, 'horizon':2880}
api_data = requests.get(url=url,params=parameters,headers=headers).json()

forecast = pd.DataFrame(
data=api_data['data'],
index=api_data['index'],
columns=api_data['columns'],
)
print(forecast)

Language

Python

POST Data for PV System

This POST method is used to push the measures data for a specific PV system or group.
Push measures with the API is very straightforward.

There are different parameters to adapt your data into our format:

Parameters

Data Type

Description

data_format

String (str)

columns(default):format type “records”
split: Json with keys “index”, ”columns” and “data”
index
tight:

date_time_format

String (str)

default is "%Y-%m-%d%H:%M:%S"
you can retrieve date_time format here

timezone

String (str)

You can specify your data Timezone (not use abbreviation, just use database name)
If you don’t pass this parameter, we assumed that they are in UTC .Your data will be saved in UTC

field_format

String (str)

short_name or long_name, short_name by default
see all fields here

To push your measures data for PV system, you must make a POST request to the following URL:

API endpoint https://steadyweb.steady-sun.com/api/v1/measures

import requests
import json

uuid = 'your_uuid'
token = 'your_token'

measures_to_send = [
  {
      "datetime": "2022-12-02T13:00",
      "power_ac": 3655500.5,
      "all_sky_global_horizontal_irradiance": 121.21,
      "all_sky_diffuse_horizontal_irradiance": 42.23,
      "all_sky_beam_normal_irradiance": 464.41,
      "2m_temperature": 2.07,
      "10m_wind_speed": 4.9
},
  {
   "datetime": "2022-12-02T14:00",
   "power_ac":891005.94,
   "all_sky_global_horizontal_irradiance": 31.25,
   "all_sky_diffuse_horizontal_irradiance": 17.6,
   "all_sky_beam_normal_irradiance": 130.74,
   "2m_temperature": 1.97,
   "10m_wind_speed": 4.73
  }
]

headers = {'Authorization': f'Token {token}'}

url = f'https://steadyweb.steady-sun.com/api/v1/measures/{uuid}'

parameters = {
  "field_format": "long_name",
  "timezone": "Europe/Paris",
  "data_format":"columns",
  "date_time_format":"%Y-%m-%dT%H:%M",
  }

result = requests.post(url, headers=headers, params=parameters, data=measures_to_send)

print(json.loads(result.text))

Language

Python

POST Data for one GROUP

To push your measures data for Group, you must make a POST request to the following URL:

API endpoint https://steadyweb.steady-sun.com/api/v1/group_measures

import requests
import json

uuid = 'your_uuid'          # Fill in the group's UUID
token = 'your_token'

measures_to_send = [
  {
      "datetime": "2022-12-02T13:00",
      "power_ac": 3655500.5,
      "all_sky_global_horizontal_irradiance": 121.21,
      "all_sky_diffuse_horizontal_irradiance": 42.23,
      "all_sky_beam_normal_irradiance": 464.41,
      "2m_temperature": 2.07,
      "10m_wind_speed": 4.9
},
  {
   "datetime": "2022-12-02T14:00",
   "power_ac":891005.94,
   "all_sky_global_horizontal_irradiance": 31.25,
   "all_sky_diffuse_horizontal_irradiance": 17.6,
   "all_sky_beam_normal_irradiance": 130.74,
   "2m_temperature": 1.97,
   "10m_wind_speed": 4.73
  }
]

headers = {'Authorization': f'Token {token}'}

url = f'https://steadyweb.steady-sun.com/api/v1/group_measures/{uuid}'

parameters = {
  "field_format": "long_name",
  "timezone": "Europe/Paris",
  "data_format":"columns",
  "date_time_format":"%Y-%m-%dT%H:%M",
  }

result = requests.post(url, headers=headers, params=parameters, data=measures_to_send)

print(json.loads(result.text))

Language

Python

Forecasts Parameters

There are different parameters to customize your query:

The timezone is UTC by default.

Parameters

Data Type

Description

data_format

String (str)

split (default): original format of the api
records: fully detailed record with name of field and value for each time step
tight: tight version of the data that can be used for data visualization

precision

Integer (int)

default = 2

horizon

Integer (int)

xx min

depend on your contract

fields

String (str)

the variables available in the call API depend on your contract.
you can specify the list of fields separated by a ',' for example: t2m,ghi

time_step

String (str)

default is 60min
available values : 1,5,10,15,30,60

date_time_format

String (str)

default is in ISO 8601 UTC format, like "2022-01-01T00:00:00Z"
you can specify "time_stamp" to get unix time stamp

time_stamp_unit

String (str)

to be specified only if the unix time stamp format is requested
default is "s" for get unix time stamp in seconds,
but you can specify "ms" to get your data in milliseconds

Responses

Result

StatusCode

Content

Success

200 OK

In case of a GET or PATCH request: The request was completed successfully.

Success

201 OK

Specific to a POST request: The request was completed successfully and an object was created.

Error

400 Bad Request

Something is wrong with the request format or the request content.
Response body will contain a specific error message.

Error

401 Unauthorized

This status code means you haven’t yet authenticated against the API.
The API doesn’t know who you are and it won’t serve you.

Error

403 Forbidden

The forbidden status indicates that you don’t have permission to request that URL.
You’re authenticated, but the user or role you’re authenticated for isn’t permitted to make the API request.

Failed

500 Internal Server Error

Something unexpected went wrong during the request.

Please contact STEADYSUN if this continues, and include any error messages received from the failed request

Failed

502 Bad Gateway Error

Something unexpected went wrong during the request, probably due a server timeout. Try again after 30 seconds.

Please contact STEADYSUN if this continues, and include any error messages received from the failed request

Responses Body

The result is a JSON array including all the forecast variables for each time step. Here’s an example. The JSON format depends on your settings.

All fields

Datasheet:

Once connected to the Steadysun API, you will find on this URL, all the possible variables proposed by Steadysun :

Main API url https://steadyweb.steady-sun.com/api/allfields

Category

Short Name

Long Name

Description

Unity

Production

pac

power_ac

Solar production of the plant in the output of the inverter

watt (W)

Radiation

ghi

all_sky_global_horizontal_irradiance

Global horizontal irradiance when the cloud cover is taken into account.

W.m-2

bni

all_sky_beam_normal_irradiance

Beam normal irradiance when the cloud cover is taken into account.

W.m-2

dhi

all_sky_diffuse_horizontal_irradiance

Diffuse horizontal irradiance when the cloud cover is taken into account.

W.m-2

bhi

all_sky_beam_horizontal_irradiance

Beam horizontal irradiance when the cloud cover is taken into account..

W.m-2

Clouds

hcc

high_cloud_cover

Proportion, ranging from 0 to 1, of the cloud cover produced by high altitude clouds.

[0-1]

lcc

low_cloud_cover

Proportion, ranging from 0 to 1, of the cloud cover produced by high altitude clouds.

[0-1]

mcc

medium_cloud_cover

Proportion, ranging from 0 to 1, of the cloud cover produced by medium altitude clouds. .

[0-1]

tcc

total_cloud_cover

Proportion of cloud cover ranging from 0 to 1.

[0-1]

Humidity

specific_humidity

Concentration (in g per kg) of water in the air at 2 meter height. This variable give information about the air humidity near the ground or sea surface.

g.kg

rh2m

2m_relative_humidity

Relative humidity meters above the ground.

tcwv

total_column_water_vapor

The total amount of water vapor in a vertical column of air.

kg.m-2

Precipitation

mtpr

mean_total_precipitation_rate

Precipitation rate in mm/h over your period of time considered. For example if your time step is 5min and the value is 12mm/h, the forecast estimate that 1mm of water will precipitate in these 5 minutes

mm.h-1

Pressure & Density

mlsp

mean_sea_level_pressure

Pressure in hPa calculated back to the sea level.

hPa

msp

mean_surface_pressure

hPa

Temperature

heat_index

The heat index provides information on human's perception of temperature above 27°C. The heat index takes into account the humidity of the air which impacts the ability of the body to regulate its temperature by evaporation of sweat.
No unit.

null

t2m

2m_temperature

Air temperature 2 meters above the ground.

°C

2m_dewpoint

Dewpoint at 2 meter height. The dewpoint is the temperature to which the air mass should be cooled to become saturated in water vapor. When compared to the air temperature at the same height, the dewpoint give information about the air humidity.

°C

apparent_temperature

The apparent temperature provides information on human's perception of the temperature. It is based on wind speed and relative humidity. If the temperature is above 26°C, the heat index is provided. If the temperature is below 10°C and the wind speed exceeds 1.4 m/s, the wind chill is computed. Otherwise, the temperature is returned
No unit.

null

wind

10m_gust

10m_wind_gust

Wind gust at 10m above ground

m.s-1

10m_wind_direction

Direction from which the wind blow at 10m above ground. (North = 0°, East= 90°, South = 180°, West= 270°)

10m_wind_speed

Average wind speed at 10m above ground.

m.s-1