USWTDB API

About the API

The USWTDB API allows for programmatic access to the U.S. Wind Turbine Database. Creation of the USWTDB API was meant to extend USWTDB visibility, expand user base, and create more productive internal workflows. The availability of the public API makes it possible for third party developers to build value-added applications leveraging the USWTDB. The API is HTTP-based (over SSL), and is compatible with any programming language that has an HTTP library (including directly in your browser). In this documentation, we'll show some examples of USWTDB API requests using cURL, a command-line tool and library for transferring data with different parameters and methods. cURL provides a generic way to demonstrate HTTP requests and responses and allows users to translate similar requests into their specific language of choice. The USWTDB API endpoint conforms to the design principles of Representational State Transfer (REST) and uses the JSON data format for responses. Retrieval of turbine data from the USWTDB API requires a standard GET request. Additional methods that submit or change USWTDB data require token-based authentication.

Resource Endpoint

Resource endpoints referenced in this documentation are only accessible via https and have a base path of https://eersc.usgs.gov/api/uswtdb/v1/. The base path, when combined with additional query parameters, constitute the full endpoint request. As an example, let’s say you wanted to get turbine level information from the USWTDB for turbine ID 3038257. To do this, you'd simply combine the base path https://eersc.usgs.gov/api/uswtdb/v1, with the desired resource /turbines, and append your query string ?&case_id=eq.3038257. The full request is shown below (if you don't have cURL, simply paste the URL in quotes below into your browser to see the response).

curl -i -X GET "https://eersc.usgs.gov/api/uswtdb/v1/turbines?&case_id=eq.3038257"

{
    "case_id": 3038257,
    "faa_ors": "19-022348",
    "faa_asn": "2011-WTE-22311-OE",
    "usgs_pr_id": 20977,
    "eia_id": null,
    "t_state": "IA",
    "t_county": "Story County",
    "t_fips": "19169",
    "p_name": "AG Land 4",
    "p_year": 2012,
    "p_tnum": 1,
    "p_cap": 1.6,
    "t_manu": "GE Wind",
    "t_model": "GE1.6-82.5",
    "t_cap": 1600,
    "t_hh": 80,
    "t_rd": 82.5,
    "t_rsa": 5345.62,
    "t_ttlh": 121.3,
    "t_retrofit": 0,
    "t_retro_yr": null
    "t_conf_atr": 3,
    "t_conf_loc": 3,
    "t_img_date": "1/1/2013",
    "t_img_src": "NAIP",
    "xlong": -93.3549,
    "ylat": 41.90419
}

The two significant parts that make up JSON are keys and values. Together they make a key/value pair. We can see the returned turbine object above has 24 key/value pairs. Key value pairs are comma separated and follow a specific syntax, with the key, followed by a colon, followed by the value. The first line from the return above is key/value pair "case_id": 3038257. The key is "case_id" and the value is 3038257. A key is always a string enclosed in quotation marks, whereas a value can be a string, number, Boolean expression, array, or object.

Key/Value Codes

Upon a successful response (see Status Codes section), the USWTDB API will return turbine objects consisting of key/value pairs. Below is a list of USWTDB keys, related value types, and an explanation of what each key means. Turbine attribute data were gathered from the Federal Aviation Administration's Digital Obstacle File (DOF) and Obstruction Evaluation Airport Airspace Analysis Dataset (OE-AAA), the American Clean Power Association (ACP), Lawrence Berkeley National Laboratory, the U.S. Geological Survey, and additional online sources. In cases where data from these sources were unknown or missing, a "null" value was assigned to the key.

Status Codes

The USWTDB API returns appropriate HTTP status codes for every request. Response status codes indicate whether a specific request has been successfully completed. USWTDB API responses are grouped into four classes: successful responses (2XX), redirects (3XX), client errors (4XX), and server errors (5XX). An exhaustive list of status codes are defined in the RFC 2616. The most common USWTDB API status codes are listed in the table below.

Pagination

When making requests to the USWTDB API, it's possible to receive a large amount of data in the response. The API has controls in place that let you paginate the results, to make returns more manageable and avoid extraneous network traffic. These controls let you set limit and offset via either request headers, or query parameters. Every API response contains Content-Range headers which describe the size of results. By default, the response includes the current range, and, if sent with Prefer: count=exact in the request, the total number of results. When using request headers to limit results, you simply specify the range of rows desired. For example, the request below returns the first 250 turbines (note that the offset numbering is zero-based).

GET /turbines HTTP/1.1
Range: 0-249
Prefer: count=exact

Since we sent our preference Prefer: count=exact in the request header, we get a Content-Range response (below) that includes the total size of the table (58,188 records). This is particularly useful when rendering a 'last' link in a pagination control.

HTTP/1.1 206 Partial Content
Content-Range: 0-249/58188

Paging the dataset can also be achieved by taking an offset and limit as query parameters. In the example below, the limit and offset were added to the query so that 50 (limit) turbine records are returned starting from the 300th (offset) record. Note that the API always returns range headers in the response, even if you use query parameters to paginate the query.

$ curl -i -X GET "https://eersc.usgs.gov/api/uswtdb/v1/turbines?&offset=300&limit=50"

Sorting

You can reorder the records in the response by using order in the query string. The parameter uses a comma separated list of turbine columns and can contain directions asc (ascending) or desc (descending) if desired. As an example (below), let's say we wanted to return turbine records sorted by the number of turbines per project (p_tnum) in ascending order, and then sorted by the year the project went online (p_year) in descending order.

$ curl -i -X GET "https://eersc.usgs.gov/api/uswtdb/v1/turbines?&order=p_tnum.desc,p_year.asc"

The USWTDB contains null values where data attributes are unknown or missing. Null values for any desired key can be sorted in either direction by appending nullsfirst or nullslast to the order query. In the example below, 100 turbine records are queried, ordered by turbine model, where null values are sent to the end of the return:

