Developer Network NREL NREL Developer Network

PVWatts V6 (GET /api/pvwatts/v6)

PVWatts Version 6 is is the current version of the PVWatts API. Updates from Version 5 include access to the Physical Solar Model (PSM) TMY and SUNY South Asia solar resource data from the NREL National Solar Radiation Database (NSRDB) by default, with optional access to the legacy solar resource data: NSRDB MTS2 1991-2005 Update (TMY3), NSRDB MTS1 1961-1990 (TMY2), and NREL international station data. PVWatts Version 6 also sets the default DC-to-AC ratio to 1.2 instead of 1.1, but you can specify a different DC to AC ratio for your simulation. For a complete description of PVWatts V6, see the description on the PVWatts website

The algorithms used to calculate energy output are the same as in Version 5. For a technical description of the model, see Dobos, A. P. PVWatts Version 5 Manual. NREL/TP-6A20-62641, 2014.

Request URL

GET /api/pvwatts/v6.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 API. Required if lat/lon or address not specified.
dataset No
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

NREL Physical Solar Model (PSM) TMY from the NREL National Solar Radiation Database (NSRDB) (see nsrdb.nrel.gov/about)

tmy2

TMY2 station data (see Typical Meteorological Year, version 2)

tmy3

TMY3 station data (see Typical Meteorological Year version 3)

intl

International station data

radius No
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 No
Type: string
Default: monthly
Options: monthly, hourly
Granularity of the output response.
dc_ac_ratio No
Type: decimal
Default: 1.2
Range: must be positive

DC to AC ratio.

gcr No
Type: decimal
Default: 0.4
Range: 0 - 3

Ground coverage ratio.

inv_eff No
Type: decimal
Default: 96
Range: 90 - 99.5

Inverter efficiency at rated power.

callback No
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 climate 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)


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)

Examples

JSON Output Format

GET /api/pvwatts/v6.json?api_key=DEMO_KEY&lat=40&lon=-105&system_capacity=4&azimuth=180&tilt=40&array_type=1&module_type=1&losses=10
{
    "inputs": {
        "system_capacity": "4",
        "lat": "40",
        "lon": "-105",
        "azimuth": "180",
        "tilt": "40",
        "array_type": "1",
        "module_type": "1",
        "losses": "10"
    },
    "errors": [],
    "warnings": [],
    "version": "1.4.0",
    "ssc_info": {
        "version": 45,
        "build": "Linux 64 bit GNU/C++ Jul  7 2015 14:24:09"
    },
    "station_info": {
        "lat": 40.0099983215332,
        "lon": -105.0199966430664,
        "elev": 1581.8399658203125,
        "tz": -7,
        "location": "None",
        "city": "",
        "state": "Colorado",
        "solar_resource_file": "W10502N4001.csv",
        "distance": 2029
    },
    "outputs": {
        "ac_monthly": [
            474.4326171875,
            484.3903503417969,
            595.7704467773438,
            592.0599365234375,
            591.2662353515625,
            589.3538208007812,
            583.2352905273438,
            586.4593505859375,
            584.8131713867188,
            561.72314453125,
            486.12603759765625,
            445.68817138671875
        ],
        "poa_monthly": [
            141.48094177246094,
            145.57119750976562,
            184.7876434326172,
            181.55137634277344,
            186.42808532714844,
            190.51329040527344,
            188.74996948242188,
            190.53981018066406,
            188.2213134765625,
            175.4444122314453,
            146.31704711914062,
            131.15682983398438
        ],
        "solrad_monthly": [
            4.563901424407959,
            5.198971271514893,
            5.9608917236328125,
            6.051712512969971,
            6.0138092041015625,
            6.350442886352539,
            6.088708877563477,
            6.146445274353027,
            6.274043560028076,
            5.659497261047363,
            4.877234935760498,
            4.230865478515625
        ],
        "dc_monthly": [
            497.9421081542969,
            511.1524963378906,
            634.3223266601562,
            623.7313842773438,
            617.8812866210938,
            615.4278564453125,
            609.3965454101562,
            612.7506713867188,
            610.5584106445312,
            588.6157836914062,
            508.07476806640625,
            465.4272155761719
        ],
        "ac_annual": 6575.31884765625,
        "solrad_annual": 5.618043899536133,
        "capacity_factor": 18.765178680419922
    }
}

XML Output Format

