Getting Started with pvwatts

Quick introduction to querying solar resource data

Author

Alejandro Hagan

Published

March 2, 2026

Overview

pvwatts provides R access to NREL’s PVWatts v8 API for solar production estimates. Use it to: - Query solar yield for any location worldwide - Get monthly generation profiles for financial models - Compare array configurations (fixed vs tracking, bifacial, etc.)

Installation

pak::pak("git::https://codeberg.org/usrbinr/pvwatts")

API Key Setup

pvwatts requires a free NREL API key.

Get Your Key

Visit developer.nrel.gov/signup
Fill out the form (instant approval)
Copy your API key

Save Your Key

Add to your ~/.Renviron file:

# Open .Renviron for editing
usethis::edit_r_environ()

# Add this line:
# NREL_API_KEY=your_key_here

Restart R after saving.

Quick Start

Query a Location

library(pvwatts)

result <- pvwatts(lat = 30.27, lon = -97.74)  # Austin, TX

ℹ Querying PVWatts for (30.27, -97.74)...
✔ Yield: 1735 kWh/kWp (Austin, Texas)

Access Results

The result is an S7 object. Use @ to access properties:

# Annual summary
result@annual
#> # A tibble: 1 × 5
#>   generation_kwh yield_kwh_per_kwp yield_p90_kwh_per_kwp capacity_factor_pct
#>            <dbl>             <dbl>                 <dbl>               <dbl>
#> 1       1734771.              1735                  1624                19.8

# Monthly generation factors (for seasonality)
result@monthly$generation_factor
#>  [1] 0.0577 0.0562 0.0783 0.0931 0.1010 0.1100 0.1140 0.1120 0.0880 0.0774
#> [11] 0.0572 0.0550

# Location info
result@location
#> # A tibble: 1 × 8
#>   city   state lat   lon   elevation_m tz_offset weather_source
#>   <chr>  <chr> <dbl> <dbl>       <dbl>     <dbl> <chr>
#> 1 Austin Texas  30.3 -97.7         165        -6 NSRDB PSM V3...

Using Location Presets

pvwatts includes coordinates for major US solar markets:

# See available locations
list_locations()

# Get coordinates
loc <- preset_location("phoenix_az")
loc$lat
#> [1] 33.45
loc$lon
#> [1] -112.07

# Query using preset
result <- pvwatts(lat = loc$lat, lon = loc$lon)
result@annual$yield_kwh_per_kwp
#> [1] 2087

Array Types

Compare mounting configurations:

# Fixed ground mount
fixed <- pvwatts(lat = 30.27, lon = -97.74, array_type = "fixed")
fixed@annual$yield_kwh_per_kwp
#> [1] 1498

# Single-axis tracking (default)
tracking <- pvwatts(lat = 30.27, lon = -97.74, array_type = "1-axis")
tracking@annual$yield_kwh_per_kwp
#> [1] 1735

# Tracking boost
(1735 - 1498) / 1498 * 100
#> [1] 15.8%

PVWatts Parameters

Parameter	Default	Description
`lat`, `lon`	(required)	Location coordinates
`system_capacity_kw`	1000	System size
`array_type`	“1-axis”	“fixed”, “fixed-roof”, “1-axis”, “1-axis-backtrack”, “2-axis”
`tilt`	auto	Panel tilt (degrees)
`azimuth`	180	Panel direction (180=south)
`losses`	14	System losses (%)
`dc_ac_ratio`	1.2	Inverter loading ratio
`module_type`	“standard”	“standard”, “premium”, “thin-film”
`bifaciality`	0	Bifacial factor (0-1)
`albedo`	auto	Ground reflectance

Package Options

options(
  pvwatts.timeout = 30,        # Request timeout (seconds)
  pvwatts.throttle_rate = 30,  # Max requests per minute
  pvwatts.silent = FALSE       # Show info messages
)

Next Steps

See vignette("pvwatts-deep-dive") for advanced usage including bifacial modules, batch queries, and best practices.