API Specification

This section details the API specification for those who wish to implement their own client software.

Getting Started

  1. Login and goto your Settings page

  2. Select Enabled for API Access

  3. Click on New Key to generate your API key

  4. Make a note of your System Id

  5. Save your settings

Both the API key and System Id will be required to access all API services

Authentication

The following HTTP Headers need to be set to authenticate the service request.

  • X-Pvoutput-Apikey

  • X-Pvoutput-SystemId

Alternatively, the parameters key and sid may be passed as part of a GET request.

Rate Limits

The following rate limits applies per API key for all request types -

  • 60 requests per hour.

  • 300 requests per hour in Donation mode.

The following rate limits applies per API key to Get Statistic API -

  • 12 requests per hour.

  • 60 requests per hour in Donation mode.

HTTP Headers

Rate limit information can be obtained by setting the HTTP header X-Rate-Limit to 1

The HTTP response will be returned with the additional headers -

  • X-Rate-Limit-Remaining - The number of requests remaining for the hour

  • X-Rate-Limit-Limit - The total request limit for the hour

  • X-Rate-Limit-Reset - Unix time in UTC when the limit is reset

Add Output Service

The Add Output service uploads end of day output information. It allows all of the information provided on the Add Output page to be uploaded.

Service URL

1https://pvoutput.org/service/r2/addoutput.jsp

POST Method

The POST method accepts either a single CSV data parameter or multiple parameters. It is recommended to use the POST method as it does not expose the API key via the URL.

Parameters

The following parameters are used when requesting the service via GET or POST.

Parameter

Field

Required

Format

Unit

Example

d

Date

Yes

yyyymmdd

date

20210228

g

Generated

No 1

number

watt hours

3271

e

Exported

No

number

watt hours

1928

pp

Peak Power

No

number

watts

2802

pt

Peak Time

No

hh:mm

time

13:15

cd

Condition

No

text

See Conditions

tm

Min Temp

No

decimal

celsius

10.2

tx

Max Temp

No

decimal

celsius

21.2

cm

Comments

No

text

Free text

ip

Import Peak

No

number

watt hours

io

Import Off Peak

No

number

watt hours

is

Import Shoulder

No

number

watt hours

ih

Import High Shoulder

No

number

watt hours

c

Consumption

No

number

watt hours

ep

Export Peak

No

number

watt hours

eo

Export Off-Peak

No

number

watt hours

es

Export Shoulder

No

number

watt hours

eh

Export High Shoulder

No

number

watt hours

1 Required if the output does not already exist.

Conditions

The following values are valid for the condition cd parameter -

  • Fine

  • Partly Cloudy

  • Mostly Cloudy

  • Cloudy

  • Showers

  • Snow

  • Hazy

  • Fog

  • Dusty

  • Frost

  • Storm

CSV Data Parameter

The data input contains comma separated values of the output details. The fields must be passed in the order shown below.

Position

Field

Required

1

Output Date

Yes

2

Generated

No 1

3

Exported

No

4

Peak Power

No

5

Peak Time

No

6

Condition

No

7

Min Temp

No

8

Max Temp

No

9

Comments

No

10

Import Peak

No

11

Import Off Peak

No

12

Import Shoulder

No

13

Import High Shoulder

No

14

Consumption

No

15

Export Peak

No

16

Export Off-Peak

No

17

Export Shoulder

No

18

Export High Shoulder

No

1 Required if the output does not already exist.

Batching Outputs

Multiple outputs may be added or updated in a single request by separating each output with a semi-colon in the data input.

See example below -

POST Examples

Using cURL to send the minimum required data

1curl -d "data=20210830,15000" -H "X-Pvoutput-Apikey: Your-API-Key" -H "X-Pvoutput-SystemId: Your-System-Id" https://pvoutput.org/service/r2/addoutput.jsp

Using cURL to send a batch of 3 outputs

1curl -d "data=20210101,15000;20210102,14000;20210103,16000" -H "X-Pvoutput-Apikey: Your-API-Key" -H "X-Pvoutput-SystemId: Your-System-Id" https://pvoutput.org/service/r2/addoutput.jsp

Using cURL to update the comment, off peak import (300) and off peak export (200)

1curl -d "data=20210301,,,,,,,,updated comment,,300,,,,,200,," -H "X-Pvoutput-Apikey: Your-API-Key" -H "X-Pvoutput-SystemId: Your-System-Id" https://pvoutput.org/service/r2/addoutput.jsp

Using cURL to send the data values as parameters

1curl -d "d=20100830" -d "g=15000" -H "X-Pvoutput-Apikey: Your-API-Key" -H "X-Pvoutput-SystemId: Your-System-Id" https://pvoutput.org/service/r2/addoutput.jsp

Hint

Replace Your-API-Key and Your-System-Id with your key and system id

GET Examples

Using the web browser to send minimum required data

1https://pvoutput.org/service/r2/addoutput.jsp?key=Your-API-Key&sid=Your-System-Id&d=20100830&g=12000

Success Messages

The following messages will be returned upon successfully adding or updating output data.

OK 200: Added Output

  • The output data has been recieved and will either be added or updated.

Error Messages

The following service specific errors may be encountered.

For general API errors common for all services, refer to the service Common Errors section.

Bad request 400: Date [date] invalid

  • The date is incorrectly formatted, expecting yyyymmdd format

Bad request 400: Date [date] too old

  • The date must be after 2000-01-01

Bad request 400: Date [date] too new

  • The date must not be a future date

Bad request 400: Generation [export] too high for system size [size] on [date]

  • The generation amount to too high compared to the system size

Bad request 400: Export [export] too high for system size [size] on [date]

  • The export amount to too high compared to the system size

Bad request 400: Export [export] cannot exceed generation [generation] by 15%

  • The export amount is too high compared to the generation amount

Bad request 400: Consumption [consumption] too high on [date]

  • Consumption exceeded the 999999999Wh limit

Bad request 400: Peak power [power] too high for system size [size] on [date]

  • The peak power is 50% greater than the system size.

Bad request 400: Min/Max temp missing on [date]

  • Both min and max temperature must exist or both should be omitted

Restrictions and Limitations

  • Generated or consumption must be provided for a new output.

  • Generated and consumption are optional for an update.

  • If a Time of Export parameter ep, eo, es or eh is set then the existing total export value e is overwritten with the sum of all 4 time of export values.

  • Min temperature must be lower or equal to max temperature.

  • Temperature range is -100 to 100 degrees celsius.

  • Batching is only available with Donation mode enabled.

  • Maximum batch size is 100.

Donation Features

Add Status Service

The Add Status service accepts live output data at the Status Interval (5 to 15 minutes) configured for the system.

Service URL

1https://pvoutput.org/service/r2/addstatus.jsp

Parameters

This service accepts both GET or POST requests with the following parameters -

Parameter

