Skip to content

Commit 5c03e14

Browse files
PjEdwardsPjEdwards
committed
2018 and puerto rico data
1 parent 8457274 commit 5c03e14

File tree

3 files changed

+300
-2
lines changed

3 files changed

+300
-2
lines changed

‎source/docs/solar/nsrdb/psm3_data_download.html.md.erb

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ _NOTE: when using POST to submit a request the api_key must still be inlcuded as
6969
<td class="doc-parameter-value">
7070
<div class="doc-parameter-value-field"><strong>Type:</strong> comma delimited string array</div>
7171
<div class="doc-parameter-value-field"><strong>Default:</strong> None</div>
72-
<div class="doc-parameter-value-field"><strong>Options:</strong> <em>1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017</em></div>
72+
<div class="doc-parameter-value-field"><strong>Options:</strong> <em>1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018</em></div>
7373
</td>
7474
<td class="doc-parameter-description">The year(s) for which data should be extracted.</td>
7575
</tr>

‎source/docs/solar/nsrdb/psm3_tmy_data_download.html.md.erb

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ _NOTE: when using POST to submit a request the api_key must still be inlcuded as
6969
<td class="doc-parameter-value">
7070
<div class="doc-parameter-value-field"><strong>Type:</strong> comma delimited string array</div>
7171
<div class="doc-parameter-value-field"><strong>Default:</strong> None</div>
72-
<div class="doc-parameter-value-field"><strong>Options:</strong> <em>tmy, tmy-2016, tmy-2017, tdy-2017, tgy-2017</em></div>
72+
<div class="doc-parameter-value-field"><strong>Options:</strong> <em>tmy, tmy-2016, tmy-2017, tdy-2017, tgy-2017. tmy-2018, tdy-2018, tgy-2018</em></div>
7373
</td>
7474
<td class="doc-parameter-description">The TMY dataset for which data should be extracted. 'tmy' will return the most recently generated TMY file.</td>
7575
</tr>

‎source/docs/solar/nsrdb/puerto_rico_data_download.html.md.erb

