PVWatts V8 (GET /api/pvwatts/v8)

PVWatts^® Version 8 is is the current version of the PVWatts API. Updates from Version 6 include a bifacial module option, a new input for monthly irradiance losses, new inputs for specifying albedo, and updates to the photovoltaic module, inverter, and thermal effects models to use more detailed and industry-accepted algorithms. PVWatts V8 also updates the weather data to 2020 TMY data from the NREL National Solar Radiation Database (NSRDB) for locations covered by the database. (The NSRDB weather data used in PVWatts V6 is from around 2015.) This update provides production estimates based on the latest, state-of-the art models from NREL that may differ from the V6 estimates, depending on the location and inputs. From a coding perspective, PVWatts V8 replaces the pvwattsv5 compute module with pvwattsv8 so that the PVWatts Calculator, web API, and implementation of PVWatts in the System Advisor Model (SAM) all use the same underlying model. For a complete description of PVWatts V8, see the description on the PVWatts website.

NREL anticipates that the V8 API will run slightly slower than the V6 API due to upgraded models. Please contact pvwatts@nrel.gov if you find V8 is significantly slower or that the performance is impacting your product.

There is a forthcoming report containing a technical description of the model.

Request URL

GET /api/pvwatts/v8.format?parameters

Request Parameters

Parameter Required Value Description

format

Yes

Type: string

Default: None

Options: json, xml

The output response format.

api_key

Yes

Type: string

Default: None

Your developer API key. See API keys for more information.

system_capacity

Yes

Type: decimal

Default: None

Range: 0.05 to 500000

Nameplate capacity (kW).

module_type

Yes

Type: integer

Default: None

Options: 0, 1, 2

Module type.

Option	Description
0	Standard
1	Premium
2	Thin film

losses

Yes

Type: decimal

Default: None

Range: -5 to 99

System losses (percent).

array_type

Yes

Type: integer

Default: None

Options: 0, 1, 2, 3, 4

Array type.

Option	Description
0	Fixed - Open Rack
1	Fixed - Roof Mounted
2	1-Axis
3	1-Axis Backtracking
4	2-Axis

tilt

Yes

Type: decimal

Default: None

Range: 0 to 90

Tilt angle (degrees).

azimuth

Yes

Type: decimal

Default: None

Min: 0

Max: < 360

Azimuth angle (degrees).

address

Depends

Type: string

Default: None

The address to use. Required if lat/lon or file_id not specified.

lat

Depends

Type: decimal

Default: None

Range: -90 to 90

The latitude for the location to use. Required if address or file_id not specified.

lon

Depends

Type: decimal

Default: None

Range: -180 to 180

The longitude for the location to use. Required if address or file_id not specified.

file_id

Depends

Type: string

Default: none

Reference to a specific climate data file to use. Must be a valid id returned by the Solar Dataset Query V2 API. Required if lat/lon or address not specified.

dataset

Type: string

Default: nsrdb

Options: nsrdb, tmy2, tmy3, intl

The climate dataset to use. Should not be passed in if using file_id to specify the climate data file.

Option	Description
nsrdb	Gridded TMY data from the NREL National Solar Radiation Database (NSRDB). Datasets include: NSRDB PSM V3 GOES tmy-2020 3.2.0, NSRDB PSM V3 Himawari tmy-2020 3.2.0, and SUNY METEOSAT IODC tmy
tmy2	TMY2 station data (see NSRDB 1961-1990 Archive)
tmy3	TMY3 station data (see NSRDB 1991-2005 Archive)
intl	PVWatts International station data

radius

Type: integer

Default: 100

The search radius to use when searching for the closest climate data station (miles). Pass in radius=0 to use the closest station regardless of the distance.

timeframe

Type: string

Default: monthly

Options: monthly, hourly

Granularity of the output response.

dc_ac_ratio

Type: decimal

Default: 1.2

Range: must be positive

DC to AC ratio.

gcr

Type: decimal

Default: 0.4

Range: 0.01 - 0.99

Ground coverage ratio.

inv_eff

Type: decimal

Default: 96

Range: 90 - 99.5

Inverter efficiency at rated power.

bifaciality

Type: decimal

Default: None

Range: 0 - 1

The ratio of rear-side efficiency to front-side efficiency. Typically a value between 0.65 and 0.9 provided on the bifacial module datasheeet. This is to account for the fact that photovoltaic cells on the rear of the module are usually less efficient than the cells on the front of the module. The bifaciality does not affect the solar irradiance on the rear of the module.

albedo

Type: decimal or array of decimal

Default: None

Range: >0 and <1