Field

Required

Format

Unit

Example

Donation

d

Output Date

Yes

yyyymmdd

date

20210228

t

Time

Yes

hh:mm

time

14:00

v1

Energy Generation

No

number

watt hours

10000

v2

Power Generation

No

number

watts

2000

v3

Energy Consumption

No

number

watt hours

10000

v4

Power Consumption

No

number

watts

2000

v5

Temperature

No

decimal

celsius

23.4

v6

Voltage

No

decimal

volts

239.2

c1

Cumulative Flag

No

number

1

n

Net Flag

No

number

1

v7

Extended Value v7

No

number

User Defined

Yes

v8

Extended Value v8

No

number

User Defined

Yes

v9

Extended Value v9

No

number

User Defined

Yes

v10

Extended Value v10

No

number

User Defined

Yes

v11

Extended Value v11

No

number

User Defined

Yes

v12

Extended Value v12

No

number

User Defined

Yes

m1

Text Message 1

No

text

30 chars max

Yes

b1

Battery Power

No

number

watts

-200 (Discharge), 200 (Charge)

Yes

b2

Battery State of Charge

No

decimal

%

0 to 100

Yes

b3

Battery Size (Usable)

No

number

watt hours

13000

Yes

b4

Battery Lifetime Charge

No

number

watt hours

30000

Yes

b5

Battery Lifetime Discharge

No

number

watt hours

20000

Yes

b6

Battery State

No

number

0-9

See Battery State

Yes

Power and Energy Calculation

Power can energy values can be derived from one another. When a system sends only power values v2 and v4 the corresponding energy values are automatically calculated.

Similarly when only energy values v1 and v3 are sent, PVOutput will calculate the average power.

Cumulative Energy

The following values are valid for the c1 flag.

  • 1 - Both v1 and v3 values are lifetime energy values.

  • 2 - Only v1 generation is a lifetime energy value.

  • 3 - Only v3 consumption is a lifetime energy value.

Net Data

The n parameter when set to 1 will indicate that the power values passed are net export/import rather than gross generation/consumption. This option is used for devices that are unable to report gross consumption data. The provided import/export data is merged with existing generation data to derive consumption.

Only the power values v2 (export) and v4 (import) are used to process a request with Net Data. Net data can have negative values to signify the opposite direction.

The following table shows how negative and positive values are interpreted, and the resulting import/export value that will be used.

v2

v4

Export

Import

n/a

Positive or zero

0

v4

n/a

Less than zero

v4 * -1

0

Positive or zero

n/a

v2

0

Less than zero

n/a

0

v2 * -1

Positive or zero

Less than zero

v2 + (v4 * -1)

0

Less than zero

Positive or zero

0

v4 + (v2 * -1)

Positive or zero

Positive or zero

v2

v4

Less than zero

Less than zero

v4 * -1

v2 * -1

Battery Data

The b1 parameter represents the current battery power in watts.

A positive value indicates charging either from generation or load (consumption). A negative value is used for discharge, when battery power is drawn for consumption.

When sending battery data the b1 is parameter is mandatory, other battery parameters will be ignored if b1 is missing.

State Codes

The following values are valid b2 Battery State codes.

  • 0 - Invalid

  • 1 - Standby

  • 2 - Thermal Management

  • 3 - Enabled

  • 4 - Fault

  • 5-9 - User Defined

Examples

Send an energy value of 1000Wh and power value of 150W on 01/Dec/11 at 10:00AM

1curl -d "d=20111201" -d "t=10:00" -d "v1=1000" -d "v2=150" -H "X-Pvoutput-Apikey: Your-API-Key" -H "X-Pvoutput-SystemId: Your-System-Id" https://pvoutput.org/service/r2/addstatus.jsp

Hint

Replace Your-API-Key and Your-System-Id with your key and system id

Success Messages

The following messages will be returned upon successfully adding or updating status data.

OK 200: Added Status

  • The status data has been recieved and will either be added or updated.

Error Messages

The following service specific errors may be encountered.

For general API errors common for all services, refer to the service Common Errors section.

Bad request 400: Invalid Date [date]

  • The d date parameter is incorrectly formatted

Bad request 400: Missing date or time

  • The d date and/or t time parameter was missing or incorrectly formatted

Bad request 400: Missing energy and power values

  • The request must send at least one of the parameters v1, v2, v3 or v4

Bad request 400: Invalid future [date]

  • The date parameter must not be greater than the current date.

Bad request 400: Date is older than 14 days [date]

  • The date parameter must not be older than 14 days from the current date.

Bad request 400: Power value [power] too high for system size [system_size]

  • The power parameter is 50% greater than the system size.

Bad request 400: Moon Powered

  • The system cannot generate power during the hours of the day where there is no sunlight. Timezone may be incorrect.

Bad request 400: Energy value [energy] too high for [time]

  • The energy parameter exceeds the 1.0-4.0kWh/kW thresholds between 6:00am and 8:00am

Bad request 400: Energy value [energy] too high for system size [system_size]

  • The energy parameter exceeds the 12kWh/kW threshold.

Bad Request 400: Invalid net and cumulative

  • Data cannot be both cumulative and net. Remove c1 and/or net from the request.

Bad Request 400: Missing net power value

  • The request is missing a power value for v2 or v4

Restrictions and Limitations

  • The d date parameter must be not be older than 14 days from the current date.

  • The t time parameter is rounded to the nearest Status Interval configured for the system.

  • The energy parameters v1 and v3 are measured in watt hours (Wh).

  • The power parameters v2 and v4 are measured in watts (W).

  • An energy value cannot be lower than the previous energy value recorded in time.

  • At least one of the values v1, v2, v3 or v4 must be present.

  • Maximum energy consumption v3 value is 200,000Wh

  • Maximum power consumption v4 value is 100,000W

Donation Features

Add Batch Status Service

The Add Batch Status service adds up to 30 statuses in a single request.

Service URL

1https://pvoutput.org/service/r2/addbatchstatus.jsp

Parameters

This service accepts both GET or POST requests with the following parameters -

Parameter

Field

Required

Example

data

Delimited

Yes

See Data Structure

c1

Cumulative Flag

No

1

n

Net Flag

No

1

Data Structure

The data parameter consists of up to 30 statuses, each status contains multiple fields.

Field Delimiter

Output Delimiter

,

;

The following table specifies the composition of each status

Field

Required

Format

Unit

Example

Date

Yes

yyyymmdd

date

20210228

Time

Yes

hh:mm

time

13:00

Energy Generation

Yes

number

watt hours

10000

Power Generation

No

number

watts

2000

Energy Consumption

No

number

watt hours

10000

Power Consumption

No

number

watts

2000

Temperature

No

decimal

celsius

23.4

Voltage

No

decimal

volts

240.7

Extended Value v7

No

number

User Defined

100.5

Extended Value v8

