USPVDB API

About the API

The USPVDB API allows for programmatic access to the United States Large Scale Solar Photovoltaic Database. Creation of the USPVDB API was meant to extend USPVDB 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 USPVDB. 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 USPVDB 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 USPVDB API endpoint conforms to the design principles of Representational State Transfer (REST) and uses the JSON data format for responses. Retrieval of facility data from the USPVDB API requires a standard GET request. Additional methods that submit or change USPVDB 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/uspvdb/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 facility level information from the USPVDB for facility ID 400004. To do this, you'd simply combine the base path https://eersc.usgs.gov/api/uspvdb/v1, with the desired resource /projects, and append your query string ?&case_id=eq.400004. 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/uspvdb/v1/projects?&case_id=eq.400004"

{
    "case_id": 400004,
    "multi_poly": "multi",
    "eia_id": 645,    
    "p_state": "FL",
    "p_county": "Hillsborough",
    "ylat": 27.7802,
    "xlong": -82.3911,
    "p_area": 830853,
    "p_img_date": 20220420,
    "p_dig_conf": 4,
    "p_name": "Big Bend",
    "p_year": 2017,
    "p_pwr_reg": "TEC",
    "p_tech_pri": "PV",
    "p_tech_sec": "thin-film",
    "p_axis": "single-axis",
    "p_azimuth": 180,
    "p_tilt": 20,
    "p_battery": "batteries",
    "p_cap_ac": 19,
    "p_cap_dc": 23,
    "p_type": "greenfield",
    "p_agrivolt": "non-agrovoltaic",
    "p_zscore": -0.97,
}

The two significant parts that make up JSON are keys and values. Together they make a key/value pair. We can see the returned facility 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": 400004. The key is "case_id" and the value is 400004. 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 USPVDB API will return facility objects consisting of key/value pairs. Below is a list of USPVDB keys, related value types, and an explanation of what each key means. Solar facility attributes were drawn from Energy Information Administration (EIA) Form 860 data, which are self-reported by facility operators. These data include attributes such as: commercial operation date, location coordinates (latitude and longitude), MW of capacity (in both DC and AC terms), module type (e.g., crystalline silicon, thin film), axis type (fixed-tilt versus single-axis tracking), facility name, and regional power authority. In cases where data from these sources were unknown or missing, a "null" value was assigned to the key.

Status Codes

The USPVDB API returns appropriate HTTP status codes for every request. Response status codes indicate whether a specific request has been successfully completed. USPVDB 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 USPVDB API status codes are listed in the table below.

Pagination

When making requests to the USPVDB 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 facilities (note that the offset numbering is zero-based).

GET /projects 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 (3,698 records). This is particularly useful when rendering a 'last' link in a pagination control.

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

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) facility 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/uspvdb/v1/projects?&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 project columns and can contain directions asc (ascending) or desc (descending) if desired. As an example (below), let's say we wanted to return facility records sorted by facility type (p_type) in ascending order, and then sorted by the year the facility went online (p_year) in descending order.

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

The USPVDB 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 facility records are queried, ordered regional power authority name (p_pwr_reg), where null values are sent to the end of the return:

$ curl -i -X GET "https://eersc.usgs.gov/api/uspvdb/v1/projects?&order=p_pwr_reg.nullslast&limit=100"

Row Filtering

The USPVDB 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 USPVDB.

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 the return to show only facilities that were installed in 2020:

$ curl -i -X GET "https://eersc.usgs.gov/api/uspvdb/v1/projects?&p_year=eq.2020"

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 facilities that were installed in 2020 and have a rated capacity greater than 100 MW (AC):

$ curl -i -X GET "https://eersc.usgs.gov/api/uspvdb/v1/projects?&p_year=eq.2020&p_cap_ac=gt.100"

Filter Operators

The table below contains the available operators used to filter returns by USPVDB 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 USPVDB API base path https://eersc.usgs.gov/api/uspvdb/v1/.

Column Filtering

By default, the USPVDB 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 facility name, facility capacity (AC), and the state where the project was located (we'll also sort by facility name in descending order):

$ curl -i -X GET "https://eersc.usgs.gov/api/uspvdb/v1/projects?&select=p_name,p_cap_ac,p_state&order=p_name.desc"

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

{"p_name":"ZV Solar 3, LLC","p_cap_ac":4.9,"p_state":"NC"}, 
{"p_name":"ZV Solar 2, LLC","p_cap_ac":4.9,"p_state":"NC"}, 
{"p_name":"ZV Solar 1","p_cap_ac":5.0,"p_state":"NC"},
 ...

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 facility name, facility capacity (AC), and install year, but feel that the default column name for install year p_year needs to be spelled out as "install_year". To do this, we'd simply append the normal select parameter to our query and add the column rename prefix install_year to p_year:

$ curl -i -X GET "https://eersc.usgs.gov/api/uspvdb/v1/projects?&select=p_name,p_cap_ac,install_year:p_year"

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

{"p_name":"Rancho Seco Solar","p_cap_ac":2,"install_year":1986}, 
{"p_name":"Big Bend","p_cap_ac":19,"install_year":2017}, 
{"p_name":"Geneseo","p_cap_ac":0.9,"install_year":2015}, 
 ...

The USPVDB 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 integer type p_cap_dc 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/uspvdb/v1/projects?&select=p_cap_dc::text"

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

{"p_cap_dc":"2.00"}, 
{"p_cap_dc":"23.00"}, 
{"p_cap_dc":"1.20"},
 ...

Authorization

The creation of USPVDB was jointly funded by the U.S. Department of Energy via the Lawrence Berkeley National Laboratory and the U.S. Geological Survey. 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 USPVDB 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/uspvdb/v1/projects?&case_id=eq.403678" \
     -H 'Authorization: Bearer {your token here}' \
     -H 'Content-Type: application/json' \
     -d '{"p_tilt": "30"}'

 curl -X POST "https://eersc.usgs.gov/api/uspvdb/v1/projects?&case_id=eq.403678" \
     -H 'Authorization: Bearer {your token here}' \
     -H 'Prefer: resolution=merge-duplicates' \
     -H 'cache-control: no-cache' \
     -d 'case_id,p_name,p_year,p_state \
     403678,Gohman Community Solar (CSG),2020,MN \
     403640,Chub Garden Solar,2020,MN'