Ground reflectance. A value of 0 would mean that the ground is completely non-reflective, and a value of 1 would mean that it is completely reflective. Specify either a pipe-delimited array of 12 monthly values or a single value to be used for all months.

use_wf_albedo

Type: integer

Default: None

Options: 0, 1

Use hourly or subhourly albedo data from the weather file instead of the monthly albedo values, if available. 0 means do not use weather file albedo values, 1 means use weather file albedo values.

soiling

Type: array of decimal

Default: None

Range: 0 - 100

Reduction in incident solar irradiance caused by dust or other seasonal soiling of the module surface that reduce the radiation incident on the subarray. Soiling losses cause a uniform reduction in the total irradiance incident on each subarray. Specify a pipe-delimited array of 12 monthly values.

callback

Type: string

Default: None

Return the data using JSONP and the given callback function (only applicable when using the json format).

Response Fields

The response is composed of service-related informational fields and the results of the PVWatts simulation.

Field	Value	Description
inputs	Type: collection	The input parameters received in the request.
errors	Type: array of strings	Any error messages resulting from the request.
warnings	Type: array of strings	Any warning messages resulting from the request.
version	Type: string	The current version of the web service.
ssc_info	Type: collection	Information about the SSC library.
station_info	Type: collection	Information about the weather data used in the simulation. (see station info fields for more detail)
outputs	Type: collection	The data outputs from the simulation. (see output fields for more detail)

Station Info Fields

Field	Value	Description
lat	Type: decimal	Latitude of the climate station.
lon	Type: decimal	Longitude of the climate station.
elev	Type: decimal	Elevation of the climate station. (meters)
tz	Type: decimal	Timezone offset from GMT.
location	Type: string	ID of the climate station.
city	Type: string	City where climate station is located.
state	Type: string	State where climate station is located.
solar_resource_file	Type: string	Solar resource filename.
distance	Type: integer	Distance between the input location and the climate station. (meters)
weather_data_source	Type: string	Source of the weather data used in the simulation.

Output Fields

Field	Value	Description
poa_monthly	Type: array of decimal	Monthly plane of array irradiance values. (kWh/m2) The array of values represents the value for each month, with the first element being for January and the last element being for December.
dc_monthly	Type: array of decimal	Monthly DC array output. (kWhdc) The array of values represents the value for each month, with the first element being for January and the last element being for December.
ac_monthly	Type: array of decimal	Monthly AC system output. (kWhac) The array of values represents the value for each month, with the first element being for January and the last element being for December.
ac_annual	Type: decimal	Annual AC system output. (kWhac)
solrad_monthly	Type: array of decimal	Monthly solar radiation values. (kWh/m2/day) The array of values represents the value for each month, with the first element being for January and the last element being for December.
solrad_annual	Type: decimal	Annual solar radiation values. (kWh/m2/day)
capacity_factor	Type: decimal	The ratio of the system's predicted electrical output in the first year of operation to the nameplate output, which is equivalent to the quantity of energy the system would generate if it operated at its nameplate capacity for every hour of the year. (AC-to-DC)
ac	Type: array of decimal	Hourly AC system output (only when timeframe=hourly). (Wac)
poa	Type: array of decimal	Hourly plane of array irradiance (only when timeframe=hourly). (W/m2)
dn	Type: array of decimal	Hourly beam normal irradiance (only when timeframe=hourly). (W/m2)
dc	Type: array of decimal	Hourly DC array output (only when timeframe=hourly). (Wdc)
df	Type: array of decimal	Hourly diffuse irradiance (only when timeframe=hourly). (W/m2)
tamb	Type: array of decimal	Hourly ambient temperature (only when timeframe=hourly). (C)
tcell	Type: array of decimal	Hourly module temperature (only when timeframe=hourly) (C)
wspd	Type: array of decimal	Hourly windspeed (only when timeframe=hourly). (m/s)
alb	Type: array of decimal	Hourly albedo values (only when timeframe=hourly).

Examples

JSON Output Format

GET /api/pvwatts/v8.json?api_key=DEMO_KEY&azimuth=180&system_capacity=4&losses=14&array_type=1&module_type=0&gcr=0.4&dc_ac_ratio=1.2&inv_eff=96.0&radius=0&dataset=nsrdb&tilt=10&address=boulder, co&soiling=12|4|45|23|9|99|67|12.54|54|9|0|7.6&albedo=0.3&bifaciality=0.7

