1. Documentation
2. Solar
3. NSRDB Data Downloads
4. NSRDB Full Disc

NSRDB Full Disc (/api/nsrdb/v2/solar/full-disc-download)

This data provides monthly average and annual average daily total solar resource averaged over surface cells of 0.02 degrees in both latitude and longitude, or nominally 2 km in size. The solar radiation values represent the resource available to solar energy systems. The data was created using cloud properties which are generated using the AVHRR Pathfinder Atmospheres-Extended (PATMOS-x) algorithms. Fast all-sky radiation model for solar applications (FARMS) in conjunction with the cloud properties, and aerosol optical depth (AOD) and precipitable water vapor (PWV) from ancillary source are used to estimate DNI and GHI. The direct normal irradiance (DNI) and GHI are computed for clear skies using the REST2 model. For cloud scenes identified by the cloud mask, the FARMS is used to compute the GHI. The DNI for cloud scenes is then computed using the DISC model. These API provide access to downloading the data. Other options are detailed here. Read more about the datasets at https://nsrdb.nrel.gov

The PATMOS-X model uses 10 minute radiance images in visible and infrared channels from the GOES series of geostationary weather satellites, daily snow cover data from the NSIDC and mixing ratio, temperature and pressure profiles from the Modern Era-Retrospective Analysis (MERRA-2) dataset. The REST2 model uses hourly aerosol optical depth from MERRA-2 to calculate GHI and DNI; water vapor and other inputs for REST 2 are obtained from the MERRA-2.

This API is capable of creating very large downloadable archives. Unlike a typical API, the response to this provides a request acknowledgement. The real work of creating the requested downloadable archive will continue to run on the server side. When complete, and email will be sent to the email address provided in the initial request with a link to a file to download. In addition to this two step workflow, there is also an option for users who wish to download a single CSV file in direct response to an API request. The .csv format may be used to download a CSV directly. This feature is restricted to use with only a single POINT, for a single YEAR at a time.

Request URL

GET|POST /api/nsrdb/v2/solar/full-disc-download.format?parameters

Request Parameters

NOTE: when using POST to submit a request the api_key must still be included as a query parameter in the url. All other parameters may be included in a POST request as part of the payload.

Response Fields

The response is composed of service-related informational fields and the results of the data query.

Data File Format

Generated data files are formatted in accordance with the Standard Time Series Data File Format. This file format has been developed to support SAM and other NREL models and is documented fully in this PDF. More information on SAM file formats available on the SAM weather page.

Examples

JSON Output Format

{
    "inputs": {
        "body": {},
        "params": {},
        "query": {
            "api_key": "{{API_KEY}}",
            "attributes": "alpha,aod,ghi,dni,dhi",
            "names": "2019",
            "utc": "true",
            "leap_day": "true",
            "interval": "10",
            "email": "user@company.com",
            "wkt": "POINT(-179.99 -15.94)"
        }
    },
    "metadata": {
        "version": "2.0.0",
        "resultset": {
            "count": 1
        }
    },
    "status": 200,
    "outputs": {
        "message": "File generation in progress. An email will be sent to user@company.com when the download is ready.",
        "downloadUrl": "https://mapfiles.nrel.gov/data/solar/332e3704bbdc119e0fb9c6bdafbce0eb.zip"
    },
    "errors": []
}

CSV Output Format

Direct streaming of CSV data is supported for single location, single year only. The following response example is truncated after the first few rows of data.

Source,Location ID,City,State,Country,Latitude,Longitude,Time Zone,Elevation,Local Time Zone,Clearsky DHI Units,Clearsky DNI Units,Clearsky GHI Units,Dew Point Units,DHI Units,DNI Units,GHI Units,Solar Zenith Angle Units,Temperature Units,Pressure Units,Relative Humidity Units,Precipitable Water Units,Wind Direction Units,Wind Speed,Cloud Type -15,Cloud Type 0,Cloud Type 1,Cloud Type 2,Cloud Type 3,Cloud Type 4,Cloud Type 5,Cloud Type 6,Cloud Type 7,Cloud Type 8,Cloud Type 9,Cloud Type 10,Cloud Type 11,Cloud Type 12,Fill Flag 0,Fill Flag 1,Fill Flag 2,Fill Flag 3,Fill Flag 4,Fill Flag 5,Surface Albedo Units,Version
NSRDB,0,-,b'None',b'None',-15.94,-179.99,0,0,12,w/m2,w/m2,w/m2,c,w/m2,w/m2,w/m2,Degree,c,mbar,%,cm,Degrees,m/s,N/A,Clear,Probably Clear,Fog,Water,Super-Cooled Water,Mixed,Opaque Ice,Cirrus,Overlapping,Overshooting,Unknown,Dust,Smoke,N/A,Missing Image,Low Irradiance,Exceeds Clearsky,Missing CLoud Properties,Rayleigh Violation,N/A,unknown
Year,Month,Day,Hour,Minute,Alpha,AOD,GHI,DNI,DHI
2019,1,1,0,0,1.02,0.0102,0,0,0
2019,1,1,0,45,1.02,0.0111,0,0,0
2019,1,1,1,30,1.02,0.0111,0,0,0
2019,1,1,2,15,1.04,0.0122,0,0,0
2019,1,1,3,0,1.06,0.013000000000000001,0,0,0
2019,1,1,3,45,1.07,0.0134,0,0,0
2019,1,1,4,30,1.07,0.0134,0,0,0

POST request example in Python

import requests

url = "http://developer.nrel.gov/api/nsrdb/v2/solar/full-disc-download.json?api_key=yourapikeygoeshere"

payload = "api_key={{API_KEY}}&attributes=alpha,aod,ghi,dni,dhi&names=2019&utc=true&leap_day=true&interval=10&email=user@company.com&wkt=POINT(-179.99 -15.94)"

headers = {
    'content-type': "application/x-www-form-urlencoded",
    'cache-control': "no-cache"
}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Rate Limits

Rate limits for this application are significantly less than the standard rate limits for developer.nrel.gov. This decrease in the limit is required as the data provided through this service is significantly more computationally intensive to generate and provide. These rate limits are carefully calculated to allow all users the maximum throughput that our servers can sustain.

There are several levels of rate limiting for this service. The first limit determines how many requests a given user can make per 24 hour period. For requests utilizing the .csv format this rate limit is set at 5000 a day at a frequency of no more than 1 per second. For all other requests this limit is set at 1000 requests per day at a frequency of no more than 1 every 2 seconds.

Secondly each user is limited to 20 in-flight requests at any given time.

In addition, the service has a fail-safe mechanism to prevent significant performance decreases that can be caused by unexpectedly high usage of the service. This limit will cause the service to stop accepting requests when the queue reaches a point where additional requests will significantly lower server performance. When this limit is hit, the service will error with a message describing that the request queue is full.

For some tips and tricks to maximize data downloads please read the guide here.

Contact

For questions about the API or the data models please contact nsrdb@nrel.gov

Errors

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