data_tools.query.SolcastClient#

class data_tools.query.SolcastClient(api_key: str = None)#

Bases: object

Represents high-level access to the Solcast Radiation and Weather API

__init__(api_key: str = None)#

Instantiate a client for access to the Solcast API.

Requires an API key to the Solcast Toolkit. SolcastClient will try to use environment variable SOLCAST_API_KEY if not provided as an argument.

Parameters:: api_key (str) – A string containing a valid Solcast API key.

Methods

`__init__`([api_key])	Instantiate a client for access to the Solcast API.
`query`(latitude, longitude, period, ...[, ...])	Make a query to the Solcast Radiation and Weather API for a specific coordinate and time range

query(latitude: float, longitude: float, period: SolcastPeriod, output_parameters: list[SolcastOutput], tilt: float, start_time: datetime | timedelta, end_time: datetime | timedelta, azimuth: float = 0, return_dataframe: bool = False, return_datetime: bool = False) → tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ...] | DataFrame#

Make a query to the Solcast Radiation and Weather API for a specific coordinate and time range

Solcast query time ranges are expanded to fit hour boundaries, so a query between 6:13AM and 8:27AM will be actually result in a query with forecasts for 6:00AM to 9:00AM. Additionally, if the weather averaging period is less than an hour, for example five minutes, the elements will go like 6:00AM, 6:05AM, 6:10AM, and such, instead of incrementing from 6:13AM.

The query will return a tuple of one-dimensional ndarray`s where each `ndarray has length N where N is the number of weather averaging periods contained within the hours encompassed by start_time and end_time.

For example, if a query is between 6:13AM and 10:45AM with a weather averaging period of 10 minutes, there will be (5 hours) * (6 forecasts per hour) = 30 elements, as the query will be between 6:00AM and 11:00AM.

The first ndarray contains POSIX timestamps where the “i”th element describes the end of the forecast window described by the “i”th element of each of the data `ndarray`s.

All ndarray`s after the first are data, and are returned in the order that they were requested in `output_parameters. Each datapoint of a data ndarray describes that data type for the forecast window.

For example,

>>> time, ghi = SolcastClient().query(output_parameters=[SolcastOutput.ghi], period=SolcastPeriod.PT10M, ...)

And then if time[5] = 9:10AM, then ghi[5] represents the GHI between 9:00AM and 9:10AM.

Probabilistic data like ghi10 and dti90 are only available for the future and present. If you request these outputs, any times in the past will be NaN such that np.isnan() is True for those times.

If return_dataframe is True, a Pandas DataFrame will be returned containing the query. If return_datetime is True, the time x-axis will contain datetime objects localized to UTC instead of POSIX timestamps.

Parameters:

latitude – The latitude of the queried coordinate.
longitude – The longitude of the queried coordinate.
period – The weather forecast averaging period.
output_parameters – A list of the output parameters that should be queried
tilt – The tilt angle 0–90 in degrees of the solar collector from the horizontal where 90 is vertical.
start_time – The time at which weather forecasts should begin. It must be in the past and no greater than 7 days in the past. It must be timezone-aware. Use None to denote the current time to ensure expected behaviour.
end_time – The time at which weather forecasts should end. It must be in the future and no greater than 14 days in the future. It must be after start_time. It must be timezone-aware. Use None to denote the current time to ensure expected behaviour.
return_dataframe – Return a Pandas DataFrame instead of tuple of `ndarray`s.
return_datetime (bool) – Return datetime objects instead of UNIX timestamps in the time x-axis.
azimuth – The azimuth (-180–180, compass direction) in degrees, in which the arrays are tilted where 0 is true north. Default is 0.