No

number

User Defined

328

Extended Value v9

No

number

User Defined

-291

Extended Value v10

No

number

User Defined

29

Extended Value v11

No

number

User Defined

192

Extended Value v12

No

number

User Defined

9281.24

Net Data

The following data structure applies when sending batch net data with the n=1 flag.

Field

Required

Format

Unit

Example

Date

Yes

yyyymmdd

date

20210228

Time

Yes

hh:mm

time

13:00

Not Used

Power Exported

Yes

number

watts

2000

Not Used

Power Imported

Yes

number

watts

2000

Examples

Send three statuses from 10:00AM to 10:10AM in a single batch request

1curl -d "data=20110112,10:00,705,1029;20110112,10:05,775,1320;20110112,10:10,800,800" -H "X-Pvoutput-Apikey: Your-API-Key" -H "X-Pvoutput-SystemId: Your-System-Id" https://pvoutput.org/service/r2/addbatchstatus.jsp

Send a single status with Generation Energy 850Wh, Generation Power 1109W, Temperature 23.1C and Voltage 240V

1curl -d "data=20110112,10:15,850,1109,-1,-1,23.1,240" -H "X-Pvoutput-Apikey: Your-API-Key" -H "X-Pvoutput-SystemId: Your-System-Id" https://pvoutput.org/service/r2/addbatchstatus.jsp

Send a single status with Consumption Energy 2000Wh, Consumption Power 210W

1curl -d "data=20110112,4:15,-1,-1,2000,210" -H "X-Pvoutput-Apikey: Your-API-Key" -H "X-Pvoutput-SystemId: Your-System-Id" https://pvoutput.org/service/r2/addbatchstatus.jsp

Send two net statuses in a single batch request. The first exports 100W, the second imports 100W.

1curl -d "data=20180403,10:00,-1,100,-1,0;20180403,10:05,-1,0,-1,100" -d "n=1" -H "X-Pvoutput-Apikey: Your-API-Key" -H "X-Pvoutput-SystemId: Your-System-Id" https://pvoutput.org/service/r2/addbatchstatus.jsp

Success Messages

The following comma delimited data is returned in the message body

120210220,10:00,1;20210220,10:05,0;20210220,10:10,1

The data specification is shown below

Field

Format

Unit

Example

Date

yyyymmdd

date

20210228

Time

hh:mm

time

16:00

Status

number

See Status Codes

Status Codes

  • 1 - The status was successfully added

  • 0 - The status did not add or update any data

Restrictions and Limitations

  • All restrictions and limitations of the Add Status service.

  • A maximum of 30 statuses can be sent in a single batch request.

  • An Add Output is called once for the last successful status update in the batch.

  • The date parameter must be not be older than 14 days from the current date.

  • All Net statuses in the batch must have the same date.

  • A Net status must have export and import data, 0W should be sent if no export/import is to be recorded.

Donation Features

Get Status Service

The Get Status service retrieves system status information and live output data.

Service URL

1https://pvoutput.org/service/r2/getstatus.jsp

Parameters

This service accepts GET requests with the following parameters

Parameter

Field

Required

Format

Unit

Example

Donation

d

Date

No

yyyymmdd

date

20210228

t

Time

No

hh:mm

time

13:00

h

History

No

number

1

asc

Ascending

No

number

1

limit

Limit

No

number

288

from

Time From

No

hh:mm

time

9:00

to

Time To

No

hh:mm

time

13:00

ext

Extended Data

No

number

1

Required

sid1

Another System Id

No

number

35

Required

stats

Day Statistics

No

number

1

Success Messages

The following comma delimited data is returned in the message body

120210228,13:00,359,731,92,130,0.164,21.4,240.4

Response with Extended Data request ext=1

120210228,13:00,359,731,92,130,0.164,21.4,240.4,70,80,90,100,110,120

The data specification is shown below

Field

Format

Unit

Example

Donation

Date

yyyymmdd

date

20210228

Time

hh:mm

time

13:00

Energy Generation

number

watt hours

359

Power Generation

number

watt

731

Energy Consumption

number

watt hours

92

Power Consumption

number

watt

130

Normalised Output

number

kW/kW

0.164

Temperature

decimal

celsius

21.4

Voltage

decimal

volts

240.4

Extended Value v7

decimal

User Defined

Yes

Extended Value v8

decimal

User Defined

Yes

Extended Value v9

decimal

User Defined

Yes

Extended Value v10

decimal

User Defined

Yes

Extended Value v11

decimal

User Defined

Yes

Extended Value v12

decimal

User Defined

Yes

Use the d parameter to request a specific date. When date is omitted, the last known live data in the last 7 days will be used.

History Query

The h parameter when set to 1 returns the entire status for a given date. If a time parameter is passed then only statuses after the given time will be returned.

Each status is separated by a semi-colon, the data specification is shown below

Field

Format

Unit

Example

Donation

Date

yyyymmdd

date

20210228

Time

hh:mm

time

13:00

Energy Generation

number

watt hours

359

Energy Efficiency

number

kWh/kW

1.392

Instantaneous Power

number

watt

731

Average Power

number

watt

720

Normalised Output

number

kW/kW

0.164

Energy Consumption

number

watt hours

92

Power Consumption

number

watt

130

Temperature

decimal

celsius

21.4

Voltage

decimal

volts

240.4

Extended Value v7

decimal

User Defined

Yes

Extended Value v8

decimal

User Defined

Yes

Extended Value v9

decimal

User Defined

Yes

Extended Value v10

decimal

User Defined

Yes

Extended Value v11

decimal

User Defined

Yes

Extended Value v12

decimal

User Defined

Yes

The example below shows 3 history statuses returned.

120200228,10:40,359,0.080,731,732,0.164,92,130,NaN,NaN;20200228,10:35,298,0.067,710,708,0.159,81,130,NaN,NaN;20200228,10:30,239,0.054,710,708,0.159,70,130,NaN,NaN

Tip

To retrieve a full day of live data, use history with a limit of 288 i.e. h=1&limit=288

Day Statistics

The stats parameter when set to 1 returns generation, consumption and temperature summary stats for the requested day.

The following parameters can be used with stats enabled -

  • from

  • to

  • sid1

The data specification is shown below

Field

Format

Unit

Example

Energy Generation

number

watt hours

359

Power Generation

number

watt

731

Peak Power

number

watt

731

Peak Power Time

hh:mm

time

10:40

Separator 1

;

Energy Consumption

hh:mm

watt hours

92

Energy Consumption

hh:mm

watts

130

Standby Power

number

watt

104

Standby Power Time

hh:mm

watt

10:00

Separator 2

;

Temperature Min

decimal

celsius

10

Temperature Max

decimal

celsius

30

Temperature Average

decimal

celsius

20

1 Section only appears for system owners

2 Section only appears for systems with temperature

Example of day statistics response below

