Modules

pvforecast_api

A Python interface for the PV_Forecast web API from Sheffield Solar.

class pvforecast_api.pvforecast.PVForecast(user_id, api_key, retries=3)[source]

Bases: object

Interface with the PV_Forecast web API.

Parameters
`user_id`string

A valid User ID for the PV_Forecast API.

`api_key`string

A valid API Key for the PV_Forecast API (must correspond to the given user_id).

`retries`int

Optionally specify the number of retries to use should the API respond with anything other than status code 200. Exponential back-off applies inbetween retries.

Notes

To obtain a User ID and API key, please visit the PV_Forecast API website.

Methods

get_forecast([forecast_base_gmt, …])

Get the PV_Forecast with a given forecast base from the API.

get_forecast_bases(start, end[, forecast_type])

Get a list of the forecast base times available on the API between two datetimes.

get_forecasts(start, end[, …])

Get multiple PV_Forecasts during a given time interval from the API.

latest([entity_type, entity_id, …])

Get the latest PV_Forecast from the API.
get_forecast(forecast_base_gmt: Optional[datetime.datetime] = None, entity_type: str = 'gsp', entity_id: int = 0, extra_fields: str = '', dataframe: bool = False) → Union[List, pandas.core.frame.DataFrame][source]

Get the PV_Forecast with a given forecast base from the API.

Parameters
`forecast_base_gmt`datetime

A timezone-aware datetime object.

`entity_type`string

The aggregation entity type of interest, either “pes” or “gsp”. Defaults to “gsp”.

`entity_id`int

The numerical ID of the entity of interest. Defaults to 0 (national).

`extra_fields`string

Comma-separated string listing any extra fields.

`dataframe`boolean

Set to True to return data as a Pandas DataFrame. Default is False, i.e. return a list.

Returns
list

Each element of the outter list is a list containing the pes_id or gsp_id, forecast_base_gmt, datetime_gmt and generation_mw fields of a PV_Forecast, plus any extra_fields in the order specified.

OR
Pandas DataFrame

Contains the columns pes_id or gsp_id, forecast_base_gmt, datetime_gmt and generation_mw, plus any extra_fields in the order specified.

Notes

For list of optional extra_fields, see PV_Forecast API Docs.

get_forecast_bases(start: datetime.datetime, end: datetime.datetime, forecast_type: str = 'national') → List[str][source]

Get a list of the forecast base times available on the API between two datetimes.

Parameters
`start`datetime

A timezone-aware datetime object.

`end`datetime

A timezone-aware datetime object.

`forecast_type`str

Either ‘national’ or ‘regional’.

Returns
list

A list of valid forecast base times as strings.

get_forecasts(start: datetime.datetime, end: datetime.datetime, forecast_base_times: List[str] = [], entity_type: str = 'gsp', entity_id: int = 0, extra_fields: str = '', dataframe: bool = False) → Union[List, pandas.core.frame.DataFrame][source]

Get multiple PV_Forecasts during a given time interval from the API.

Parameters
`start`datetime

A timezone-aware datetime object.

`end`datetime

A timezone-aware datetime object.

`forecast_base_times`list

Optionally provide a list of forecast base times of interest (e.g. [“07:00”, “10:00”]). The default behaviour (an empty list) is to download all forecast base times.

`entity_type`string

The aggregation entity type of interest, either “pes” or “gsp”. Defaults to “gsp”.

`entity_id`int

The numerical ID of the entity of interest. Defaults to 0 (national).

`extra_fields`string

Comma-separated string listing any extra fields.

`dataframe`boolean

Set to True to return data as a Pandas DataFrame. Default is False, i.e. return a list.

Returns
list

Each element of the outter list is a list containing the pes_id or gsp_id, forecast_base_gmt, datetime_gmt and generation_mw fields of a PV_Forecast, plus any extra_fields in the order specified.

OR
Pandas DataFrame

Contains the columns pes_id or gsp_id, forecast_base_gmt, datetime_gmt and generation_mw, plus any extra_fields in the order specified.

Notes

For list of optional extra_fields, see PV_Forecast API Docs.

latest(entity_type: str = 'gsp', entity_id: int = 0, extra_fields: str = '', dataframe: bool = False) → Union[List, pandas.core.frame.DataFrame][source]

Get the latest PV_Forecast from the API.

Parameters
`entity_type`string

The aggregation entity type of interest, either “pes” or “gsp”. Defaults to “gsp”.

`entity_id`int

The numerical ID of the entity of interest. Defaults to 0 (national).

`extra_fields`string

Comma-separated string listing any extra fields.

`dataframe`boolean

Set to True to return data as a Pandas DataFrame. Default is False, i.e. return a list.

Returns
list

Each element of the outter list is a list containing the pes_id or gsp_id, forecast_base_gmt, datetime_gmt and generation_mw fields of a PV_Forecast, plus any extra_fields in the order specified.

OR
Pandas DataFrame

Contains the columns pes_id or gsp_id, forecast_base_gmt, datetime_gmt and generation_mw, plus any extra_fields in the order specified.

Notes

For list of optional extra_fields, see PV_Forecast API Docs.

exception pvforecast_api.pvforecast.PVForecastException(msg)[source]

Bases: Exception

An Exception specific to the PVForecast class.

pvforecast_api.pvforecast.main()[source]

Placeholder for CLI to be added in future release.