{
  "inputs": {
    "api_key": "DEMO_KEY",
    "azimuth": "180",
    "system_capacity": "4",
    "losses": "14",
    "array_type": "1",
    "module_type": "0",
    "gcr": "0.4",
    "dc_ac_ratio": "1.2",
    "inv_eff": "96.0",
    "radius": "0",
    "dataset": "nsrdb",
    "tilt": "10",
    "address": "boulder, co",
    "soiling": [
      12.0,
      4.0,
      45.0,
      23.0,
      9.0,
      99.0,
      67.0,
      12.54,
      54.0,
      9.0,
      0.0,
      7.6
    ],
    "albedo": "0.3",
    "bifaciality": "0.7"
  },
  "errors": [],
  "warnings": [],
  "version": "8.0.0",
  "ssc_info": {
    "version": 275,
    "build": "Linux 64 bit GNU/C++ Oct  4 2022 03:10:07",
    "module": "pvwattsv8"
  },
  "station_info": {
    "lat": 40.0099983215332,
    "lon": -105.2600021362305,
    "elev": 1635.640014648438,
    "tz": -7.0,
    "location": "149190",
    "city": "",
    "state": "Colorado",
    "solar_resource_file": "149190.csv",
    "weather_data_source": "NSRDB PSM V3 GOES tmy-2020 3.2.0"
  },
  "outputs": {
    "ac_monthly": [
      320.4228876642905,
      384.8616364666353,
      321.3271515621691,
      461.0094975545317,
      554.600835450473,
      40.44452828685269,
      226.7508104582373,
      511.2267102793363,
      256.8889494651126,
      399.0896267699792,
      360.6690887453739,
      294.0619118014161
    ],
    "poa_monthly": [
      96.24926945531107,
      116.1349407270755,
      98.51940622925228,
      144.41773091741,
      183.8794484222849,
      15.66165708215378,
      77.02556424264554,
      173.1452731392307,
      84.65672810465938,
      127.5225461326769,
      111.2069066909127,
      88.32854384099618
    ],
    "solrad_monthly": [
      3.104815143719712,
      4.147676454538409,
      3.178045362233945,
      4.813924363913667,
      5.931595110396287,
      0.5220552360717927,
      2.484695620730502,
      5.585331391588086,
      2.821890936821979,
      4.113630520408932,
      3.706896889697091,
      2.849307865838586
    ],
    "dc_monthly": [
      336.9419000259236,
      403.7478814828723,
      339.0451574758127,
      484.2180320849528,
      582.0288887329309,
      48.66263077401924,
      242.1187483732162,
      536.8888804277215,
      272.1669926053272,
      419.1849677039804,
      378.8226598116249,
      309.3147603281601
    ],
    "ac_annual": 4131.353634504403,
    "solrad_annual": 3.604988741329917,
    "capacity_factor": 11.79039279253541
  }
}

XML Output Format

