From 17ba9bd8adaff3875c499e994684ca8d84f896e4 Mon Sep 17 00:00:00 2001 From: msherman32 <35711675+msherman32@users.noreply.github.com> Date: Fri, 27 Sep 2024 13:29:41 -0600 Subject: [PATCH] =?UTF-8?q?=F0=9F=8C=B4=20CV=20-=208338=20-=20Data=20Inges?= =?UTF-8?q?tion=20(#363)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * adding ncdb folder underneath solar * Adds guide and index * Modify to represent NCDB * Address changes to URL path --------- Co-authored-by: Michael Sherman Co-authored-by: Edwards, Paul --- source/docs/climate/index.html.md.erb | 9 + source/docs/climate/ncdb/guide.html.md.erb | 64 ++++ source/docs/climate/ncdb/index.html.md.erb | 17 + ...y-CONUS-v1-0-0-RCP4-5-download.html.md.erb | 312 ++++++++++++++++++ ...y-CONUS-v1-0-0-RCP8-5-download.html.md.erb | 311 +++++++++++++++++ 5 files changed, 713 insertions(+) create mode 100644 source/docs/climate/index.html.md.erb create mode 100644 source/docs/climate/ncdb/guide.html.md.erb create mode 100644 source/docs/climate/ncdb/index.html.md.erb create mode 100755 source/docs/climate/ncdb/ncdb-4km-Hourly-CONUS-v1-0-0-RCP4-5-download.html.md.erb create mode 100755 source/docs/climate/ncdb/ncdb-4km-Hourly-CONUS-v1-0-0-RCP8-5-download.html.md.erb diff --git a/source/docs/climate/index.html.md.erb b/source/docs/climate/index.html.md.erb new file mode 100644 index 00000000..77451120 --- /dev/null +++ b/source/docs/climate/index.html.md.erb @@ -0,0 +1,9 @@ +--- +title: Climate +summary: Access data services that provide access to climate resource data. +--- + +# <%= current_page.data.title %> +<%= current_page.data.summary %> + +<%= partial("layouts/child_links") %> diff --git a/source/docs/climate/ncdb/guide.html.md.erb b/source/docs/climate/ncdb/guide.html.md.erb new file mode 100644 index 00000000..afac2caa --- /dev/null +++ b/source/docs/climate/ncdb/guide.html.md.erb @@ -0,0 +1,64 @@ +--- +title: Data Download Guide +summary: Tips and tricks for getting the most out of the API + +--- + +## Data Download Usage Guide + +We often receive requests from users interested in downloading larger segments of the data than are supported by the API. It is important to understand that these datasets are large. Currently our storage archive contains hundreds of terabytes of data and is constantly growing! In order to reliably serve dynamic segments of a dataset of this size to a growing community of users we have calculated the maximum capacity our server hardware can sustain. We use this physical capacity to determine our API rate limits. For users insterested in accessing bulk data the full datasets are available via the Registry of Open Data on AWS at [https://registry.opendata.aws/nrel-pds-ncdb/](https://registry.opendata.aws/nrel-pds-ncdb/). + +The API is restricted in several ways including the number of simultaneous requests a single user can make, the number of requests a single user can make in a 24 hour period, as well as in the maximum size of a single request. The API rate limits are set at: + +> 1000 requests per day +> 1 request every 2 seconds +> 20 requests in process at once + +For downloading directly via CSV there are separate rate limits. This is due to the fact that it is only possible to download a single site for a single year via the CSV endpoint, therefor these requests are always quite small by comparison: + +> 5000 requests per day +> 1 request per second +> 20 requests in process at once + +The size limit per each single request is determined by the number of total attributes in each request. The maximum weight of each request is **5000000**. The calculation for determining the weight of each request is: + +> site-count\*attribute-count\*year-count\*data-intervals-per-year + + * **site-count** is derived from the WKT value submitted and can be retrieved using the [site_count](/docs/solar/nsrdb/site_count) API endpoint. + * **attribute-count** is equal to the number of attributes requested + * **year-count** is equal to the number of years requested + * **data-intervals-per-year** is *((60/interval)\*24\*365)* where interval is the interval requested + +To maximize a single request simply minimize the variables wherever possible. For example by requesting half as many attributes one can request twice as many years (or sites) worth of data. + +Imagine a use case where one wanted to download all Climate data for the state of Texas. The first step would be to refine the request down to the least number of attributes, years, and intervals possible. From that one could determine the number of sites that could be requested in a single request. By experimenting with the site_count endpoint a polygon size could be identified that intersects close to that many sites. Using that polygon size create a grid that covers all of Texas. The final step would be to write a script that invokes the API once for every required grid cell at a rate of no more than 1 every 2 seconds and no more than 20 in process at a time. If more than 1000 requests are required the script will have to be continued across multiple days. + + +In cases where a very large WKT value is required, e.g. downloading the maximum number of broadly spaced points at a time using a MULTIPOINT wkt, it is possible to POST a request to the API providing the WKT params in the payload. Here is an example of a Python script that uses this variation: + +```python +import requests + +url = "http://developer.nrel.gov/api/climate/ncdb/v2/climate/ncdb-4km-Hourly-CONUS-v1-0-0-RCP8-5-download.json?api_key=yourapikeygoeshere" + +payload = "names=2012&leap_day=false&interval=60&utc=false&full_name=Honored%2BUser&email=honored.user%40gmail.com&affiliation=NREL&mailing_list=true&reason=Academic&attributes=dhi%2Cdni%2Cwind_speed&wkt=MULTIPOINT(-106.22%2032.9741%2C-106.18%2032.9741%2C-106.1%2032.9741)" + +headers = { + 'content-type': "application/x-www-form-urlencoded", + 'cache-control': "no-cache" +} + +response = requests.request("POST", url, data=payload, headers=headers) + +print(response.text) +``` + +And a CURL example of the same + +```shell +curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -H "Cache-Control: no-cache" -d 'names=2009&leap_day=false&interval=60&utc=false&full_name=Honored%2BUser&email=user@company.com&affiliation=NREL&mailing_list=true&reason=Academic&attributes=dhi%2Cdni%2Cwind_speed&wkt=MULTIPOINT(-106.22 32.9741%2C-106.18 32.9741%2C-106.1 32.9741%2C-106.06 32.9741)' "http://developer.nrel.gov/api/solar/psm3-5min-download.json?api_key=yourapikeygoeshere" +``` + +

Contact

+ +

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

diff --git a/source/docs/climate/ncdb/index.html.md.erb b/source/docs/climate/ncdb/index.html.md.erb new file mode 100644 index 00000000..13e24279 --- /dev/null +++ b/source/docs/climate/ncdb/index.html.md.erb @@ -0,0 +1,17 @@ +--- +title: National Climate Database Downloads +summary: Freely available downloads of The National Climate Database. + +--- + +# <%= current_page.data.title %> +<%= current_page.data.summary %> + +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. Currently, the NCDB covers the contiguous United States and provides 4-km and hourly resolution climate projections under two Representative Concentration Pathways (RCP4.5 and RCP8.5) for the years from 2006-2100. The data are publicly available at no cost to the user. These API provide access to downloading the data. Other options are detailed [here](https://climate.nrel.gov/data-sets/how-to-access-data) + +<%= partial("layouts/child_links") %> + + +## Contact + +

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

diff --git a/source/docs/climate/ncdb/ncdb-4km-Hourly-CONUS-v1-0-0-RCP4-5-download.html.md.erb b/source/docs/climate/ncdb/ncdb-4km-Hourly-CONUS-v1-0-0-RCP4-5-download.html.md.erb new file mode 100755 index 00000000..f331abfa --- /dev/null +++ b/source/docs/climate/ncdb/ncdb-4km-Hourly-CONUS-v1-0-0-RCP4-5-download.html.md.erb @@ -0,0 +1,312 @@ +--- +title: "CONUS 2006-2100 60-minute, 4km, RCP4.5" +summary: "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." +detail: "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](https://climate.nrel.gov)." +url: /api/climate/ncdb/v2/climate/ncdb-4km-Hourly-CONUS-v1-0-0-RCP4-5-download +--- + +# <%= current_page.data.title %> (<%= current_page.data.url %>) +<%= current_page.data.summary %> + +<%= current_page.data.detail %> + + + +## Request URL + +
GET|POST <%= current_page.data.url %>.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._ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterRequiredValueDescription
api_keyYes +
Type: string
+
Default: None
+ 		+

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

+
wktYes +
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. +
attributesNo +
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. +
namesYes +
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.
utcNo +
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_dayNo +
Type: true or false
+
Default: false
+ 		+ Pass true to retrieve data including leap day (where appropriate). Pass false to retrieve data excluding leap day. +
intervalYes +
Type:60
+
Default: None
+ 		+ This value determines data resolution. Either 60 minute intervals are available. +
full_nameNo +
Type: string
+
Default: None
+ 		The full name of the user requesting data.
emailYes +
Type: email string
+
Default: None
+ 		+ An active email for the user requesting data. This email will be used to deliver the extracted data. +
affiliationNo +
Type: string
+
Default: None
+ 		+ The organization with which the user requesting the data is affiliated. +
reasonNo +
Type: string
+
Default: None
+ 		The reason that the user is requesting the data.
mailing_listNo +
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. + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldValueDescription
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](https://sam.nrel.gov/) and other NREL models and is documented fully in [this PDF](https://sam.nrel.gov/sites/default/files/content/documents/pdf/wfcsv.pdf). More information on SAM file formats available on [the SAM weather page](https://sam.nrel.gov/weather). + +## Examples +Examples may not reflect this specific dataset. + +### JSON Output Format + +
GET <%= current_page.data.url %>.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
+ +```JSON +{ + "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 <%= current_page.data.url %>.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
+ +```csv +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 + +```python +import requests + +url = "http://developer.nrel.gov<%= current_page.data.url %>.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](/docs/rate-limits){:target="_blank"} 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](/docs/climate/ncdb/guide/). + +

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 CodeDescription
400Bad Request: When required parameters are missing.
diff --git a/source/docs/climate/ncdb/ncdb-4km-Hourly-CONUS-v1-0-0-RCP8-5-download.html.md.erb b/source/docs/climate/ncdb/ncdb-4km-Hourly-CONUS-v1-0-0-RCP8-5-download.html.md.erb new file mode 100755 index 00000000..0ff27c83 --- /dev/null +++ b/source/docs/climate/ncdb/ncdb-4km-Hourly-CONUS-v1-0-0-RCP8-5-download.html.md.erb @@ -0,0 +1,311 @@ +--- +title: "CONUS 2006-2100 60-minute, 4km, RCP8.5" +summary: "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." +detail: "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](https://climate.nrel.gov)." +url: /api/climate/ncdb/v2/climate/ncdb-4km-Hourly-CONUS-v1-0-0-RCP8-5-download +--- + +# <%= current_page.data.title %> (<%= current_page.data.url %>) +<%= current_page.data.summary %> + +<%= current_page.data.detail %> + + + +## Request URL + +
GET|POST <%= current_page.data.url %>.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._ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterRequiredValueDescription
api_keyYes +
Type: string
+
Default: None
+ 		+

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

+
wktYes +
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. +
attributesNo +
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. +
namesYes +
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.
utcNo +
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_dayNo +
Type: true or false
+
Default: false
+ 		+ Pass true to retrieve data including leap day (where appropriate). Pass false to retrieve data excluding leap day. +
intervalYes +
Type:60
+
Default: None
+ 		+ This value determines data resolution. Either 60 minute intervals are available. +
full_nameNo +
Type: string
+
Default: None
+ 		The full name of the user requesting data.
emailYes +
Type: email string
+
Default: None
+ 		+ An active email for the user requesting data. This email will be used to deliver the extracted data. +
affiliationNo +
Type: string
+
Default: None
+ 		+ The organization with which the user requesting the data is affiliated. +
reasonNo +
Type: string
+
Default: None
+ 		The reason that the user is requesting the data.
mailing_listNo +
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. + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldValueDescription
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](https://sam.nrel.gov/) and other NREL models and is documented fully in [this PDF](https://sam.nrel.gov/sites/default/files/content/documents/pdf/wfcsv.pdf). More information on SAM file formats available on [the SAM weather page](https://sam.nrel.gov/weather). + +## Examples +Examples may not reflect this specific dataset. + +### JSON Output Format + +
GET <%= current_page.data.url %>.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
+ +```JSON +{ + "inputs": { + "query": { + "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 <%= current_page.data.url %>.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
+ +```csv +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 + +```python +import requests + +url = "http://developer.nrel.gov<%= current_page.data.url %>.json?api_key=yourapikeygoeshere" + +payload = "api_key={{API_KEY}}&attributes=winddirection_180m&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](/docs/rate-limits){:target="_blank"} 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](/docs/climate/ncdb/guide/). + +

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 CodeDescription
400Bad Request: When required parameters are missing.