Developer Network NREL NREL Developer Network

CONUS 2006-2100 60-minute, 4km, RCP4.5 (/api/climate/ncdb/v2/climate/ncdb-4km-Hourly-CONUS-v1-0-0-RCP4-5-download)

The National Climate Database (NCDB) is a high-resolution, bias-corrected climate dataset including global horizontal irradiance, direct normal irradiance, and diffuse horizontal irradiance, as well as other meteorological data.

The NCDB is developed using a statistical downscaling approach with Regional Climate Model (RCM)-based climate projections obtained from the North American Coordinated Regional Climate Downscaling Experiment (NA-CORDEX; https://na-cordex.org/). 0.22⁰ daily climate projections simulated by the Canadian Regional Climate Model 4 (CanRCM4) forced by the second-generation Canadian Earth System Model (CanESM2) for two Representative Concentration Pathways (RCP4.5 or moderate emissions scenario and RCP8.5 or highest baseline emission scenario) are selected as inputs to the statistical downscaling models. The National Solar Radiation Database (NSRDB) (Sengupta et al. 2018) is used to build and calibrate the statistical model. For more details please visit the NCDB.

Request URL

GET|POST /api/climate/ncdb/v2/climate/ncdb-4km-Hourly-CONUS-v1-0-0-RCP4-5-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.

Parameter Required Value Description
api_key Yes
Type: string
Default: None

Your developer API key. See API keys for more information.

wkt Yes
Type: well-known text string
Default: None
A well-known text (WKT) representation of the geometry for which to extract data. May be a point, multipoint, or polygon geometry. When a point is passed the site nearest to that point is used. When a multipoint is passed the site nearest each point is used. This can be useful for downloading multiple sites in a single request when those sites are geographically distant from each other. When a polygon is passed all sites that intersect with the given polygon are used.
attributes No
Type: comma delimited string array
Default: Returns ALL
Options: air_temperature, dhi, dni, ghi, solar_zenith_angle, wind_speed.
Each specified attribute(*) will be returned as a column in the resultant CSV download.
names Yes
Type: comma delimited string array
Default: None
Options: 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025, 2026, 2027, 2028, 2029, 2030, 2031, 2032, 2033, 2034, 2035, 2036, 2037, 2038, 2039, 2040, 2041, 2042, 2043, 2044, 2045, 2046, 2047, 2048, 2049, 2050, 2051, 2052, 2053, 2054, 2055, 2056, 2057, 2058, 2059, 2060, 2061, 2062, 2063, 2064, 2065, 2066, 2067, 2068, 2069, 2070, 2071, 2072, 2073, 2074, 2075, 2076, 2077, 2078, 2079, 2080, 2081, 2082, 2083, 2084, 2085, 2086, 2087, 2088, 2089, 2090, 2091, 2092, 2093, 2094, 2095, 2096, 2097, 2098, 2099, 2100.
The year(s) for which data should be extracted.
utc No
Type: true or false
Default: true
Pass true to retrieve data with timestamps in UTC. Pass false to retrieve data with timestamps converted to local time of data point (without daylight savings time).
leap_day No
Type: true or false
Default: false
Pass true to retrieve data including leap day (where appropriate). Pass false to retrieve data excluding leap day.
interval Yes
Type:60
Default: None
This value determines data resolution. Either 60 minute intervals are available.
full_name No
Type: string
Default: None
The full name of the user requesting data.
email Yes
Type: email string
Default: None
An active email for the user requesting data. This email will be used to deliver the extracted data.
affiliation No
Type: string
Default: None
The organization with which the user requesting the data is affiliated.
reason No
Type: string
Default: None
The reason that the user is requesting the data.
mailing_list No
Type: true or false
Default: false
Pass true to add the email address to our list of recipients for the NSRDB mailing list.

Response Fields

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

Field Value Description
errors
Type: string array

A list of error messages

inputs
Type: Object Hash
Key: Value pairs representing all input parameters
outputs
Type: Object Hash
Upon successful completion a message will be returned informing the user that file generation is in progress and an email will be sent to the address provided in the email input field when the download is ready

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

Examples may not reflect this specific dataset.

JSON Output Format

GET /api/climate/ncdb/v2/climate/ncdb-4km-Hourly-CONUS-v1-0-0-RCP4-5-download.json?wkt=POLYGON((-130.756145509839060 48.75520578942107,-130.75571635639668 48.75520578942107,-130.75571635639668 48.75485477666326,-130.75614550983906 48.75485477666326,-130.75614550983906 48.75520578942107))&attributes=winddirection_180m&names=2017&utc=false&leap_day=true&email=user@company.com
{
    "inputs": {
        "query": {
            "attributes": "winddirection_180m",
            "names": "2017",
            "utc": "false",
            "leap_day": "true",
            "email": "user@company.com",
            "wkt": "POLYGON((-130.756145509839060 48.75520578942107,-130.75571635639668 48.75520578942107,-130.75571635639668 48.75485477666326,-130.75614550983906 48.75485477666326,-130.75614550983906 48.75520578942107))"
        }
    },
    "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/wind/ebc9bbbc34f91c65ac50707d43176c6c.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.

GET /api/climate/ncdb/v2/climate/ncdb-4km-Hourly-CONUS-v1-0-0-RCP4-5-download.csv?wkt=POINT(-179.99 -15.94)&attributes=winddirection_180m&names=2017&utc=false&leap_day=true&email=user@company.com&api_key=DEMO_KEY
SiteID,Site Timezone,Data Timezone,Longitude,Latitude,Country
80,-9,-9,-130.756,48.75498,b'Canada'
Year,Month,Day,Hour,Minute,wind direction at 180m (deg)
2017,1,1,0,0,347.18
2017,1,1,0,5,347.3
2017,1,1,0,10,347.40000000000003
2017,1,1,0,15,347.52
2017,1,1,0,20,347.66
2017,1,1,0,25,347.79
2017,1,1,0,30,348
2017,1,1,0,35,348.18
2017,1,1,0,40,348.35

POST request example in Python

import requests

url = "http://developer.nrel.gov/api/climate/ncdb/v2/climate/ncdb-4km-Hourly-CONUS-v1-0-0-RCP4-5-download.json?api_key=yourapikeygoeshere"

payload = "api_key={{API_KEY}}&names=2017&utc=true&leap_day=true&interval=60&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:

HTTP Status Code Description
400 Bad Request: When required parameters are missing.
Help Improve this Content