PVWatts Getting Started: API Access and First Request (2026)

Getting started overview

Integrating with the PVWatts API enables developers to programmatically access solar photovoltaic (PV) system performance estimates. This process typically involves registering for an API key, understanding the required parameters for the API, and constructing a valid HTTP GET request to retrieve data. The PVWatts API, provided by the National Renewable Energy Laboratory (NREL), is designed for straightforward integration, offering a free service for preliminary solar project assessments and research.

The core functionality of the PVWatts API revolves around providing hourly, monthly, and annual energy production estimates for grid-connected PV systems. These estimates are based on user-defined system parameters and location data. Developers can specify a wide range of variables, including system size, array type, tilt, azimuth, and loss factors, to simulate various scenarios. The API returns results in JSON format, facilitating parsing and integration into applications or analytical tools.

Before making your first API call, it's essential to familiarize yourself with the NREL Developer Network and the specific requirements for PVWatts. This includes understanding rate limits, data formats, and error handling. The NREL Developer Network provides a unified portal for accessing various NREL APIs, with distinct documentation for each service. The PVWatts API is designed to be accessible to developers with varying levels of experience in solar energy modeling, focusing on ease of use while maintaining scientific rigor in its estimations.

Below is a quick reference guide to the essential steps for getting started:

Create an account and get keys

Access to the PVWatts API requires an API key from the NREL Developer Network. This key identifies your application and helps NREL manage API usage and provide support. The process for obtaining a key is free and generally involves a few steps:

1. Navigate to the NREL Developer Network: Open your web browser and go to the NREL Developer Network homepage.

2. Sign Up for an Account: Click on the "Sign Up" or "Register" button. You will typically be prompted to provide an email address, create a password, and agree to the terms of service. NREL's terms of service outline acceptable use and data policies, which are important to review to ensure compliance.

3. Verify Your Email: After submitting your registration, NREL will send a verification email to the address you provided. Follow the instructions in the email to activate your account. This step is crucial for security and to ensure you receive important updates from NREL.

4. Log In: Once your account is activated, log in to the NREL Developer Network using your newly created credentials.

5. Locate Your API Key: Upon logging in, your API key should be displayed prominently on your account dashboard or a dedicated "API Keys" section. The key is a unique alphanumeric string. It is important to treat this key as sensitive information, as it grants access to the API on your behalf.

NREL provides a single API key that grants access to all NREL APIs, including PVWatts. There are no separate keys for individual services. The API key is typically a 32-character hexadecimal string. For example, a key might look like abcdefghijklmnopqrstuvwxyz0123456789 (this is an illustrative example and not a real key). It is recommended to store your API key securely and avoid embedding it directly into client-side code that could be publicly exposed.

Your first request

Once you have your NREL API key, you can construct and execute your first request to the PVWatts API. This example demonstrates fetching a basic solar energy production estimate for a specific location using cURL, a common command-line tool for making HTTP requests. You will need a latitude and longitude for a location, and a few basic system parameters.

The PVWatts API v8 endpoint is https://developer.nrel.gov/api/pvwatts/v8.json. All requests are made via HTTP GET, with parameters passed in the URL query string.

Required Parameters

For a basic request, the following parameters are typically required:

• api_key: Your NREL API key.
• lat: Latitude of the system location (e.g., 34.05).
• lon: Longitude of the system location (e.g., -118.25).
• system_capacity: Nameplate capacity of the PV system in kilowatts (kW) (e.g., 4 for a 4kW system).
• module_type: Type of PV module (0: Standard, 1: Premium, 2: Thin Film).
• array_type: Type of array mounting (0: Fixed (open rack), 1: Fixed (roof mount), 2: 1-Axis, 3: 1-Axis Backtracking, 4: 2-Axis).
• tilt: Tilt angle of the array in degrees (0-90).
• azimuth: Azimuth angle of the array in degrees (0-359, 180=south).
• losses: System losses in percentage (e.g., 14 for 14%).

Example cURL Request

Replace YOUR_API_KEY with your actual NREL API key.

curl -X GET "https://developer.nrel.gov/api/pvwatts/v8.json?api_key=YOUR_API_KEY&lat=34.05&lon=-118.25&system_capacity=4&module_type=0&array_type=1&tilt=20&azimuth=180&losses=14"

Example Python Request

For Python, you can use the requests library:

import requests
import json

api_key = "YOUR_API_KEY" # Replace with your NREL API key
lat = 34.05
lon = -118.25
system_capacity = 4 # kW
module_type = 0 # Standard
array_type = 1 # Fixed (roof mount)
tilt = 20 # degrees
azimuth = 180 # degrees (South)
losses = 14 # percent

url = f"https://developer.nrel.gov/api/pvwatts/v8.json?api_key={api_key}&lat={lat}&lon={lon}&system_capacity={system_capacity}&module_type={module_type}&array_type={array_type}&tilt={tilt}&azimuth={azimuth}&losses={losses}"