Lines changed: 298 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,298 @@
1+
---
2+
title: Puerto Rico SHR (Simulated High Resolution)
3+
summary: Collect and download, as CSV, a configurable set of solar and meteoroligical data fields from The NSRDB. The National Solar Radiation Database (NSRDB) is a serially complete collection of hourly and half-hourly values of the three most common measurements of solar radiation—global horizontal, direct normal, and diffuse horizontal irradiance—and meteorological data. These data have been collected at a sufficient number of locations and temporal and spatial scales to accurately represent regional solar radiation climates. Read more about the datasets at [https://nsrdb.nrel.gov](https://nsrdb.nrel.gov)
4+
detail: This API is capabale 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 either a link to a file to download, or in the case of a very, very large archive, a link to more detailed instructions for using Globus to complete the 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 <em>.csv</em> 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.
5+
url: /api/nsrdb_api/solar/nsrdb_puerto_rico_download
6+
---
7+
8+
# <%= current_page.data.title %> <span class="url">(<%= current_page.data.url %>)</span>
9+
<%= current_page.data.summary %>
10+
11+
<%= current_page.data.detail %>
12+
13+
<ul id="toc"></ul>
14+
15+
## Request URL
16+
17+
<pre>GET|POST <%= current_page.data.url %><em>.format?parameters</em></pre>
18+
19+
## Request Parameters
20+
_NOTE: when using POST to submit a request the api_key must still be inlcuded as a query parameter in the url. All other parameters may be included in a POST request as part of the payload._
21+
22+
<table border="0" cellpadding="0" cellspacing="0" class="doc-parameters">
23+
<thead>
24+
<tr>
25+
<th class="doc-parameters-name" scope="col">Parameter</th>
26+
<th class="doc-parameters-required" scope="col">Required</th>
27+
<th class="doc-parameters-value" scope="col">Value</th>
28+
<th class="doc-parameters-description" scope="col">Description</th>
29+
</tr>
30+
</thead>
31+
<tbody>
32+
<tr>
33+
<th class="doc-parameter-name" scope="row">api_key</th>
34+
<td class="doc-parameter-required">Yes</td>
35+
<td class="doc-parameter-value">
36+
<div class="doc-parameter-value-field"><strong>Type:</strong> string</div>
37+
<div class="doc-parameter-value-field"><strong>Default:</strong> None</div>
38+
</td>
39+
<td class="doc-parameter-description">
40+
<p>Your developer API key. See <a href="/docs/api-key/">API keys</a> for more information.</p>
41+
</td>
42+
</tr>
43+
<tr>
44+
<th class="doc-parameter-name" scope="row">wkt</th>
45+
<td class="doc-parameter-required">Yes</td>
46+
<td class="doc-parameter-value">
47+
<div class="doc-parameter-value-field"><strong>Type:</strong> well-known text string</div>
48+
<div class="doc-parameter-value-field"><strong>Default:</strong> None</div>
49+
</td>
50+
<td class="doc-parameter-description">
51+
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.
52+
</td>
53+
</tr>
54+
<tr>
55+
<th class="doc-parameter-name" scope="row">attributes</th>
56+
<td class="doc-parameter-required">No</td>
57+
<td class="doc-parameter-value">
58+
<div class="doc-parameter-value-field"><strong>Type:</strong> comma delimited string array</div>
59+
<div class="doc-parameter-value-field"><strong>Default:</strong> Returns ALL</div>
60+
<div class="doc-parameter-value-field"><strong>Options:</strong> <em>air_temperature, clearsky_dhi, clearsky_dni, clearsky_ghi, dhi, dni, ghi, solar_zenith_angle, surface_albedo, surface_pressure, total_precipitable_water, wind_speed</em></div>
61+
</td>
62+
<td class="doc-parameter-description">
63+
Each specified attribute(*) will be returned as a column in the resultant CSV download.<br/><br/>
64+
</td>
65+
</tr>
66+
<tr>
67+
<th class="doc-parameter-name" scope="row">names</th>
68+
<td class="doc-parameter-required">Yes</td>
69+
<td class="doc-parameter-value">
70+
<div class="doc-parameter-value-field"><strong>Type:</strong> comma delimited string array</div>
71+
<div class="doc-parameter-value-field"><strong>Default:</strong> None</div>
72+
<div class="doc-parameter-value-field"><strong>Options:</strong> <em>1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017</em></div>
73+
</td>
74+
<td class="doc-parameter-description">The year(s) for which data should be extracted.</td>
75+
</tr>
76+
<tr>
77+
<th class="doc-parameter-name" scope="row">utc</th>
78+
<td class="doc-parameter-required">No</td>
79+
<td class="doc-parameter-value">
80+
<div class="doc-parameter-value-field"><strong>Type:</strong> true or false</div>
81+
<div class="doc-parameter-value-field"><strong>Default:</strong> true</div>
82+
</td>
83+
<td class="doc-parameter-description">
84+
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).
85+
</td>
86+
</tr>
87+
<tr>
88+
<th class="doc-parameter-name" scope="row">leap_day</th>
89+
<td class="doc-parameter-required">No</td>
90+
<td class="doc-parameter-value">
91+
<div class="doc-parameter-value-field"><strong>Type:</strong> true or false</div>
92+
<div class="doc-parameter-value-field"><strong>Default:</strong> false</div>
93+
</td>
94+
<td class="doc-parameter-description">
95+
Pass true to retrieve data including leap day (where appropriate). Pass false to retrieve data excluding leap day.
96+
</td>
97+
</tr>
98+
<tr>
99+
<th class="doc-parameter-name" scope="row">interval</th>
100+
<td class="doc-parameter-required">Yes</td>
101+
<td class="doc-parameter-value">
102+
<div class="doc-parameter-value-field"><strong>Type:</strong> 5, 30 or 60</div>
103+
<div class="doc-parameter-value-field"><strong>Default:</strong> None</div>
104+
</td>
105+
<td class="doc-parameter-description">
106+
This value determines data resolution. 5 minute, 30 minute, or 60 minute intervals are available.
107+
</td>
108+
</tr>
109+
<tr>
110+
<th class="doc-parameter-name" scope="row">full_name</th>
111+
<td class="doc-parameter-required">No</td>
112+
<td class="doc-parameter-value">
113+
<div class="doc-parameter-value-field"><strong>Type:</strong> string</div>
114+
<div class="doc-parameter-value-field"><strong>Default:</strong> None</div>
115+
</td>
116+
<td class="doc-parameter-description">The full name of the user requesting data.</td>
117+
</tr>
118+
<tr>
119+
<th class="doc-parameter-name" scope="row">email</th>
120+
<td class="doc-parameter-required">Yes</td>
121+
<td class="doc-parameter-value">
122+
<div class="doc-parameter-value-field"><strong>Type:</strong> email string</div>
123+
<div class="doc-parameter-value-field"><strong>Default:</strong> None</div>
124+
</td>
125+
<td class="doc-parameter-description">
126+
An active email for the user requesting data. This email will be used to deliver the extracted data.
127+
</td>
128+
</tr>
129+
<tr>
130+
<th class="doc-parameter-name" scope="row">affiliation</th>
131+
<td class="doc-parameter-required">No</td>
132+
<td class="doc-parameter-value">
133+
<div class="doc-parameter-value-field"><strong>Type:</strong> string</div>
134+
<div class="doc-parameter-value-field"><strong>Default:</strong> None</div>
135+
</td>
136+
<td class="doc-parameter-description">
137+
The organization with which the user requesting the data is affiliated.
138+
</td>
139+
</tr>
140+
<tr>
141+
<th class="doc-parameter-name" scope="row">reason</th>
142+
<td class="doc-parameter-required">No</td>
143+
<td class="doc-parameter-value">
144+
<div class="doc-parameter-value-field"><strong>Type:</strong> string</div>
145+
<div class="doc-parameter-value-field"><strong>Default:</strong> None</div>
146+
</td>
147+
<td class="doc-parameter-description">The reason that the user is requesting the data.</td>
148+
</tr>
149+
<tr>
150+
<th class="doc-parameter-name" scope="row">mailing_list</th>
151+
<td class="doc-parameter-required">No</td>
152+
<td class="doc-parameter-value">
153+
<div class="doc-parameter-value-field"><strong>Type:</strong> true or false</div>
154+
<div class="doc-parameter-value-field"><strong>Default:</strong> false</div>
155+
</td>
156+
<td class="doc-parameter-description">
157+
Pass true to add the email address to our list of recipients for the NSRDB mailing list.
158+
</td>
159+
</tr>
160+
</tbody>
161+
</table>
162+
163+
## Response Fields
164+
165+
The response is composed of service-related informational fields and the results of the data query.
166+
167+
<table border="0" cellpadding="0" cellspacing="0" class="doc-parameters">
168+
<thead>
169+
<tr>
170+
<th class="doc-parameters-name" scope="col">Field</th>
171+
<th class="doc-parameters-value" scope="col">Value</th>
172+
<th class="doc-parameters-description" scope="col">Description</th>
173+
</tr>
174+
</thead>
175+
<tbody>
176+
<tr>
177+
<th class="doc-parameter-name" scope="row">errors</th>
178+
<td class="doc-parameter-value">
179+
<div class="doc-parameter-value-field"><strong>Type:</strong> string array</div>
180+
</td>
181+
<td class="doc-parameter-description">
182+
<p>A list of error messages</p>
183+
</td>
184+
</tr>
185+
<tr>
186+
<th class="doc-parameter-name" scope="row">inputs</th>
187+
<td class="doc-parameter-value">
188+
<div class="doc-parameter-value-field"><strong>Type:</strong> Object Hash</div>
189+
</td>
190+
<td class="doc-parameter-description">Key: Value pairs representing all input parameters</td>
191+
</tr>
192+
<tr>
193+
<th class="doc-parameter-name" scope="row">outputs</th>
194+
<td class="doc-parameter-value">
195+
<div class="doc-parameter-value-field"><strong>Type:</strong> Object Hash</div>
196+
</td>
197+
<td class="doc-parameter-description">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 <code>email</code> input field when the download is ready</td>
198+
</tr>
199+
</tbody>
200+
</table>
201+
202+
## Data File Format
203+
204+
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 avaialable on [the SAM weather page](https://sam.nrel.gov/weather).
205+
206+
## Examples
207+
208+
### JSON Output Format
209+
210+
<div class="doc-example-url"><code>GET <%= current_page.data.url %>.json?api_key=DEMO_KEY&names=2016&[email protected]&interval=60&wkt=POINT(-66.1057 18.4655)</code></div>
211+
212+
```json
213+
{
214+
"errors": [],
215+
"inputs": {
216+
"names": [
217+
2016
218+
],
219+
"email": "[email protected]",
220+
"interval": 60,
221+
"wkt": "POINT(-66.1057 18.4655)"
222+
},
223+
"outputs": {
224+
"message": "File generation in progress. An email will be sent to [email protected] when the download is ready."
225+
}
226+
}
227+
```
228+
229+
230+
### CSV Output Format
231+
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.
232+
233+
<div class="doc-example-url"><code>GET <%= current_page.data.url %>.csv?api_key=DEMO_KEY&names=2016&[email protected]&interval=60&wkt=POINT(-66.1057 18.4655)</code></div>
234+
235+
```csv
236+
Source,Location ID,City,State,Country,Latitude,Longitude,Time Zone,Elevation,Local Time Zone,Clearsky DHI Units,Clearsky DNI Units,Clearsky GHI Units,DHI Units,DNI Units,GHI Units,Solar Zenith Angle Units,Pressure Units,Precipitable Water Units,Wind Speed,Version
237+
NSRDB,1601,-,PR,Puerto Rico,18.459999084472656,-66.11000061035156,-4,9,-4,w/m2,w/m2,w/m2,w/m2,w/m2,w/m2,Degree,mbar,mm,m/s,unknown
238+
Year,Month,Day,Hour,Minute,Air Temerature,Clearsky DHI,Clearsky DNI,Clearsky GHI,DHI,DNI,GHI,Solar Zenith Angle,Albedo,Pressure,Precipitable Water,Wind Speed
239+
2016,1,1,0,5,25,0,0,0,0,0,0,89.0,0.082,1020.0,3.286,5
240+
2016,1,1,1,5,25,0,0,0,0,0,0,89.0,0.082,1020.0,2.852,5
241+
2016,1,1,2,5,25,0,0,0,0,0,0,89.0,0.082,1020.0,2.5340000000000003,5
242+
2016,1,1,3,5,25,0,0,0,0,0,0,89.0,0.082,1020.0,2.316,5
243+
2016,1,1,4,5,25,0,0,0,0,0,0,89.0,0.082,1020.0,2.1350000000000002,4
244+
2016,1,1,5,5,24,0,0,0,0,0,0,89.0,0.082,1020.0,1.999,4
245+
2016,1,1,6,5,24,0,0,0,0,0,0,89.0,0.082,1020.0,1.926,4
246+
2016,1,1,7,5,25,16,78,18,16,78,18,88.26,0.082,1020.0,1.923,4
247+
2016,1,1,8,5,26,61,594,206,61,594,206,75.91,0.082,1021.7,1.973,4
248+
2016,1,1,9,5,27,79,788,423,79,788,423,64.15,0.082,1030.0,2.081,4
249+
2016,1,1,10,5,27,89,876,606,89,876,606,53.800000000000004,0.082,1030.0,2.248,5
250+
```
251+
252+
### POST request example in Python
253+
254+
```python
255+
import requests
256+
257+
url = "http://developer.nrel.gov<%= current_page.data.url %>.json?api_key=yourapikeygoeshere"
258+
259+
payload = "names=2012&leap_day=false&interval=60&utc=false&full_name=Valued%2BUser&email=valued.user%40gmail.com&affiliation=NREL&mailing_list=true&reason=Academic&attributes=dhi%2Cdni%2Cwind_speed%2Cair_temperature&wkt=MULTIPOINT(-66.1057%2018.4655%2C-66.2057%2018.3655%2C-66.1157%2018.4655)"
260+
261+
headers = {
262+
'content-type': "application/x-www-form-urlencoded",
263+
'cache-control': "no-cache"
264+
}
265+
266+
response = requests.request("POST", url, data=payload, headers=headers)
267+
268+
print(response.text)
269+
```
270+
271+
<h2 id="rate-limits">Rate Limits</h2>
272+
273+
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.
274+
275+
There are two 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 <em>.csv</em> format this rate limit is set at 2000 a day at a frequency of no more than 1 per second. For all other requests this limit is set at 300 requests per day at a frequency of no more than 1 every 2 seconds.
276+
277+
In addition to this limit, the service has a secondary 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.
278+
279+
For some tips and tricks to maximize data downloads please read the guide [here](/docs/solar/nsrdb/guide).
280+
281+
<h2 id="errors">Errors</h2>
282+
283+
<p><a href="/docs/errors/">Standard errors</a> may be returned. In addition, the following service-specific errors may be returned:</p>
284+
285+
<table border="0" cellpadding="0" cellspacing="0" class="doc-parameters">
286+
<thead>
287+
<tr>
288+
<th class="doc-parameters-name" scope="col" style="width: 100px;">HTTP Status Code</th>
289+
<th class="doc-parameters-required" scope="col">Description</th>
290+
</tr>
291+
</thead>
292+
<tbody>
293+
<tr>
294+
<th class="doc-parameter-name" scope="row">400</th>
295+
<td class="doc-parameter-description">Bad Request: When required parameters are missing.</td>
296+
</tr>
297+
</tbody>
298+
</table>

0 commit comments

Comments
 (0)