GET /api/pvwatts/v6.xml?api_key=DEMO_KEY&lat=40&lon=-105&system_capacity=4&azimuth=180&tilt=40&array_type=1&module_type=1&losses=10
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <inputs>
        <system-capacity>4</system-capacity>
        <lat>40</lat>
        <lon>-105</lon>
        <azimuth>180</azimuth>
        <tilt>40</tilt>
        <array-type>1</array-type>
        <module-type>1</module-type>
        <losses>10</losses>
    </inputs>
    <errors type="array"/>
    <warnings type="array"/>
    <version>1.4.0</version>
    <ssc-info>
        <version type="integer">45</version>
        <build>Linux 64 bit GNU/C++ Jul  7 2015 14:24:09</build>
    </ssc-info>
    <station-info>
        <lat type="float">40.0099983215332</lat>
        <lon type="float">-105.0199966430664</lon>
        <elev type="float">1581.8399658203125</elev>
        <tz type="float">-7.0</tz>
        <location>None</location>
        <city></city>
        <state>Colorado</state>
        <solar-resource-file>W10502N4001.csv</solar-resource-file>
        <distance type="integer">2029</distance>
    </station-info>
    <outputs>
        <ac-monthly type="array">
            <ac-monthly type="float">474.4326171875</ac-monthly>
            <ac-monthly type="float">484.3903503417969</ac-monthly>
            <ac-monthly type="float">595.7704467773438</ac-monthly>
            <ac-monthly type="float">592.0599365234375</ac-monthly>
            <ac-monthly type="float">591.2662353515625</ac-monthly>
            <ac-monthly type="float">589.3538208007812</ac-monthly>
            <ac-monthly type="float">583.2352905273438</ac-monthly>
            <ac-monthly type="float">586.4593505859375</ac-monthly>
            <ac-monthly type="float">584.8131713867188</ac-monthly>
            <ac-monthly type="float">561.72314453125</ac-monthly>
            <ac-monthly type="float">486.12603759765625</ac-monthly>
            <ac-monthly type="float">445.68817138671875</ac-monthly>
        </ac-monthly>
        <poa-monthly type="array">
            <poa-monthly type="float">141.48094177246094</poa-monthly>
            <poa-monthly type="float">145.57119750976562</poa-monthly>
            <poa-monthly type="float">184.7876434326172</poa-monthly>
            <poa-monthly type="float">181.55137634277344</poa-monthly>
            <poa-monthly type="float">186.42808532714844</poa-monthly>
            <poa-monthly type="float">190.51329040527344</poa-monthly>
            <poa-monthly type="float">188.74996948242188</poa-monthly>
            <poa-monthly type="float">190.53981018066406</poa-monthly>
            <poa-monthly type="float">188.2213134765625</poa-monthly>
            <poa-monthly type="float">175.4444122314453</poa-monthly>
            <poa-monthly type="float">146.31704711914062</poa-monthly>
            <poa-monthly type="float">131.15682983398438</poa-monthly>
        </poa-monthly>
        <solrad-monthly type="array">
            <solrad-monthly type="float">4.563901424407959</solrad-monthly>
            <solrad-monthly type="float">5.198971271514893</solrad-monthly>
            <solrad-monthly type="float">5.9608917236328125</solrad-monthly>
            <solrad-monthly type="float">6.051712512969971</solrad-monthly>
            <solrad-monthly type="float">6.0138092041015625</solrad-monthly>
            <solrad-monthly type="float">6.350442886352539</solrad-monthly>
            <solrad-monthly type="float">6.088708877563477</solrad-monthly>
            <solrad-monthly type="float">6.146445274353027</solrad-monthly>
            <solrad-monthly type="float">6.274043560028076</solrad-monthly>
            <solrad-monthly type="float">5.659497261047363</solrad-monthly>
            <solrad-monthly type="float">4.877234935760498</solrad-monthly>
            <solrad-monthly type="float">4.230865478515625</solrad-monthly>
        </solrad-monthly>
        <dc-monthly type="array">
            <dc-monthly type="float">497.9421081542969</dc-monthly>
            <dc-monthly type="float">511.1524963378906</dc-monthly>
            <dc-monthly type="float">634.3223266601562</dc-monthly>
            <dc-monthly type="float">623.7313842773438</dc-monthly>
            <dc-monthly type="float">617.8812866210938</dc-monthly>
            <dc-monthly type="float">615.4278564453125</dc-monthly>
            <dc-monthly type="float">609.3965454101562</dc-monthly>
            <dc-monthly type="float">612.7506713867188</dc-monthly>
            <dc-monthly type="float">610.5584106445312</dc-monthly>
            <dc-monthly type="float">588.6157836914062</dc-monthly>
            <dc-monthly type="float">508.07476806640625</dc-monthly>
            <dc-monthly type="float">465.4272155761719</dc-monthly>
        </dc-monthly>
        <ac-annual type="float">6575.31884765625</ac-annual>
        <solrad-annual type="float">5.618043899536133</solrad-annual>
        <capacity-factor type="float">18.765178680419922</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