try:
    response = requests.get(url)
    response.raise_for_status() # Raise an exception for HTTP errors
    data = response.json()
    print(json.dumps(data, indent=2))
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")
except json.JSONDecodeError:
    print(f"Failed to decode JSON from response: {response.text}")

Interpreting the Response

A successful response will return a JSON object containing various data points, including:

• outputs: Contains the actual energy production data (e.g., ac_annual for annual AC production in kWh, ac_monthly for monthly production).
• errors: An array of error messages, if any.
• warnings: An array of warning messages, if any.
• inputs: A reflection of the input parameters used for the calculation.

For a detailed breakdown of all possible output fields, consult the PVWatts API v8 documentation.

Common next steps

After successfully making your first PVWatts API call, consider these next steps to further integrate and optimize your use of the service:

1. Explore Advanced Parameters: The PVWatts API offers a range of additional parameters to refine your simulations, such as specific component choices (inverter efficiency, ground coverage ratio for tracking systems), and advanced loss parameters (shading, snow, soiling). Review the PVWatts API v8 reference to understand how these can be used to improve the accuracy of your estimates for specific project types.

2. Implement Error Handling: Robust applications should include comprehensive error handling. The PVWatts API returns clear error messages in the errors array of the JSON response. Implement logic to check for and appropriately respond to these messages, which can indicate issues like invalid parameters, rate limit infringements, or internal server errors. For example, a 400 Bad Request HTTP status code often accompanies detailed error messages within the JSON payload indicating a malformed request.

3. Manage Rate Limits: NREL APIs typically have rate limits to ensure fair usage across all developers. While specific limits for PVWatts are detailed in the NREL Developer Network terms, it's good practice to implement mechanisms like exponential backoff for retries to avoid exceeding these limits, especially in applications that make frequent calls. Monitoring HTTP headers like X-RateLimit-Limit and X-RateLimit-Remaining (if provided by NREL) can help manage this effectively.

4. Integrate with Mapping Services: For applications requiring geographical context, integrate PVWatts with mapping APIs such as the Google Maps Geocoding API or ArcGIS Mapping APIs. This allows users to input addresses or click on a map to retrieve latitude and longitude coordinates, which can then be passed to PVWatts for location-specific solar estimates. This enhances user experience by abstracting away the need for manual coordinate input.

5. Automate Data Processing: Develop scripts or application logic to automatically process the JSON output from PVWatts. This could involve storing the data in a database, generating reports, visualizing the energy production profiles, or integrating the estimates into financial models for solar project feasibility studies. Libraries like Pandas in Python are useful for data manipulation and analysis.

6. Explore NREL's Other APIs: The NREL Developer Network offers several other APIs related to renewable energy, such as the National Solar Radiation Database (NSRDB) API for detailed solar radiation data, or the System Advisor Model (SAM) API for more complex energy system modeling. These can complement PVWatts for more comprehensive analyses.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps for typical problems with the PVWatts API:

1. Invalid API Key

• Symptom: You receive an error message indicating an invalid API key, or a 401 Unauthorized HTTP status code.
• Solution: Double-check that you have correctly copied and pasted your NREL API key into the api_key parameter of your request URL. Ensure there are no extra spaces or characters. Log in to your NREL Developer Network account to verify your key.

2. Missing or Invalid Required Parameters

• Symptom: The API returns a 400 Bad Request error with messages like "Missing parameter: lat" or "Invalid value for system_capacity."
• Solution: Review the PVWatts API v8 documentation for the list of required parameters and their acceptable value ranges. Ensure all mandatory parameters (e.g., lat, lon, system_capacity, module_type, array_type, tilt, azimuth, losses) are present in your request URL and that their values are within the specified limits. For instance, latitude should be between -90 and 90, and longitude between -180 and 180.

3. Rate Limit Exceeded

• Symptom: You receive a 429 Too Many Requests HTTP status code.
• Solution: This indicates you have exceeded the number of allowed requests within a specific time frame. Wait for the rate limit window to reset before making further requests. For production applications, implement a delay or exponential backoff strategy for retries to avoid hitting this limit. Check the NREL Developer Network documentation for specific rate limit details.

4. Network Connectivity Issues

• Symptom: Your request times out or returns a network-related error.
• Solution: Verify your internet connection. If using cURL or a programming language, ensure your firewall or network settings are not blocking outbound requests to developer.nrel.gov. Try accessing the NREL Developer Network website directly in your browser to confirm connectivity.

5. Incorrect Endpoint or Protocol

• Symptom: You receive a 404 Not Found error or an SSL/TLS handshaking error.
• Solution: Ensure you are using the correct API endpoint (https://developer.nrel.gov/api/pvwatts/v8.json) and that you are using HTTPS, not HTTP. The API requires secure communication.

6. JSON Parsing Errors

• Symptom: Your application fails to parse the API response, or the response content is unexpected.
• Solution: Inspect the raw response text from the API. If it's not valid JSON, there might be an issue with the API service or an underlying error that prevented a proper JSON payload from being returned (e.g., an HTML error page instead of JSON for a 500 server error). Ensure your JSON parsing library is configured correctly.