1359,731,731,10:40;92,130,104,10:00;10,30,20

Error Messages

Unauthorized 401: Inaccessible System ID

  • This error is reported when another system id is requested sid1 from an account without donation enabled.

A Bad request 400: No status found

  • No live data found on a specified date or no live data reported in the last 7 days when no date parameter is used.

Restrictions and Limitations

  1. The value NaN will be returned where a numeric value does not exist

  2. The maximum number of history status records returned is 288 (1 day).

  3. The parameter sid1 is able to retrieve generation data from any system. Consumption data is not returned. The requesting system must have Donation mode enabled.

  4. Extended Data values (v7-v12) will only be returned when ext is set to 1. The requesting system must have donation mode enabled.

  5. Where no limit is specified a default limit of 30 records applies

  6. Statuses are returned in descending order by default e.g. 5:00PM to 1:00PM. Use the asc parameter to reverse the order

  7. The from and to parameters can be used to restrict the data returned to the specified time range

Get Statistic Service

The Get Statistic service retrieves system statisticial information.

Service URL

1https://pvoutput.org/service/r2/getstatistic.jsp

Parameters

This service accepts GET requests with the following parameters

Parameter

Field

Required

Format

Unit

Example

Donation

df

Date From

No

yyyymmdd

date

20210201

dt

Date To

No

yyyymmdd

date

20210228

c

Consumption

No

1

crdr

Credit and Debits

No

1

sid1

Another System Id

No

Number

35

Required

Where no date range is specified the Lifetime statistic of the system will be retrieved.

Success Messages

The following comma delimited data is returned in the message body -

124600,14220,2220,800,3400,3.358,27,20210201,20210228,4.653,20210205

The data specification is shown below -

Field

Format

Unit

Example

Energy Generated

number

watt hours

24600

Energy Exported

number

watt hours

14220

Average Generation

number

watt hours

2220

Minimum Generation

number

watt hours

800

Maximum Generation

number

watt hours

3400

Average Efficiency

number

kWh/kW

3.358

Outputs

number

27

Actual Date From

yyyymmdd

date

20210201

Actual Date To

yyyymmdd

date

20210228

Record Efficiency

number

kWh/kW

4.653

Record Date

yyyymmdd

date

20210205

Additional fields are returned for consumption enabled c=1

Field

Format

Unit

Example

Energy Consumed

number

watt hours

10800

Peak Energy Import

number

watt hours

5000

Off Peak Energy Import

number

watt hours

1000

Shoulder Energy Import

number

watt hours

4000

High Shoulder Energy Import

number

watt hours

800

Average Consumption

number

watt hours

1392

Minimum Consumption

number

watt hours

10

Maximum Consumption

number

watt hours

2890

Additional fields are returned for credit and debit enabled crdr=1

Field

Format

Unit

Example

Credit Amount

decimal

currency

37.29

Debit Amount

decimal

currency

40.81

Restrictions and Limitations

  • The latest Record Date is returned where there is more than one date with the same Record Efficiency.

  • Consumption and credit/debit data is only available to the system owner.

Get System Service

The Get System service retrieves system information.

Service URL

1https://pvoutput.org/service/r2/getsystem.jsp

Parameters

This service accepts GET requests with the following parameters -

Parameter

Field

Required

Format

Example

Donation

array2

Secondary Array Details

No

number

1

tariffs

Tariff Details

No

number

1

teams

Member of Team Ids

No

number

1

est

Monthly Estimates

No

number

1

donations

Donation Count

No

number

1

sid1

Another System Id

No

number

35

Yes

ext

Extended Data Config

No

number

1

Success Messages

The following comma delimited data is returned in the message body -

1PVOutput Demo,3200,2162,10,320,Enertech,1,5000,Fronius,N,20.0,No,20120228,-33.868135,151.133423,5;;0

The data specification is shown below -

Field

Format

Unit

Example

System Name

text

PVOutput Demo

System Size

number

watts

3200

Postcode / Zipcode

number

2162

Panels

number

10

Panel Power

number

watts

320

Panel Brand

text

Enertech

Inverters

number

1

Inverter Power

watts

5000

Inverter Brand

text

Fronius

Orientation

text

N

Array Tilt

decimal

degrees

20.0

Shade

text

No

Install Date

yyyymmdd

date

20120228

Latitude

decimal

-33.868135

Longitude

decimal

151.133423

Status Interval

number

minutes

5

Secondary Panels

number

10

Secondary Panel Power

number

watts

190

Secondary Orientation

text

W

Secondary Array Tilt

decimal

degrees

30.5

Separator

;

Export Tariff

decimal

cents

12.0

Import Peak Tariff

decimal

cents

39.98

Import Off Peak Tariff

decimal

cents

12.3

Import Shoulder Tariff

decimal

cents

23.23

Import High Shoulder Tariff

decimal

cents

NaN

Import Daily Charge

decimal

cents

99.3

Separator 1

;

(Teams)

comma separated

1,12,93

Separator

;

Donations

number

0

Separator 2

;

(Extended Data Config)

comma separated

Separator 3

;

(Monthly Estimations)

comma separated

kWh

  • 1 Section appears including separator when teams set to 1

  • 2 Section appears including separator when ext set to 1

  • 3 Section appears including separator when est set to 1

Restrictions and Limitations

  • The value NaN will be returned where a numeric value does not exist

  • A blank value will be returned where a date value does not exist

  • The latitude and longitude of the system is returned if available, otherwise the system postcode latitude and longitude is returned

  • The parameter sid1 is able to retrieve information for any system. Donation data is not returned. The requesting system must have Donation mode enabled

  • A blank value will be returned where an extended data label or unit is not configured

  • Monthly estimation data only available to the system owner

Post System Service

The Post System service updates system configuration, including the setup of extended parameters.

Service URL

1https://pvoutput.org/service/r2/postsystem.jsp

Parameters

This service accepts POST requests with the following parameters -

Parameter

Field

Format

Limit

Example

Donation

name

System Name

text

30 chars

v7l - v12l

Extended Label

text

20 chars

Battery Charge

Required

v7u - v12u

Extended Unit

text

10 chars

%

Required

v7c - v12c

Extended Colour

text (hex)

6 chars

cc9966

Required

v7a - v12a

Extended Axis

number

0-5

0

Required

v7g - v12g

Extended Graph

text

area or line

Required

Example Requests

Add extended parameter v8 Battery Charge measured in % shown as an Area graph

1curl "https://pvoutput.org/service/r2/postsystem.jsp?sid=Your-System-Id&key=Your-API-Key&v8l=Battery+Charge&v8u=%&v8g=area"

Restrictions and Limitations

  • Both label and unit of an extended parameter must be specified if it does not already exist

  • Extended parameters cannot be removed, blank labels and unit values will be ignored

Get Ladder Service

