Modules

pvlive_api

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

class pvlive_api.pvlive.PVLive(retries: int = 3, proxies: Optional[Dict] = None, ssl_verify: bool = True)[source]

Bases: object

Interface with the PV_Live web API.

Parameters:

  • 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.

  • proxies (Optional[Dict]) – Optionally specify a Dict of proxies for http and https requests in the format: {“http”: “<address>”, “https”: “<address>”}

Methods

at_time(dt[, entity_type, entity_id, ...])

Get the PV_Live generation result for a given time from the API.

between(start, end[, entity_type, ...])

Get the PV_Live generation result for a given time interval from the API.

day_energy(d[, entity_type, entity_id])

Get the cumulative PV generation for a given day from the API.

day_peak(d[, entity_type, entity_id, ...])

Get the peak PV_Live generation result for a given day from the API.

deployment([region, include_history, ...])

Download deployment data from the /capacity endpoint.

latest([entity_type, entity_id, ...])

Get the latest PV_Live generation result from the API.
at_time(dt: datetime, entity_type: Literal['gsp', 'pes'] = 'gsp', entity_id: int = 0, extra_fields: str = '', period: int = 30, dataframe: bool = False) → Union[Tuple, DataFrame][source]

Get the PV_Live generation result for a given time from the API.

Parameters:

  • dt (datetime) – A timezone-aware datetime object. Will be corrected to the END of the half hour in which dt falls, since Sheffield Solar use end of interval as convention.

  • 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.

  • extra_fields (string) – Comma-separated string listing any extra fields.

  • period (int) – Time-resolution to retrieve, either 30 or 5 (minutely). Default is 30.

  • dataframe (boolean) – Set to True to return data as a Python DataFrame. Default is False, i.e. return a tuple.

Returns:

  • tuple – Tuple containing the pes_id, datetime_gmt and generation_mw fields of the PV_Live result, plus any extra_fields in the order specified.

  • OR

  • Pandas DataFrame – Contains the columns pes_id, datetime_gmt and generation_mw, plus any extra_fields in the order specified.

Notes

For list of optional extra_fields, see PV_Live API Docs.

between(start: datetime, end: datetime, entity_type: Literal['gsp', 'pes'] = 'gsp', entity_id: int = 0, extra_fields: str = '', period: int = 30, dataframe: bool = False) → Union[List, DataFrame][source]

Get the PV_Live generation result for a given time interval from the API.

Parameters:

  • start (datetime) – A timezone-aware datetime object. Will be corrected to the END of the half hour in which start falls, since Sheffield Solar use end of interval as convention.

  • end (datetime) – A timezone-aware datetime object. Will be corrected to the END of the half hour in which end falls, since Sheffield Solar use end of interval as convention.

  • 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.

  • extra_fields (string) – Comma-separated string listing any extra fields.

  • period (int) – Time-resolution to retrieve, either 30 or 5 (minutely). Default is 30.

  • dataframe (boolean) – Set to True to return data as a Python DataFrame. Default is False, i.e. return a tuple.

Returns:

  • list – Each element of the outter list is a list containing the pes_id, datetime_gmt and generation_mw fields of a PV_Live result, plus any extra_fields in the order specified.

  • OR

  • Pandas DataFrame – Contains the columns pes_id, datetime_gmt and generation_mw, plus any extra_fields in the order specified.

Notes

For list of optional extra_fields, see PV_Live API Docs.

day_energy(d: date, entity_type: Literal['gsp', 'pes'] = 'gsp', entity_id: int = 0) → float[source]

Get the cumulative PV generation for a given day from the API.

Parameters:

  • d (date) – The day of interest as a date 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.

Returns:

  • float – The cumulative PV generation on the given day in MWh.

  • OR

  • None – If no data found, return None.

day_peak(d: date, entity_type: Literal['gsp', 'pes'] = 'gsp', entity_id: int = 0, extra_fields: str = '', period: int = 30, dataframe: bool = False) → Union[Tuple, DataFrame][source]

Get the peak PV_Live generation result for a given day from the API.

Parameters:

  • d (date) – The day of interest as a date 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.

  • extra_fields (string) – Comma-separated string listing any extra fields.

  • period (int) – Time-resolution to retrieve, either 30 or 5 (minutely). Default is 30.

  • dataframe (boolean) – Set to True to return data as a Python DataFrame. Default is False, i.e. return a tuple.

Returns:

  • tuple – Tuple containing the pes_id, datetime_gmt and generation_mw fields of the latest PV_Live result, plus any extra_fields in the order specified.

  • OR

  • Pandas DataFrame – Contains the columns pes_id, datetime_gmt and generation_mw, plus any extra_fields in the order specified.

  • OR

  • None – If no data found for the day, return None.

Notes

For list of optional extra_fields, see PV_Live API Docs.

deployment(region: Literal['gsp', 'llsoa'] = 'gsp', include_history: bool = False, by_system_size: bool = False, release: Union[str, int] = 0) → DataFrame[source]

Download deployment data from the /capacity endpoint.

Parameters:

  • region (str) – The aggregation region for the deployment data, either ‘gsp’ (default) or ‘llsoa’.

  • include_history (bool) – Set to True to include historical deployment data. Defaults to False.

  • by_system_size (bool) – If region == “gsp”, set to True to also include the breakdown by system size.

  • release (Union[str, int]) – The datestamp (YYYYMMDD) of the capacity update you wish to download. Pass a string (e.g. “20231116”) to get a specific release, or pass an int to get the latest (release=0), next-latest (release==1) etc. Defaults to 0.

Returns:

Columns vary depending on the input parameters, but shoudl include at least release, GSPs/llsoa and dc_capacity_mwp.

Return type:

Pandas DataFrame

latest(entity_type: Literal['gsp', 'pes'] = 'gsp', entity_id: int = 0, extra_fields: str = '', period: int = 30, dataframe: bool = False) → Union[Tuple, DataFrame][source]

Get the latest PV_Live generation result 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.

  • extra_fields (string) – Comma-separated string listing any extra fields.

  • period (int) – Time-resolution to retrieve, either 30 or 5 (minutely). Default is 30.

  • dataframe (boolean) – Set to True to return data as a Python DataFrame. Default is False, i.e. return a tuple.

Returns:

  • tuple – Tuple containing the pes_id, datetime_gmt and generation_mw fields of the latest PV_Live result, plus any extra_fields in the order specified.

  • OR

  • Pandas DataFrame – Contains the columns pes_id, datetime_gmt and generation_mw, plus any extra_fields in the order specified.

  • OR

  • None – If no data found, return None.

Notes

For list of optional extra_fields, see PV_Live API Docs.

exception pvlive_api.pvlive.PVLiveException(msg)[source]

Bases: Exception

An Exception specific to the PVLive class.

pvlive_api.pvlive.main()[source]

Load CLI options and access the API accordingly.

pvlive_api.pvlive.parse_options()[source]

Parse command line options.