The Offshore Hawaii Dataset is a 21-year wind resource dataset for offshore Hawaii. Produced in 2020, this data set replaces NREL's Wind Integration National Dataset (WIND) Toolkit for offshore Hawaii, which was produced and released publicly in 2013 and is currently the principal data set used by stakeholders for wind resource assessment in the continental United States. Both the WIND Toolkit and this new data set are created using the Weather Research and Forecasting (WRF) numerical weather prediction model (NWP).
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.
The Offshore Hawaii shares many of the same attributes as the WIND Toolkit, including 5-minute time resolution and 2-kilometer horizontal spatial resolution. However, the new data set improves upon - the WIND Toolkit through:
GET /api/wind-toolkit/v2/wind/offshore-hawaii-download.format?parameters
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 point string
Default: None
|
A well-known text (WKT) representation of the geometry for which to extract data. May be a point or polygon geometry. |
attributes | Yes |
Type: comma delimited string array
Default: None
Options: friction_velocity_2m, inversemoninobukhovlength_2m, skin_temperature, roughness_length, surface_heat_flux, surface_sea_temperature, pressure_0m, pressure_100m, pressure_200m, pressure_300m, relativehumidity_2m, precipitationrate_0m, temperature_100m, turbulent_kinetic_energy_100m, winddirection_100m, windspeed_100m, temperature_10m, turbulent_kinetic_energy_10m, winddirection_10m, windspeed_10m, temperature_120m, turbulent_kinetic_energy_120m, winddirection_120m, windspeed_120m, temperature_140m, turbulent_kinetic_energy_140m, winddirection_140m, windspeed_140m, temperature_160m, turbulent_kinetic_energy_160m, winddirection_160m, windspeed_160m, temperature_180m, turbulent_kinetic_energy_180m, winddirection_180m, windspeed_180m, temperature_200m, turbulent_kinetic_energy_200m, winddirection_200m, windspeed_200m, temperature_20m, turbulent_kinetic_energy_20m, winddirection_20m, windspeed_20m, temperature_220m, turbulent_kinetic_energy_220m, winddirection_220m, windspeed_220m, temperature_240m, turbulent_kinetic_energy_240m, winddirection_240m, windspeed_240m, temperature_260m, turbulent_kinetic_energy_260m, winddirection_260m, windspeed_260m, temperature_280m, turbulent_kinetic_energy_280m, winddirection_280m, windspeed_280m, temperature_2m, temperature_300m, turbulent_kinetic_energy_300m, winddirection_300m, windspeed_300m, temperature_400m, turbulent_kinetic_energy_400m, winddirection_400m, windspeed_400m, temperature_40m, turbulent_kinetic_energy_40m, winddirection_40m, windspeed_40m, temperature_500m, turbulent_kinetic_energy_500m, winddirection_500m, windspeed_500m, temperature_60m, turbulent_kinetic_energy_60m, winddirection_60m, windspeed_60m, temperature_80m, turbulent_kinetic_energy_80m, winddirection_80m, windspeed_80m
|
Each specified attribute will be returned as a column in the resultant CSV download. |
names | Yes |
Type: comma delimited integer array
Default: None
Options: 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020
|
The year(s) for which data should be extracted. |
interval | No |
Type: integer
Default: 5
Options: 5, 15, 30, 60
|
Desired data timestep resolution in minutes. |
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. |
full_name | No |
Type: string
Default: None
|
The full name of the user requesting data. |
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. |
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 |
GET /api/wind-toolkit/v2/wind/offshore-hawaii-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": {
"body": {},
"params": {},
"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": []
}
GET /api/wind-toolkit/v2/wind/offshore-hawaii-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
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.
For questions about the API or the data models please contact WindToolkit@nrel.gov
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. |