The Get Ladder service retrieves system ladder information including ranking and total outputs.

Service URL

1https://pvoutput.org/service/r2/getladder.jsp

Parameters

This service accepts GET requests with the following parameters -

Parameter

Field

Required

Format

Unit

Example

Donation

sid1

Another System Id

No

Number

35

Required

Success Messages

The following comma delimited data is returned in the message body -

120211028,19899,11123,2.902,1223,20211028,10976552,0,8975,0,20115,0,3464

The data specification is shown below -

Field

Format

Unit

Example

Ranking Date

yyyymmdd

date

20211028

Generation Rank

number

19899

Efficiency Rank

number

11123

Average Efficiency

number

kWh/kW

2.902

Total Outputs

number

days

1223

Last Output

yyyymmdd

date

20211028

Total Generation

number

watt hours

10976552

Total Consumption

number

watt hours

0

Average Generation

number

watt hours

8975

Average Consumption

number

watt hours

0

Maximum Generation

number

watt hours

20115

Maximum Consumption

number

watt hours

0

System Age

number

days

3464

Restrictions and Limitations

  • The value NaN will be returned where a numeric value does not exist

  • The parameter sid1 is able to retrieve information from any system. Consumption data is not returned. The requesting system must have Donation mode enabled.

Get Output Service

The Get Output service retrieves system or team daily output information.

Service URL

1https://pvoutput.org/service/r2/getoutput.jsp

Parameters

This service accepts GET requests with the following parameters -

Parameter

Field

Required

Format

Unit

Example

Donation

df

Date From

No

yyyymmdd

date

20210201

dt

Date To

No

yyyymmdd

date

20210228

a

Aggregate

No

text

m or y

limit

Limit

No

number

30

tid

Team Id

No

number

20

sid1

Another System Id

No

Number

35

Required

insolation

Insolation

No

number

1

Required

timeofexport

Time of Export

No

number

1

Required

Where no date range is specified, the most recent outputs of the system will be retrieved.

Success Messages

The following comma delimited data is returned in the message body -

Each output is separated by a semi-colon.

120210218,479,0.213,0,0,1500,11:10,Showers,NaN,NaN,NaN,NaN,NaN,NaN;

The data specification is shown below -

Field

Format

Unit

Example

Date

yyyymmdd

date

20210228

Energy Generated

number

watt hours

4413

Efficiency

number

kWh/kW

0.460

Energy Exported

number

watt hours

0

Energy Used

number

watt hours

21859

Peak Power

number

watts

2070

Peak Time

time

hh:mm

11:00

Condition

text

Showers

Min. Temperature

number

celsius

-3

Max. Temperature

number

celsius

6

Peak Energy Import

number

watt hours

4220

Off Peak Energy Import

number

watt hours

7308

Shoulder Energy Import

number

watt hours

2030

High Shoulder Energy Import

number

watt hours

3888

The data fields below are present when timeofexport=1 is sent

Field

Format

Unit

Example

Peak Energy Export

number

watt hours

3220

Off Peak Energy Export

number

watt hours

6307

Shoulder Energy Export

number

watt hours

1030

High Shoulder Energy Export

number

watt hours

30

The data fields below are present when insolation=1 is sent

Field

Format

Unit

Example

Insolation

number

watt hours

12910

Insolation

When the insolation parameter is set to 1, the service will return the total daily insolation value for each output date. This value is identical to the last energy figure returned in the Get Insolation service.

Aggregated Outputs

When the a parameter is set to m monthly, or y yearly the output data is summed.

The following comma delimited data is returned in the message body -

Each output is separated by a semi-colon.

1202102,30,475875,4.764,292834,245629,58411,136433,50785,0

The data specification is shown below -

Field

Format

Unit

Example

Date

yyyymmdd

date

20210228

Outputs

number

30

Energy Generated

number

watt hours

475875

Efficiency

number

kWh/kW

4.764

Energy Exported

number

watt hours

292834

Energy Used

number

watt hours

245629

Peak Energy Import

number

watt hours

58411

Off Peak Energy Import

number

watt hours

136433

Shoulder Energy Import

number

watt hours

50785

High Shoulder Energy Import

number

watt hours

0

The data fields below are present when timeofexport=1 is sent

Field

Format

Unit

Example

Peak Energy Export

number

watt hours

3220

Off Peak Energy Export

number

watt hours

6307

Shoulder Energy Export

number

watt hours

1030

High Shoulder Energy Export

number

watt hours

30

Team Output

When the tid parameter is specified, the outputs for the requested team is returned.

The following comma delimited data is returned in the message body -

Each output is separated by a semi-colon.

120210228,6,3.543,81392,13565,7813,24345,4058,14314

The data specification is shown below -

Field

Format

Unit

Example

Date

yyyymmdd

date

20210228

Outputs

number

6

Efficiency

number

kWh/kW

3.543

Total Generation

number

watt hours

81392

Average Generation

number

watt hours

13565

Total Exported

number

watt hours

7813

Total Consumption

number

watt hours

24345

Average Consumption

number

watt hours

4058

Total Imported

number

watt hours

14314

Restrictions and Limitations

  • The value NaN will be returned where a numeric value does not exist

  • The maximum number of output records returned is 50. The limit is increased to 150 for donators.

  • The parameter sid1 is able to retrieve information from any system. Consumption data is not returned. The requesting system must have Donation mode enabled.

  • Aggregated team output is not supported.

Get Extended Service

The Get Extended service retrieves system daily extended data.

Service URL

1https://pvoutput.org/service/r2/getextended.jsp

Parameters

This service accepts GET requests with the following parameters -

Parameter

Field

Required

Format

Unit

Example

df

Date From

No

yyyymmdd

date

20210201

dt

Date To

No

yyyymmdd

date

20210228

limit

Limit

No

number

50

Where no date range is specified, the most recent system extended data will be retrieved.

Success Messages

The following comma delimited data is returned in the message body -

Each daily record is separated by a semi-colon.

120210228,67.4,825.321,349.0,1105.0,1115.0,-12.3

The data specification is shown below -

Field

Format

Unit

Example

Date

yyyymmdd

date

20210228

Extended Value v7

number

User Defined

67.4

Extended Value v8

number

User Defined

825.321

Extended Value v9

number

User Defined

349.0

Extended Value v10

number

User Defined

1105.0

Extended Value v11

number

User Defined

1115.0

Extended Value v12

number

User Defined

-12.3

Restrictions and Limitations

  • The value NaN will be returned where a numeric value does not exist

  • The maximum number of daily records returned is 50

  • The requesting system must have Donation mode enabled

Get Favourite Service

The Get Favourite service retrieves the systems in your favourites or another user’s favourites.

Service URL

1https://pvoutput.org/service/r2/getfavourite.jsp

Parameters

This service accepts GET requests with the following parameters -

Parameter

Field

Required

Format

Unit

