Developer Network NREL NREL Developer Network
  1. Documentation
  2. Solar
  3. Solar Dataset Query
  4. Solar Dataset Query V2

Solar Dataset Query V2 (GET /api/solar/data_query/v2)

Returns information about data available for a given location for the solar resource database used by the PVWatts® Calculator and PVWatts v8 API.

Request URL

GET /api/solar/data_query/v2.format?parameters

Request Parameters

Parameter Required Value Description
format Yes
Type: string
Default: None
Options: json, xml, csv

The output response format.
api_key Yes
Type: string
Default: None

Your developer API key. See API keys for more information.
address Depends
Type: string
Default: None
The address to use. Required if lat/lon not specified.
lat Depends
Type: decimal
Default: None
Min: -90
Max: 90
The latitude for the location to use. Required if address not specified.
lon Depends
Type: decimal
Default: None
Min: -180
Max: 180
The longitude for the location to use. Required if address not specified.
radius No
Type: integer
Default: 100
Min: 0
Max: 2000

The search radius to use when searching for climate data stations (miles). Pass in radius=0 to find the closest stations regardless of the distance. A value greater than 0 is required when using in combination with all=1.
all No
Type: integer
Default: 0
Options: 0, 1

Return all stations within the radius. The closest stations will still be returned individually.

Response Fields

The response is composed of service-related informational fields and information about the closest climate data files.

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. This includes messages regarding data not being found for one or more datasets.
version Type: string The current version of the web service.
metadata Type: collection Any metadata associated with the request (sources, etc)
outputs Type: collection

Information about the climate data files for each supported dataset. Keys represent the dataset code. (see output fields for more detail)

Key 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

Output Fields

The output fields contain the following information regarding climate data files from each supported dataset. If no data is found for a specific dataset, the service will return null for it in the outputs, and return a message in the warnings.

Field Value Description
id Type: string An identifier for the climate data within the dataset.
lat Type: decimal The latitude of the station.
lon Type: decimal The longitude of the station.
city Type: string The city where the station is located.
state Type: string The state where the station is located.
timezone Type: integer The timezone of the station, relative to GMT.
elevation Type: integer The elevation of the station in meters.
distance Type: integer The distance in meters from the input location to the station.
weather_data_source Type: string Source of the weather data used in the simulation.

Examples

JSON Output Format

GET /api/solar/data_query/v2.json?api_key=DEMO_KEY&lat=40&lon=-105&radius=0&all=1
{
  "version": "1.4.0",
  "warnings": [],
  "errors": [],
  "metadata": {},
  "inputs": {
    "api_key": "DEMO_KEY",
    "address": "boulder, co",
    "radius": "0"
  },
  "outputs": {
    "tmy2": {
      "id": "0-94018",
      "city": "BOULDER",
      "state": "COLORADO",
      "timezone": -7,
      "lat": 40.13,
      "lon": -105.24,
      "elevation": 1689,
      "distance": 13224,
      "weather_data_source": "NSRDB 1961-1990 Archive TMY2"
    },
    "tmy3": {
      "id": "1-724699",
      "city": "BROOMFIELD/JEFFCO [BOULDER - SURFRAD]",
      "state": "COLORADO",
      "timezone": -7,
      "lat": 40.13,
      "lon": -105.24,
      "elevation": 1689,
      "distance": 13224,
      "weather_data_source": "NSRDB 1991-2005 Archive TMY3"
    },
    "intl": {
      "id": "2-26110-tm3",
      "city": "YELLOWKNIFE",
      "state": "NORTHWEST TERRITORIES",
      "timezone": -7,
      "lat": 62.47,
      "lon": -114.45,
      "elevation": 205,
      "distance": 2495062,
      "weather_data_source": "PVWatts International"
    },
    "nsrdb": {
      "id": "3-G-0149190",
      "city": "",
      "state": "Colorado",
      "country": "United States",
      "lat": 40.01,
      "lon": -105.26,
      "distance": 1750,
      "timezone": -7,
      "elevation": 1635,
      "resolution": 4,
      "weather_data_source": "NSRDB PSM V3 GOES tmy-2020 3.2.0"
    }
  }
}

XML Output Format

GET /api/solar/data_query/v2.xml?api_key=DEMO_KEY&lat=40&lon=-105&radius=0&all=1
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <version>1.4.0</version>
  <warnings type="array"/>
  <errors type="array"/>
  <metadata>
  </metadata>
  <inputs>
    <api-key>DEMO_KEY</api-key>
    <address>boulder, co</address>
    <radius>0</radius>
  </inputs>
  <outputs>
    <tmy2>
      <id>0-94018</id>
      <city>BOULDER</city>
      <state>COLORADO</state>
      <timezone type="integer">-7</timezone>
      <lat type="float">40.13</lat>
      <lon type="float">-105.24</lon>
      <elevation type="integer">1689</elevation>
      <distance type="integer">13224</distance>
      <weather-data-source>NSRDB 1961-1990 Archive TMY2</weather-data-source>
    </tmy2>
    <tmy3>
      <id>1-724699</id>
      <city>BROOMFIELD/JEFFCO [BOULDER - SURFRAD]</city>
      <state>COLORADO</state>
      <timezone type="integer">-7</timezone>
      <lat type="float">40.13</lat>
      <lon type="float">-105.24</lon>
      <elevation type="integer">1689</elevation>
      <distance type="integer">13224</distance>
      <weather-data-source>NSRDB 1991-2005 Archive TMY3</weather-data-source>
    </tmy3>
    <intl>
      <id>2-26110-tm3</id>
      <city>YELLOWKNIFE</city>
      <state>NORTHWEST TERRITORIES</state>
      <timezone type="integer">-7</timezone>
      <lat type="float">62.47</lat>
      <lon type="float">-114.45</lon>
      <elevation type="integer">205</elevation>
      <distance type="integer">2495062</distance>
      <weather-data-source>PVWatts International</weather-data-source>
    </intl>
    <nsrdb>
      <id>3-G-0149190</id>
      <city></city>
      <state>Colorado</state>
      <country>United States</country>
      <lat type="float">40.01</lat>
      <lon type="float">-105.26</lon>
      <distance type="integer">1750</distance>
      <timezone type="integer">-7</timezone>
      <elevation type="integer">1635</elevation>
      <resolution type="integer">4</resolution>
      <weather-data-source>NSRDB PSM V3 GOES tmy-2020 3.2.0</weather-data-source>
    </nsrdb>
  </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