Biositing Tool API (v1)¶
The Biositing Tool API is an open API for programatically accessing data in our geospatial platform based on REpresentational State Transfer (REST) principles. In a RESTful system, information is organized into resources, each of which is uniquely identified via a uniform resource identifier (URI). This page documents the first release (v1) of the Biositing API and provides examples of common use-cases.
Resources¶
In the Biositing API, resources refer to specific types of data in the tool that can be accessed programatically with a URI endpoint. Currently supported information types (v1 of the REST API) include the following:
Ethanol Biorefineries - Identifiers (i.e. name, address, latitude, longitude, etc.) and properties (capacity, operational status) of ethanol biorefineries in the continental U.S.
Renewable Diesel & SAF Plants - Identifiers (i.e. name, address, latitude, longitude, etc.) and properties (capacity, operational status) of renewable diesel and SAF plants in the continental U.S.
... More coming soon!
Authentication¶
SSL Encryption All requests to the Biositing API must be done over HTTPS. Non-secure http requests are not allowed and will result in a HTTP 403 (Forbidden) response.
Security¶
You agree not to use automated scripts to collect large fractions of the database and disseminate them. You may collect large fractions of the database for analysis and to present processed results with proper attribution. If you plan to download large datasets, please email feedstocktofunction@gmail.com with the email address associated with your account and with your use case so that we can avoid flagging your account as abusing the service. We may also suggest an efficient way for you to obtain the data you need. We reserve the right to disable API access as a security precaution against bots.
API Reference¶
General URI Format¶
All URIs in the Biositing API are of the general form
https://biositing.jbei.org/api/v1/{resource_type}[?{parameters}]
-
The initial part of the URI (https://biositing.jbei.org/api/v1/) is a preamble, specifying a https REST request. The v1 denotes version 1 of the API, to provide flexibility to support multiple versions of the API in the future.
-
{resource_type}
specifies the kind of information or operation being requested. -
{parameters}
specifies optional query parameters in the formatkey=value
. When specifying mulitple query parameters in a URIthey must be separated by&
characters e.g.key1=value1&key2=value2&key3=value3
Resources¶
Renewable Diesel & SAF Plants - Identifiers (i.e. name, address, latitude, longitude, etc.) and properties (capacity, operational status) of renewable diesel and SAF plants in the continental U.S.
ethanol_biorefineries
¶
Request Template¶
GET https://biositing.jbei.org/api/v1/ethanol_biorefineries
Obtain dataset of ethanol biorefineries in the continental U.S. Attributes include name, address, latitude, longitude, capacity, operational status, etc.
renewable_diesel_saf_plants
¶
Request Template¶
GET https://biositing.jbei.org/api/v1/renewable_diesel_saf_plants
Obtain dataset of renewable diesel and SAF plants in the continental U.S. Attributes include name, address, latitude, longitude, capacity, operational status, etc.
site_buffer
¶
Request Template¶
GET https://biositing.jbei.org/api/v1/chemicals?latitude={LATITUDE}&longitude={LONGITUDE}&radius={RADIUS}
Obtain an inventory of bioeconomy resources (e.g. biomass, municipal solid waste, plastic waste etc.) within a defined buffer radius of a point location specified by latitude and longitude coordinates.
Required Parameters¶
The following query parameters must be specified in the GET request URI.
latitude
- Latitude coordinate of buffer zone centroid in in decimal degrees format
e.g.
39.44869283589919
longitude
- Longitude coordinate of buffer zone centroid in in decimal degrees format.
e.g.
-92.48419980931273
radius
- Radial distance (in kilometers) to define the buffer zone around the point
specified by
latitude
andlongitude
Optional Parameters¶
The following optional parameters may also be specified:
summarize=true
- Whether to return sum totals resource types
within the site buffer zone instead of returning individual point-level
resource estimates. Note: this is a fixed parameter for which the only
allowable value is
true
.
Example Usage¶
GET https://biositing.jbei.org/api/v1/site_buffer/?latitude=39.44869283589919&longitude=-92.48419980931273&radius=20