PV_Live Public API v0 User Guide

PV_Live

This API (v0) is deprecated and superseded by v1.

See PV_Live_API_v1 user guide.

This API (v0) will be decommissioned on 23rd May 2018.

Contents

Introduction

PVNowcast

Example Response

Historic PV_Live

Example Response:

Region Definitions

Region Shape Definitions

Example Response:

Substation Definitions:

Example Response:

Querying the API

Web Browser

Command line

Python

pvlive.py

Introduction

The PV-Live web API (Application Programming Interface) provides access to the near-real-time estimate of aggregated solar PV generation across the GB electricity transmission network. It returns a computer friendly (JSON) response for use in software, websites, apps etc. The “PV_Live API” consists of a set of URLs that fetch PV_Live results from Sheffield Solar (SS) servers.

Warning: The PV-Live API is under active development.We may change: base-url, end-points, authentication, response format etc.

PVNowcast

Real-time API, provides the latest half-hourly national PV generation outturn estimate.

url: https://www.solar.sheffield.ac.uk/ssfdb3/crud/nationalgrid/pvnowcast/0

username: pvlive

password: (empty)

Example Response

Example of JSON produced when querying the PVNowcast

{

"Substation_id":"0",

"timestamp_GMT":"2016-05-17 13:15:10",

"datetime_GMT":"2016-05-17 13:00:00",

"generation_MW":"4410",

"uncertainty_MW":null,

"Stats_error":"44",

"Bias_error":null,

"lcl_MW":"4230",

"ucl_MW":"4590",

"Version_id":"46",

"capacity_MWp":"10340",

"installedcapacity_MWp":"10500",

"Site_count":"311",

"Calculation_time_s":"8"

}

Where:

to acquire the input data and run the calculation. Results are sometimes recalculated after the initial LIVE calculation.

timestamp.

generation is between LCL and UCL (Mega-Watts).

generation is between LCL and UCL (Mega-Watts).

sources and methodology.

differs from the “installed” capacity because we have incorporated some performance degradation.

according to National Grid data.

acquire the input data.

Historic PV_Live

Provide historic PV_Live results for a given region and time period. It can be used to access results for individual regions or national data.

url:https://www.solar.sheffield.ac.uk/ssfdb3/sql/call%20get_pv_generation(<region_id>,%22<start_datetime>%22,%22<end_datetime>%22)

username: pvlive

password: (None)

Parameter name

Data type

Format

region_id

Int

NA

start_datetime

String

ISO8601

yyyy-mm-ddTHH:MM:SS (GMT)

end_datetime

String

ISO8601

yyyy-mm-ddTHH:MM:SS (GMT)

The region id represents each of the 327 GSP’s which are modelled. A region_id of -1 will return results for all regions, however, this can be quite slow so it is instead advised that all regions are accessed individually.

To access national out-turn estimates, use a region id of 0. This may not necessarily be equal to the sum of all of the individual regions as the methodologies used to calculate the two are entirely independent.

Example Response:

url:https://www.solar.sheffield.ac.uk/ssfdb3/sql/call%20pv_generation(1,%222018-03-25T23:00%22,%222018-03-29T10:18%22) 

[
{
"meta":[
        
{"type":3,"catalog":"def","database":"nationalgrid","table":"pvgeneration","org_table":"pvgeneration","column":"region_id","org_column":"substation_id","charset":63,"length":11,"flags":20515,"decimals":0},

        ...


],
"data":[ 
        
["1","2018-03-26 03:00:00","0",null,null,null,null,null,"64","0.4.7","115.53953","112.05123","779","29"],

      ...


        
["1","2018-03-27 21:00:00","0",null,null,null,null,null,"64","0.4.7","115.53953","112.0487","772","22"]

],
"status":[{"server_status":42,"warning_count":0}]
},
{"server_status":34,"warning_count":0,"affected_rows":0,"last_insert_id":0}
]

The fields in the response are:

generation is between LCL and UCL (Mega-Watts)

generation is between LCL and UCL (Mega-Watts).

estimated performance degradation (Megawatt-peak).

Region Definitions

The regions are defined by the nearest neighbour region corresponding to each transmission system grid supply point (GSP), of which there are 327[1]. The Well Known Text (WKT) definition of these regions can be accessed as well as the locations of the individual GSP’s.

Region Shape Definitions

Provide region outline definitions using WKT MultiPolygons with WGS84 World Mercator projection.

url:https://www.solar.sheffield.ac.uk/ssfdb3/sql/nationalgrid/call%20get_region_definitions()

username: pvlive

password: (None)

Example Response:

[
{
"meta":[
        
{"type":3,"catalog":"def","database":"nationalgrid","table":"substation_regions","org_table":"substation_regions","column":"region_id","org_column":"group_id","charset":63,"length":10,"flags":20519,"decimals":0},
        
{"type":251,"catalog":"def","database":"","table":"","org_table":"","column":"WKT","org_column":"","charset":33,"length":50331648,"flags":0,"decimals":31}
],
"data":[ 
        
["1","MULTIPOLYGON(((-1.979191693549882 50.66657571239672,-1.979177551804063 50.66655772439479,"

...

"-1.051625356184888 51.12668566101031)))"]
],
"status":[{"server_status":42,"warning_count":0}]
},
{"server_status":34,"warning_count":0,"affected_rows":0,"last_insert_id":0}
]

Substation Definitions:

Returns the locations of the individual GSP’s. Mapped with as WGS84 World Mercator Projection.

url:https://www.solar.sheffield.ac.uk/ssfdb3/sql/nationalgrid/call%20get_substations_WGS84WebMerc()

username: pvlive

password: (None)

Example Response:

{
"meta":[
        
{"type":3,"catalog":"def","database":"nationalgrid","table":"substation_WGS84WebMerc_20170904","org_table":"substation_WGS84WebMerc_20170904","column":"id","org_column":"id","charset":63,"length":10,"flags":16935,"decimals":0},
        
{"type":253,"catalog":"def","database":"nationalgrid","table":"substation_WGS84WebMerc_20170904","org_table":"substation_WGS84WebMerc_20170904","column":"sitename","org_column":"sitename","charset":33,"length":78,"flags":20485,"decimals":0},

…]

"data":[ 
        
["1","Abham","ABHA","6528261.853","-415196.0972"],
        
["2","Abernethy","ABNE","7626297.503","-366693.0818"],
        
["3","Aberthaw","ABTH","6690188.786","-378706.6813"],
        
["4","Aldwarke","ALDW","7065781.831","-146833.7479"],
        
["5","Alness","ALNE","7906103.041","-475968.7468"],
        
["6","Alverdiscott","ALVE","6622245.438","-460343.9431"],
        
["7","Amersham","AMEM","6739717.321","-72888.66299"],
        
["8","Arbroath","ARBR","7671507.139","-291285.2588"],
        
["9","Ardmore","ARMO","7874305.534","-739721.6899"],
        
["10","Axminster","AXMI","6583515.979","-325428.0598"],

           …

       ["327","Wymondley","WYMO","6786886.32","-27679.59139"]

],

"status":[{"server_status":42,"warning_count":0}]
},
{"server_status":34,"warning_count":0,"affected_rows":0,"last_insert_id":0}
]

Querying the API

You can query the PV Live API using:

  1. Web browser: Chrome, Firefox, Internet Explorer etc.
  2. Command line: curl, wget etc.
  3. Python
  4. Most other programming languages

The API responds with a JSON encoded dataset.

Below, there are some examples of different methods of querying the API.

Web Browser

Visit: https://www.solar.sheffield.ac.uk/ssfdb3/crud/nationalgrid/pvnowcast/0

username: pvlive

password: (None. So leave this empty)

Command line

$ curl --user pvlive: --url https://www.solar.sheffield.ac.uk/ssfdb3/crud/nationalgrid/pvnowcast/0

$ wget -qO- --password=  --user=pvlive https://www.solar.sheffield.ac.uk/ssfdb3/crud/nationalgrid/pvnowcast/0

$ curl --user pvlive: --url "https://www.solar.sheffield.ac.uk/ssfdb3/sql/nationalgrid/call%20get_region_definitions()"

$ wget -qO- --password=  --user=pvlive

"https://www.solar.sheffield.ac.uk/ssfdb3/sql/nationalgrid/call%20get_region_definitions()"

(Note both of these provide a username and empty password.)

Python

The demo script below, pvlive.py, shows how the API can be queried in Python.

pvlive.py

#!/usr/bin/python3

import requests

class Querier(object):

    def __init__(self, url_base, username, password):

        self.url_base=url_base

        self.username=username

        self.password=password

    def query(self, substation_id):

        return requests.get(self.url_base + str(substation_id),

                            auth=requests.auth.HTTPBasicAuth(self.username,

                                                             self.password))

if __name__ == '__main__':

    url_base='https://www.solar.sheffield.ac.uk/ssfdb3/crud/' \

             'nationalgrid/pvnowcast/'

    username='pvlive'

    password=''     #2 single quotes i.e. empty string

    querier = Querier(url_base, username, password)

    substation_id=0

    response = querier.query(substation_id)

    print(response.text)


Updated: Wed May 23 2018 23:03:04 GMT+0100 (BST)


[1] As of 2018-03-29