GET /api/pvwatts/v8.xml?api_key=DEMO_KEY&azimuth=180&system_capacity=4&losses=14&array_type=1&module_type=0&gcr=0.4&dc_ac_ratio=1.2&inv_eff=96.0&radius=0&dataset=nsrdb&tilt=10&address=boulder, co&soiling=12|4|45|23|9|99|67|12.54|54|9|0|7.6&albedo=0.3&bifaciality=0.7

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <inputs>
    <api-key>DEMO_KEY</api-key>
    <azimuth>180</azimuth>
    <system-capacity>4</system-capacity>
    <losses>14</losses>
    <array-type>1</array-type>
    <module-type>0</module-type>
    <gcr>0.4</gcr>
    <dc-ac-ratio>1.2</dc-ac-ratio>
    <inv-eff>96.0</inv-eff>
    <radius>0</radius>
    <dataset>nsrdb</dataset>
    <tilt>10</tilt>
    <address>boulder, co</address>
    <soiling type="array">
      <soiling type="float">12.0</soiling>
      <soiling type="float">4.0</soiling>
      <soiling type="float">45.0</soiling>
      <soiling type="float">23.0</soiling>
      <soiling type="float">9.0</soiling>
      <soiling type="float">99.0</soiling>
      <soiling type="float">67.0</soiling>
      <soiling type="float">12.54</soiling>
      <soiling type="float">54.0</soiling>
      <soiling type="float">9.0</soiling>
      <soiling type="float">0.0</soiling>
      <soiling type="float">7.6</soiling>
    </soiling>
    <albedo>0.3</albedo>
    <bifaciality>0.7</bifaciality>
  </inputs>
  <errors type="array"/>
  <warnings type="array"/>
  <version>8.0.0</version>
  <ssc-info>
    <version type="integer">275</version>
    <build>Linux 64 bit GNU/C++ Oct  4 2022 03:10:07</build>
    <module>pvwattsv8</module>
  </ssc-info>
  <station-info>
    <lat type="float">40.0099983215332</lat>
    <lon type="float">-105.26000213623047</lon>
    <elev type="float">1635.6400146484375</elev>
    <tz type="float">-7.0</tz>
    <location>149190</location>
    <city></city>
    <state>Colorado</state>
    <solar-resource-file>149190.csv</solar-resource-file>
    <weather-data-source>NSRDB PSM V3 GOES tmy-2020 3.2.0</weather-data-source>
  </station-info>
  <outputs>
    <ac-monthly type="array">
      <ac-monthly type="float">320.4228876642905</ac-monthly>
      <ac-monthly type="float">384.8616364666353</ac-monthly>
      <ac-monthly type="float">321.32715156216915</ac-monthly>
      <ac-monthly type="float">461.00949755453166</ac-monthly>
      <ac-monthly type="float">554.600835450473</ac-monthly>
      <ac-monthly type="float">40.444528286852695</ac-monthly>
      <ac-monthly type="float">226.75081045823728</ac-monthly>
      <ac-monthly type="float">511.2267102793363</ac-monthly>
      <ac-monthly type="float">256.8889494651126</ac-monthly>
      <ac-monthly type="float">399.0896267699792</ac-monthly>
      <ac-monthly type="float">360.66908874537387</ac-monthly>
      <ac-monthly type="float">294.0619118014161</ac-monthly>
    </ac-monthly>
    <poa-monthly type="array">
      <poa-monthly type="float">96.24926945531107</poa-monthly>
      <poa-monthly type="float">116.13494072707546</poa-monthly>
      <poa-monthly type="float">98.51940622925228</poa-monthly>
      <poa-monthly type="float">144.41773091741</poa-monthly>
      <poa-monthly type="float">183.8794484222849</poa-monthly>
      <poa-monthly type="float">15.661657082153782</poa-monthly>
      <poa-monthly type="float">77.02556424264554</poa-monthly>
      <poa-monthly type="float">173.14527313923068</poa-monthly>
      <poa-monthly type="float">84.65672810465938</poa-monthly>
      <poa-monthly type="float">127.5225461326769</poa-monthly>
      <poa-monthly type="float">111.20690669091273</poa-monthly>
      <poa-monthly type="float">88.32854384099618</poa-monthly>
    </poa-monthly>
    <solrad-monthly type="array">
      <solrad-monthly type="float">3.1048151437197116</solrad-monthly>
      <solrad-monthly type="float">4.147676454538409</solrad-monthly>
      <solrad-monthly type="float">3.1780453622339446</solrad-monthly>
      <solrad-monthly type="float">4.813924363913667</solrad-monthly>
      <solrad-monthly type="float">5.9315951103962865</solrad-monthly>
      <solrad-monthly type="float">0.5220552360717927</solrad-monthly>
      <solrad-monthly type="float">2.4846956207305015</solrad-monthly>
      <solrad-monthly type="float">5.5853313915880864</solrad-monthly>
      <solrad-monthly type="float">2.8218909368219793</solrad-monthly>
      <solrad-monthly type="float">4.113630520408932</solrad-monthly>
      <solrad-monthly type="float">3.706896889697091</solrad-monthly>
      <solrad-monthly type="float">2.849307865838586</solrad-monthly>
    </solrad-monthly>
    <dc-monthly type="array">
      <dc-monthly type="float">336.9419000259236</dc-monthly>
      <dc-monthly type="float">403.7478814828723</dc-monthly>
      <dc-monthly type="float">339.04515747581274</dc-monthly>
      <dc-monthly type="float">484.21803208495277</dc-monthly>
      <dc-monthly type="float">582.0288887329309</dc-monthly>
      <dc-monthly type="float">48.66263077401924</dc-monthly>
      <dc-monthly type="float">242.1187483732162</dc-monthly>
      <dc-monthly type="float">536.8888804277215</dc-monthly>
      <dc-monthly type="float">272.16699260532715</dc-monthly>
      <dc-monthly type="float">419.1849677039804</dc-monthly>
      <dc-monthly type="float">378.82265981162493</dc-monthly>
      <dc-monthly type="float">309.3147603281601</dc-monthly>
    </dc-monthly>
    <ac-annual type="float">4131.353634504403</ac-annual>
    <solrad-annual type="float">3.6049887413299166</solrad-annual>
    <capacity-factor type="float">11.79039279253541</capacity-factor>
  </outputs>
</response>

Rate Limits

Standard rate limits apply. No more than 1,000 requests may be made in any hour.

Errors

Standard errors may be returned. In addition, the following service-specific errors may be returned:

HTTP Status Code	Description
422	Unprocessable Entity - One or more parameters did not pass validation, or a parameter may be missing. Check the errors section of the response to see how the request should be modified to address the error.

Help Improve this Content