Example

Donation

sid1

Another System Id

No

number

35

Required

Success Messages

The following comma delimited data is returned in the message body -

18,Climate Change Skeptic,2450,2200,14,175,Enertech,1,2000,CMS2000,N,20.0,Low,20100806,-33.919539,151.034909,5

The data specification is shown below -

Field

Format

Unit

Example

System Id

text

8

System Name

text

Climate Change Skeptic

System Size

number

watts

2450

Postcode

number

2200

Panels

number

14

Panel Power

number

watts

175

Panel Brand

text

Enertech

Inverters

number

1

Inverter Power

watts

2000

Inverter Brand

text

CMS2000

Orientation

text

N

Array Tilt

decimal

degrees

20.0

Shade

text

Low

Install Date

yyyymmdd

date

20100806

Latitude

decimal

-33.919539

Longitude

decimal

151.034909

Status Interval

number

minutes

5

Note

Each system in the favourite list is separated by a new line.

Restrictions and Limitations

  • A maximum of 50 systems will be returned.

  • The value NaN will be returned where a numeric value does not exist

  • A blank value will be returned where a date value does not exist

  • The latitude and longitude of the system is returned if available, otherwise the system postcode latitiude and longitude is returned

  • The parameter sid1 is able to retrieve favourites for another system. The requesting system must have Donation mode enabled.

Get Missing Service

The Get Missing service retrieves a list of output dates missing from a system.

Service URL

1https://pvoutput.org/service/r2/getmissing.jsp

Parameters

This service accepts GET requests with the following parameters

Parameter

Field

Required

Format

Unit

Example

df

Date From

No

yyyymmdd

date

20210201

dt

Date To

No

yyyymmdd

date

20210228

Success Messages

The following comma delimited data is returned in the message body -

120210203,20210204

The data specification is shown below -

Field

Format

Unit

Min Occurs

Max Occurs

Example

Missing Date

yyyymmdd

date

0

50

20210203

Restrictions and Limitations

  • A maximum of 50 missing dates will be returned.

  • Dates are returned in ascending order i.e. oldest to most recent.

Get Insolation Service

The Get Insolation service retrieves 5-minute insolation data (power and energy) under ideal weather conditions.

The insolation data returned is calculated based on the following parameters -

  • Latitude and Longitude

  • System Size

  • Azimuth or Orientation

  • Array Tilt

  • Timezone

  • Day of the year

Service URL

1https://pvoutput.org/service/r2/getinsolation.jsp

Parameters

This service accepts GET requests with the following parameters

Parameter

Field

Required

Format

Unit

Example

Donation

d

Date

No

yyyymmdd

date

20210228

Required

tz

Timezone

No

text

See Timezone

Required

ll

Latitude and Longitude

No

decimal

-33.907725,151.026108

Required

sid1

Another System Id

No

number

35

Required

Latitude and Longitude

The latitude and longitude is obtained in the following order of precedence -

  1. The latitude/longitude value in the ll parameter.

  2. The system latitude/longitude configured for the system.

  3. The postcode/zipcode latitude/longitude configured for the system

Timezone

The timezone set for the system is used for insolation calculation. A different timezone may be used with the tz parameter.

Date

The current date is used for insolation calculation. A different date may be used with the d parameter.

Example Requests

Get the insolation data for your system for today

1curl "https://pvoutput.org/service/r2/getinsolation.jsp?sid=Your-System-Id&key=Your-API-Key"

Get the insolation data for your system on 28 Feb 2021, in timezone Australia/Brisbane at location -27.4676,153.0279

1curl "https://pvoutput.org/service/r2/getinsolation.jsp?sid=Your-System-Id&key=Your-API-Key&d=20210228&tz=Australia/Brisbane&ll=-27.4676,153.0279"

Get the insolation data for System Id 12345 for today

1curl "https://pvoutput.org/service/r2/getinsolation.jsp?sid=Your-System-Id&key=Your-API-Key&sid1=12345"

Hint

Replace Your-API-Key and Your-System-Id with your key and system id

Success Messages

The following comma delimited data is returned in the message body -

106:00,0,0;06:05,3,0;06:10,11,1;06:15,25,3;06:20,44,7;06:25,67,12;06:30,93,20;06:35,123,30

The data specification is shown below -

Field

Format

Unit

Example

Time

hh:mm

13:45

Power

number

watts

1050

Energy

number

watt hours

4028

Note

Insolation values are returned for each 5-minute interval and are separated by a semi-colon ;

Restrictions and Limitations

  • The UTC timezone is used when the system does not have a timezone configured or no tz parameter is passed.

  • Insolation data is not available for systems without a configured location or postcode.

Donation Features

See Donation feature section.

Delete Status Service

The Delete Status service removes an existing status from the system.

Service URL

1https://pvoutput.org/service/r2/deletestatus.jsp

Parameters

This service accepts POST or GET requests with the following parameters -

Parameter

Field

Required

Format

Unit

Example

d

Date

Yes

yyyymmdd

date

20210228

t

Time

No

hh:mm

date

19:00

Warning

If the t time parameter is omitted then all statuses for the given date will be deleted.

Success Messages

The following message will be returned upon successfully deleting status data.

OK 200: Deleted Status

  • The status on the given date and time has been removed

Error Messages

The following service specific errors may be encountered.

For general API errors common for all services, refer to the service Common Errors section.

Bad request 400: Date is required

  • The d date parameter was missing or incorrectly formatted

Bad request 400: Status not found

  • Requested date was not found

Bad request 400: Date is in the future

  • The date parameter must not be greater than the current date.

Bad request 400: Invalid date: [date]

  • The d date parameter is incorrectly formatted

Bad request 400: Invalid time: [time]

  • The t time parameter is incorrectly formatted

Bad request 400: Date is older than 14 days [date]

  • The date parameter must not be older than 14 days from the current date.

Restrictions and Limitations

  • The d date parameter must be not be older than 14 days from the current date.

Donation Features

See Donation feature section.

Search Service

The Search service retrieves a list of systems matching the given search query.

Service URL

1https://pvoutput.org/service/r2/search.jsp

Parameters

This service accepts GET or POST requests with the following parameters -

Parameter

Field

Required

Example

q

Query

Yes

See Search

ll

Latitude/Longitude 1

No

-27.42234,152.98142

country

Country Flag 2

No

1

country_code

Country Code 3

No

See Codes

seen

Last Seen 4

No

7

  • 1 The point of origin used for distance searches

  • 2 The country name is prefixed to the postcode returned e.g. ‘Australia 2000’

  • 3 Filter results by country code. Required for postcode distance search e.g. ‘4000 20km’

  • 4 Filter results by last output activity. e.g. ‘7’ for the last 7 days

Country Codes

List of valid country_codes below -

  • au

  • be

  • dk

  • it

  • nl

  • uk

  • us