$ curl -i -X GET "https://eersc.usgs.gov/api/uswtdb/v1/turbines?&order=t_model.nullslast&limit=100"

Row Filtering

The USWTDB API supports filtering table rows by appending the property (or multiple properties), the filter operator, and the filter value to the request. Filters can keep or exclude table rows using simple operators that compare against specified key values. Applying filters to the request allows for more efficient, faster API responses because unneeded data is withheld by the server prior to API return. This is particularly useful when users are only interested in a subset of data from the USWTDB.

To apply row filtering, simply append the ? query string parameter and a valid filter expression (see Filter Operators section) to your request. In the example below, we'll filter our return to show only turbines that were installed in 1995:

$ curl -i -X GET "https://eersc.usgs.gov/api/uswtdb/v1/turbines?&p_year=eq.1995"

Multiple parameters can be logically conjoined using the & parameter, allowing for filtering on as many attributes as desired. In the request below, we'll further refine our query to only return turbines that were installed in 1995 and had a rated capacity greater than 2.5 MW:

$ curl -i -X GET "https://eersc.usgs.gov/api/uswtdb/v1/turbines?&p_year=eq.1995&t_cap=gt.200"

Filter Operators

The table below contains the available operators used to filter returns by USWTDB key values. For each available operator, a real-world example is included showing how the operator is used to filter API responses. Note that some of the examples combine the query operators with additional functions described previously in the documentation. As previously noted, query strings should be appended to the USWTDB API base path https://eersc.usgs.gov/api/uswtdb/v1/.

Column Filtering

By default, the USWTDB API returns data with all columns (attribute fields) in the response. If you're only interested in a subset of these, you can specify which columns are returned using the select parameter in the query string. This effectively tells the API to withhold all unneeded data fields, resulting in a far more efficient response. In the example below, let's say you were only interested a response that included project name, turbine capacity, and the state where the turbine was located (we'll also sort by project name in descending order):

$ curl -i -X GET "https://eersc.usgs.gov/api/uswtdb/v1/turbines?&select=p_name,t_cap,t_state&order=p_name.desc"

Our response (below) only returns the columns passed in our select parameter:

 {"p_name":"Zotos","t_cap":1650,"t_state":"NY"},
 {"p_name":"Zotos","t_cap":1650,"t_state":"NY"},
 {"p_name":"Zephyr Wind Project","t_cap":1500,"t_state":"OH"},
 ...

In some cases, you may want to rename (alias) a column name on API return. Aliases are often used to make column names more readable or easier to understand. This can be achieved by prefixing the column name with a column alias, followed by the : operator. Let's say you'd like to display API returns limited to project name, turbine capacity, and rotor diameter, but feel that the default column name for rotor diameter t_rd needs to be spelled out as "rotor_diameter". To do this, we'd simply append the normal select parameter to our query and add the column rename prefix rotor_diameter to t_rd:

$ curl -i -X GET "https://eersc.usgs.gov/api/uswtdb/v1/turbines?&select=p_name,t_cap,rotor_diameter:t_rd"

Our response (below) returns the columns passed in our select parameter, but with t_rd column renamed to rotor_diameter:

 {"p_name":"Agassiz Beach","t_cap":660,"rotor_diameter":47.00},
 {"p_name":"Air Force (Barnstable)","t_cap":1500,"rotor_diameter":77.00},
 {"p_name":"Alite Wind Farm","t_cap":3000,"rotor_diameter":90.00},
 ...

The USWTDB API allows columns to be converted from one data type to another through casting. Examples of common casts are strings to date type, numeric type to text, or character strings to numeric values. Note that not every data type can be cast into every other data type, and invalid casting will result in an code 400 error from the API. To cast a column, suffix it with a :: plus the desired type. Let's say you'd like to cast the default string type t_img_date as a date type, and cast the default integer type t_cap as a string type. To do this we'll apply our casts to the appropriate columns:

$ curl -i -X GET "https://eersc.usgs.gov/api/uswtdb/v1/turbines?&select=t_img_date::date,t_cap::text"

Our response (below) returns the selected columns formatted with the desired casts:

 {"t_img_date":"2017-04-21","t_cap":"1000"},
 {"t_img_date":"2017-04-21","t_cap":"660"},
 {"t_img_date":"2012-01-01","t_cap":"1500"},
 ...

Authorization

The creation of USWTDB was jointly funded by the U.S. Department of Energy via the Lawrence Berkeley National Laboratory, the U.S. Geological Survey, and the American Clean Power Association. The database is being continuously updated through collaboration among these partners and as such, requires authorized access to the API by selected collaborators. For public users, the USWTDB API acts as read-only resource and allows standard HTTP GET (read) requests to be received successfully without authentication. For any additional incoming HTTP methods, including POST (create records), PUT (replace/update records), PATCH (patial update records), and DELETE (deletes a record), authorization is required.

 curl -X PATCH "https://eersc.usgs.gov/api/uswtdb/v1/turbines?&case_id=eq.636" \
     -H 'Authorization: Bearer {your token here}' \
     -H 'Content-Type: application/json' \
     -d '{ "t_manu": "GE Wind" }'

 curl -X POST "https://eersc.usgs.gov/api/uswtdb/v1/turbines?&case_id=eq.636" \
     -H 'Authorization: Bearer {your token here}' \
     -H 'Prefer: resolution=merge-duplicates' \
     -H 'cache-control: no-cache' \
     -d 'case_id,p_name,p_year,p_tnum,p_cap,t_manu,t_model \
       3018370,Jiminy Peak Ski Resort,2007,1,1.5,GE Wind \
       3045115,Judith Gap,2005,90,135,GE Wind'