PV_Live
A Python implementation of the PV_Live web API. See https://www.solar.sheffield.ac.uk/pvlive/
Latest Version: 0.12
New! Updated 2022-07-19 to use the v4 PV_Live API.
About this repository
-
This Python library provides a convenient interface for the PV_Live web API to facilitate accessing PV_Live results in Python code.
-
Developed and tested with Python 3.8, should work with Python 3.5+. Support for Python 2.7+ has been discontinued as of 2021-01-15.
How do I get set up?
-
Make sure you have Git installed - Download Git
-
Run
pip install git+https://github.com/SheffieldSolar/PV_Live-API
Usage
There are three methods for extracting raw data from the PV_Live API:
|Method|Description|Docs Link|
|------|-----------|---------|
|PVLive.latest(entity_type="pes", entity_id=0, extra_fields="", period=30, dataframe=False)|Get the latest PV_Live generation result from the API.|🔗|
|PVLive.at_time(dt, entity_type="pes", entity_id=0, extra_fields="", period=30, dataframe=False)|Get the PV_Live generation result for a given time from the API.|🔗|
|PVLive.between(start, end, entity_type="pes", entity_id=0, extra_fields="", period=30, dataframe=False)|Get the PV_Live generation result for a given time interval from the API.|🔗|
There are two methods for extracting derived statistics:
|Method|Description|Docs Link|
|------|-----------|---------|
|PVLive.day_peak(d, entity_type="pes", entity_id=0, extra_fields="", period=30, dataframe=False)|Get the peak PV_Live generation result for a given day from the API.|🔗|
|PVLive.day_energy(d, entity_type="pes", entity_id=0)|Get the cumulative PV generation for a given day from the API.|🔗|
These methods include the following optional parameters:
|Parameter|Usage|
|---------|-----|
|entity_type|Choose between "pes" or "gsp". If querying for national data, this parameter can be set to either value (or left to it's default value) since setting entity_id to 0 will always return national data.|
|entity_id|Set entity_id=0 (the default value) to return nationally aggregated data. If entity_type="pes", specify a pes_id to retrieve data for, else if entity_id="gsp", specify a gsp_id. For a full list of GSP and PES IDs, refer to the lookup table hosted on National Grid ESO's data portal here.|
|extra_fields|Use this to extract additional fields from the API such as installedcapacity_mwp. For a full list of available fields, see the PV_Live API Docs.|
|period|Set the desired temporal resolution (in minutes) for PV outturn estimates. Options are 30 (default) or 5.|
|dataframe|Set dataframe=True and the results will be returned as a Pandas DataFrame object which is generally much easier to work with. The columns of the DataFrame will be pes_id or gsp_id, datetime_gmt, generation_mw, plus any extra fields specified.|
Code Examples
See pvlive_api_demo.py for more example usage.
The examples below assume you have imported the PVLive class and created a local instance called pvl:
from datetime import datetime
import pytz
from pvlive_api import PVLive
pvl = PVLive()
|Example|Code|Example Output|
|-------|----|------|
|Get the latest nationally aggregated GB PV outturn|pvl.latest()|(0, '2021-01-20T11:00:00Z', 203.0)|
|Get the latest aggregated outturn for PES region 23 (Yorkshire)|pvl.latest(entity_id=23)|(23, '2021-01-20T14:00:00Z', 5.8833031)
|Get the latest aggregated outturn for GSP ID 120 (INDQ1 or "Indian Queens")|pvl.latest(entity_type="gsp", entity_id=120)|(120, '2021-01-20T14:00:00Z', 1, 3.05604)
|Get the nationally aggregated GB PV outturn for all of 2020 as a DataFrame|pvl.between(start=datetime(2020, 1, 1, 0, 30, tzinfo=pytz.utc), end=datetime(2021, 1, 1, tzinfo=pytz.utc), dataframe=True)||
|Get a list of GSP IDs|pvl.gsp_ids|array([ 0, 1, 2, 3, ..., 336, 337, 338])|
|Get a list of PES IDs|pvl.pes_ids|array([ 0, 1, 2, 3, ..., 336, 337, 338])|
To download data for all GSPs, use something like:
def download_pvlive_by_gsp(start, end, include_national=True, extra_fields=""):
data = None
pvl = PVLive()
min_gsp_id = 0 if include_national else 1
for gsp_id in pvl.gsp_ids:
if gsp_id < min_gsp_id:
continue
data_ = pvl.between(start=start, end=end, entity_type="gsp", entity_id=gsp_id,
dataframe=True, extra_fields=extra_fields)
if data is None:
data = data_
else:
data = pd.concat((data, data_), ignore_index=True)
return data
Command Line Utilities
pv_live
This utility can be used to download data to a CSV file:
>> pv_live -h
usage: pvlive.py [-h] [-s "<yyyy-mm-dd HH:MM:SS>"] [-e "<yyyy-mm-dd HH:MM:SS>"] [--entity_type <entity_type>] [--entity_id <entity_id>]
[--period <5|30>] [-q] [-o </path/to/output/file>]
This is a command line interface (CLI) for the PV_Live API module
optional arguments:
-h, --help show this help message and exit
-s "<yyyy-mm-dd HH:MM:SS>", --start "<yyyy-mm-dd HH:MM:SS>"
Specify a UTC start date in 'yyyy-mm-dd HH:MM:SS' format (inclusive), default behaviour is to retrieve the latest outturn.
-e "<yyyy-mm-dd HH:MM:SS>", --end "<yyyy-mm-dd HH:MM:SS>"
Specify a UTC end date in 'yyyy-mm-dd HH:MM:SS' format (inclusive), default behaviour is to retrieve the latest outturn.
--entity_type <entity_type>
Specify an entity type, either 'gsp' or 'pes'. Default is 'pes'.
--entity_id <entity_id>
Specify an entity ID, default is 0 (i.e. national).
--period <5|30> Desired temporal resolution (in minutes) for PV outturn estimates. Default is 30.
-q, --quiet Specify to not print anything to stdout.
-o </path/to/output/file>, --outfile </path/to/output/file>
Specify a CSV file to write results to.
Jamie Taylor, 2018-06-04
Using the Docker Image
There is also a Docker Image hosted on Docker Hub which can be used to download data from the PV_Live API with minimal setup:
>> docker run -it --rm sheffieldsolar/pv_live-api:<release> pv_live -h
Documentation
How do I upgrade?
Sheffield Solar will endeavour to update this library in sync with the PV_Live API and ensure the latest version of this library always supports the latest version of the PV_Live API, but cannot guarantee this. To make sure you are forewarned of upcoming changes to the API, you should email solar@sheffield.ac.uk and request to be added to the PV_Live user mailing list.
To upgrade the code:
- Run
pip install --upgrade git+https://github.com/SheffieldSolar/PV_Live-API
Who do I talk to?
- Jamie Taylor - jamie.taylor@sheffield.ac.uk - SheffieldSolar
Authors
-
Jamie Taylor - SheffieldSolar
-
Ethan Jones - SheffieldSolar
License
No license is defined yet - use at your own risk.
Metadata
Release files for pvlive-api 0.12
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pvlive_api-0.12.tar.gz | 14.4 kB | Without provenance | Details for pvlive_api-0.12.tar.gz |
Release files / pvlive_api-0.12.tar.gz
| Download URL | pvlive_api-0.12.tar.gz |
|---|---|
| Size | 14.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8122fdf18fa33e626c27179874754736a7ed85c45218763d202b151c883cf1b7
|
|
BLAKE2b-256 checksum How to use checksums |
a3ca05eaaa4ff741f34c2ac39cca42c60e39e2d46e9c5b6d377144589f921400
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.9.12
|
Security for pvlive-api 0.12
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.