Success Messages

The following comma delimited data is returned in the message body -

1Albany Creek Enphase,9990,4035,N,181,Today,78641,Longi 370,Enphase IQ7+,NaN,-27.345529,152.968403
2Albion Enphase,6660,4010,EW,164,Today,79034,Longi 370,Enphase IQ7+,NaN,-27.428026,153.045205
3Alderley Enphase,11360,4051,N,140,Today,79541,Sunpower P3-320,Enphase IQ7+,NaN,-27.424422,153.000517
4Allandale Enphase,6050,4107,N,6,Today,81322,Winaico WST275,S230-60-LN-2-AU,NaN,-27.544798,153.029585
5AmbalindumHawker Enphase,11220,2614,NW,356,Today,74207,Trina,Enphase,NaN,-35.257964,149.075648

The data specification is shown below -

Field

Format

Unit

Example

System Name

text

Albany Creek Enphase

System Size

number

watts

9990

Postcode

text

4035

Orientation

text

N, W, E, S, NE, NW, SE, SW

Outputs

number

442

Last Output

text

Today, Yesterday, n days ago

System Id

number

78641

Panel

text

Longi 370

Inverter

text

Enphase IQ7+

Distance

number

kilometres

23

Latitude

decimal

-27.345529

Longitude

decimal

152.968403

Note

Each system in the search result is separated by a new line.

Restrictions and Limitations

  • Distance is returned if an origin is given via the distance query 4000 5km or latitude/longitude.

  • Systems are returned by distance, if available, otherwise system name.

  • The system latitude and longitude is returned if known, otherwise the postcode latitude/longitude where the system resides is returned.

  • A maximum of 30 systems will be returned.

Get Team Service

The Get Team service retrieves team information.

Service URL

1https://pvoutput.org/service/r2/getteam.jsp

Parameters

This service accepts GET requests with the following parameters -

Parameter

Field

Required

Format

Unit

Example

tid

Team Id

No

number

1

Success Messages

The following comma delimited data is returned in the message body -

1CMS Inverters;108131;2845;38;402662180;46887;9014;Inverter;Join this team if you have a CMS inverter;20100917

The data specification is shown below -

Field

Format

Unit

Example

Team Name

text

CMS Inverters

Team Size

number

watts

108131

Average Size

number

watts

2845

Number Of Systems

number

38

Energy Generated

number

watt hours

402662180

Outputs

number

46887

Energy Average

number

watt hours

9014

Type

text

See Teams

Description

text

Creation Date

date

yyyymmdd

20100917

Error Messages

The following service specific errors may be encountered.

For general API errors common for all services, refer to the service Common Errors section.

Bad request 400: No team found

  • The tid Team Id requested was not found

Restrictions and Limitations

  • Only team owners may retrieve details of their own team. Donation enabled accounts may query any team.

Join Team Service

The Join Team service adds the system to a team

Service URL

1https://pvoutput.org/service/r2/jointeam.jsp

Parameters

This service accepts GET requests with the following parameters -

Parameter

Field

Required

Format

Unit

Example

tid

Team Id

No

number

1

Success Messages

OK 200: You have joined team [team_name]

  • The system has been added to the team

Error Messages

The following service specific errors may be encountered.

For general API errors common for all services, refer to the service Common Errors section.

Bad Request 400: You cannot join a team that does not exist

  • The tid Team Id does not exist

Bad Request 400: Your system cannot join more than 10 teams

  • The number of teams the system has join has been reached

Bad Request 400: You are already a member of [team_name]

  • The system has already joined the specified team

Bad Request 400: Your system must have at least 5 outputs to join a team

  • The system does not have enough outputs to join a team

Restrictions and Limitations

  • The system must have at least 5 outputs

  • The system cannot join more than 10 teams

Leave Team Service

The Leave Team service removes the system from a team

Service URL

1https://pvoutput.org/service/r2/leaveteam.jsp

Parameters

This service accepts GET requests with the following parameters -

Parameter

Field

Required

Format

Unit

Example

tid

Team Id

No

number

1

Success Messages

OK 200: You have left team [team_name]

  • The system has been removed from the team

Error Messages

The following service specific errors may be encountered.

For general API errors common for all services, refer to the service Common Errors section.

Bad Request 400: You cannot leave a team that does not exist

  • The tid Team Id does not exist

Bad Request 400: You are not a member of team [team_name]

  • The system is not part of the specified team

Bad Request 400: You cannot leave the team [team_name] which you started

  • Team owners cannot leave a team which they created

Restrictions and Limitations

  • The system cannot leave a team which it has created

Get Supply Service

The Get Supply service displays aggregated live generation and consumption data.

Service URL

1https://pvoutput.org/service/r2/getsupply.jsp

Parameters

This service accepts GET requests with the following parameters -

Parameter

Field

Required

Format

Unit

Example

Donation

tz

Timezone

No

text

See Timezone

r

Region Key

No

text

See Region Keys

Required

Region Keys

The list of valid r region keys below -

Australia

Region Key

1:australian_capital_territory

1:new_south_wales

1:northern_territory

1:queensland

1:south_australia

1:tasmania

1:victoria

1:western_australia

The Netherlands

Region Key

165:provincie_drenthe

165:provincie_flevoland

165:provincie_friesland

165:provincie_gelderland

165:provincie_groningen

165:provincie_limburg

165:provincie_noord-brabant

165:provincie_noord-holland

165:provincie_overijssel

165:provincie_utrecht

165:provincie_zeeland

165:provincie_zuid-holland

United Kingdom

Region Key

243:belfast

243:cardiff

243:carlisle

243:derby

243:east

243:east_of_england

243:huddersfield

243:leicester

243:lincoln

243:llandrindod_wells

243:llandudno

243:london

243:motherwell

243:newport

243:northampton

243:north_east

243:north_west

243:nottingham

243:paisley

243:romford

243:scotland

243:scottish_islands

243:shetland_isles

243:south_east

243:southend_on_sea

243:south_west

243:stoke_on_trent

243:sunderland

243:sutton

243:swansea

243:tweed

243:uvbridge

243:west_midlands

243:wolverhampton

243:yorkshire_and_the_humber

United States

Region Key

244:alabama

244:alaska

244:arizona

244:arkansas

244:california

244:colorado

244:connecticut

244:delaware

244:district_of_columbia

244:florida

244:georgia

244:hawaii

244:idaho

244:illinois

244:indiana

244:iowa

244:kansas

244:kentucky

244:louisiana

244:maine

244:maryland

244:massachusetts

244:michigan

244:minnesota

244:missouri

244:montana

244:nebraska

244:nevada

244:new_hampshire

244:new_jersey

244:new_mexico

244:new_york

244:north_carolina

244:ohio

244:oklahoma

244:oregon

244:pennsylvania

244:rhode_island

244:south_carolina

244:tennessee

244:texas

244:utah

244:vermont

244:virginia

244:washington

244:west_virginia

244:wisconsin

Italy

Region Key

117:abruzzi

117:basilicata

117:calabria

117:campania

117:emilia-romagna

117:friuli-venezia_giulia

117:lazio

117:liguria

117:lombardia

117:marche

117:molise

117:piemonte

117:puglia

117:sardegna

117:sicilia

117:toscana

117:trentino-alto_adige

117:umbria

117:valle_daosta

117:veneto

Belgium

Region Key

25:bruxelles-capitale

25:vlaanderen

25:wallonie

Denmark

Region Key

67:hovedstaden

Example Requests

1curl -H "X-Pvoutput-Apikey: Your-API-Key" -H "X-Pvoutput-SystemId: Your-System-Id" https://pvoutput.org/service/r2/getsupply.jsp?r=1:new_south_wales&tz=Australia/Sydney

Success Messages

Requesting the service without any parameters -

12021-03-06T10:40:00+0000,Provincie Noord-brabant,45.818,1124034,109147,2590,658,1932,434,166,2453266,5653
22021-03-06T10:40:00+0000,Provincie Zuid-holland,27.835,689367,72542,1732,733,999,398,99,2476616,6223
32021-03-06T10:40:00+0000,Vlaanderen,53.224,620380,40517,2885,988,1897,215,41,1165592,5421
42021-03-06T10:40:00+0000,Provincie Gelderland,27.616,564729,106644,1272,544,728,444,196,2044914,4606
52021-03-06T10:40:00+0000,Provincie Utrecht,40.674,493152,23869,2326,442,1884,212,54,1212461,5719
62021-03-06T10:40:00+0000,Provincie Limburg,55.036,392549,10291,2351,245,2106,167,42,713255,4271
72021-03-06T10:40:00+0000,Friuli-venezia Giulia,52.152,366703,12152,9650,1350,8300,38,9,703144,18504

Requesting the service for a specific region r=1:new_south_wales&tz=Australia/Sydney

12021-03-06T21:10:00+1100,New South Wales,0.297,8799,244722,35,1046,-1011,250,234,2960410,11842
22021-03-06T21:00:00+1100,New South Wales,0.127,4302,275312,13,956,-943,341,288,3390529,9943
32021-03-06T20:50:00+1100,New South Wales,0.099,2968,267929,12,978,-966,253,274,2987354,11808
42021-03-06T20:40:00+1100,New South Wales,0.081,2391,284416,9,1094,-1085,254,260,2944539,11593
52021-03-06T20:30:00+1100,New South Wales,0.202,6670,300258,20,1025,-1005,333,293,3299984,9910
62021-03-06T20:20:00+1100,New South Wales,0.115,3418,252361,13,1065,-1052,258,237,2983444,11564
72021-03-06T20:10:00+1100,New South Wales,0.158,4789,249695,18,1058,-1040,264,236,3025374,11460

Note

Each region status is separated by a semi-colon.

The data specification is shown below -

Field

Format

Unit

Example

Timestamp

yyyy-mm-ddThh:mm:ssZ

timestamp

2021-03-06T21:10:00+1100

Region Name

text

New South Wales

Utilisation

decimal

percentage

0.297

Total Power Output

number

watts

8799

Total Power Input

number

watts

244722

Average Power Output

number

watts

35

Average Power Input

number

watts

1046

Average Net Power

number

watts

-1011

Systems Out

number

250

Systems In

number

234

Total Size

number

watts

2960410

Average Size

number

watts

11842

Restrictions and Limitations

  • When the tz parameter is empty, the timezone will default to UTC

  • When the r parameter is provided, the 24 hour supply and demand history of the region is returned

  • Region demand and supply history is delayed by 20 minutes

  • Region demand and supply history is returned in 10 minute resolution

Register Notification Service

The Register Notification Service allows a third party application to receive PVOutput alert callbacks via a HTTP end point.

Service URL

1https://pvoutput.org/service/r2/registernotification.jsp

Parameters

This service accepts GET requests with the following parameters -

Parameter

Field

Required

Format

Example

appid

Application Id

Yes

text

my.application.id

url

Callback URL

Yes

text

http://my.application.com/api/alert.php

type

Alert Type

Yes

number

See Types

Alert Types

Type

Description

0

All Notifications

1

Private Message

3

Joined Team

4

Added Favourite

5

High Consumption Alert

6

System Idle Alert

8

Low Generation Alert

11

Performance Alert

14

Standby Cost Alert

15

Extended Data V7 Alert

16

Extended Data V8 Alert

17

Extended Data V9 Alert

18

Extended Data V10 Alert

19

Extended Data V11 Alert

20

Extended Data V12 Alert

23

High Net Power Alert

24

Low Net Power Alert

Callback URL

Normally when an alert is triggered the system owner will be sent an email.

If the alert has been registered for notifications then the subject of the email message will be sent to the callback url.

The POST request will contain the following parameters -

Parameter

Field

Format

Example/Comment

appid

Application Id

text

The application id in the registration request

msg

Notification Message

text

Your system has been idle for more than 15 minutes

type

Alert Type

number

See Types

Restrictions and Limitations

  • The alert type must be enabled for the notification to be sent.

  • All notification types are sent to the same url with the same appid.

  • The url must not be longer than 150 characters.

  • The appid must not be longer than 100 characters.

  • A maximum of 1 application id can be registered for a system.

Donation Features

  • Maximum number of application ids increased to 5.

Deregister Notification Service

The Deregister Notification Service removes registered notifications under an application id for a system.

Service URL

1https://pvoutput.org/service/r2/deregisternotification.jsp

Parameters

This service accepts GET requests with the following parameters -

Parameter

Field

Required

Format

Example

appid

Application Id

Yes

text

my.application.id

type

Alert Type

Yes

number

See Types

Common Errors

The following errors may be encountered across all API services -

Method Not Allowed 405: POST or GET only

  • Data must be sent via the HTTP POST or GET method

Unauthorized 401: Invalid System ID

  • The required parameter X-Pvoutput-SystemId or sid is missing from the request. The sid is a number which identifies a system. The sid can be obtained from the Settings page under Registered Systems

Unauthorized 401: Invalid API Key

  • The API key is missing in the header request or the API key is invalid.

Unauthorized 401: Disabled API Key

  • The API key has not been enabled in the Settings.

Forbidden 403: Read only key

  • The API key provided is a read only key and cannot access the requested service which updates system data, use the standard key to update system data.

Unauthorized 401: Missing, invalid or inactive api key information (X-Pvoutput-Apikey)

  • The sid and key combination is invalid

Forbidden 403: Exceeded number requests per hour

  • The maximum number of requests per hour has been reached for the API key. Wait till the next hour before making further requests.

Forbidden 403: Donation Mode

  • Request is only available in Donation mode.