Billion-Ton REST API

Base URL: https://bioenergykdf.net/appsapi/resources/

All services in this document are defined assuming they are appended to the base URL defined above.  Client applications can choose the most appropriate response format for the particular environment.  XML is the default format and is what is returned from a browser, JSON can be used for Javascript applications using Proxy server to exchange data across domains.  The preferred method for JavaScript applications is the JavaScript callback which will provide the data within the callback function specified by passing the function name in the jsoncallback parameter in the URL.

 

Response Formats

XML [Default]

JSON: Specify Application/JSON in request Header

JavaScript callback: Specify Application/x-javascript in request Header

Example Query:

https://bioenergykdf.net/appsapi/resources/billionton/energy/price?jsoncallback=Function

Example Responses:

XML:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<bt2Prices>

<bt2Price>

<price>40.0</price>

<type>Energy</type>

<typeCode>0</typeCode>

</bt2Price>

<bt2Price>

<price>45.0</price>

<type>Energy</type>

<typeCode>0</typeCode> 
</bt2Price>

...

...

</bt2Prices>

 

JSON:

{"bt2Price":[{"price":40.0,"type":"Energy","typeCode":0},

{"price":45.0,"type":"Energy","typeCode":0},...]}

 

JSON Callback:

jsonFunction({"bt2Price":[{"price":40.0,"type":"Energy","typeCode":0},

{"price":45.0,"type":"Energy","typeCode":0},...]})

 

Billion-Ton Update:

Background:

Crop Type

Description

Crops

Energy

   

Conventional

   

Forest

   

SecForest

   

SecAgriculture

   

Web Service Definitions

 

Crops, Residue, Resource Prices:  Prices vary depending on the resources of interest.

URL: billionton/{cropType}/price

Parameter

Type

Description

cropType [Required]

Enum

The type of crops/resources that will be returned and specified in the later queries.  Valid values are energy, conventional, forest, secagriculture, and secforest.  This is a required parameter.

Jsoncallback [Optional]

String

Callback function to return value in for JavaScript Applications

 

Lookup Values:  Lookup scenario, feedstock, and units of measure

URL: billionton/{cropType}/lookup/{value}?jsoncallback=function

Parameter

Type

Description

cropType [Required]

Enum

The type of crops/resources that will be returned and specified in the later queries.  Valid values are energy, conventional, forest, secagriculture, and secforest. 

Value

Enum

The information you are seeking for the selected crop type.  Valid values are scenario (only valid for energy/conventional), feedstock, and units.

Jsoncallback [Optional]

String

Callback function to return value in for JavaScript Applications

 

Production Data:  Get the production data for specified crops for a given year and price.

URL: billionton/{cropType}/production/{aggregation}/{year}{price}?

crop=CropName& scenarioid=Scenario&minvalue=minProductionValue

&maxvalue=maxProductionValue&jsoncallback=Function

Parameter

Type

Description

cropType [Required]

Enum

The type of crops/resources that will be returned and specified in the later queries.  Valid values are energy, conventional, forest, secagriculture, and secforest.  This is a required parameter.

Aggregation [Required]

Enum

This determines weather the results are returned at the State or County level.  Valid arguments are ST and CNTY.  Aggregation value is ignored for secforest and secagriculture crop types.

Year [Required]

Integer

The year for data to be returned.  Ranges from 2012 ‚Äì 2030.

Price [Required]

Integer

The Biomass Price for the selected crop of choice.  Best to use the price service to ensure proper price values for different crop types.

Crop [Required]

String

A selected crop from the chosen crop type using the feedstock lookup service.  A valid year and price must also be provided.

Scenarioid [Optional]

String

Only valid for conventional and energy crops to define the appropriate model scenario for crop production.  Use the lookup web service to find appropriate scenarioid values.

Minvalue [Optional]

Double

Filter the data to values greater than or equal to the specified value

Maxvalue [Optional]

Double

Filter the data to values less than or equal to the specified value.

Jsoncallback [Optional]

String

Callback function to return value in for JavaScript Applications

 

Example Workflow:

Find state level production values for an energy crop in 2022.

  1. Find prices for energy crops/residues
    1. https://bioenergykdf.net/appsapi/resources/billionton/energy/price
      1. Results show the range from $40 - $80 in $5 increments
      2. Select $60 as price values
  2. Lookup Energy Crops
    1. https://bioenergykdf.net/appsapi/resources/billionton/energy/lookup/feedstock
      1. Results Show 8 energy crops
      2. Select Corn Stover (code = Corn-stvr)
  3. Lookup Energy Crop Scenarios
    1. https://bioenergykdf.net/appsapi/resources/billionton/energy/lookup/scenario
      1. Results show 6 scenarios
      2. Select High-yield Scenario, 1 % Increase Energy Crop Yield Growth (id = BLY+EC1HC_HNT)
  4. Get State Production For Corn Stover under the High-yield 1% Scenario at a price of $60 in 2022.
    1. https://bioenergykdf.net/appsapi/resources/billionton/energy/production/st/2022/60?crop=Corn-stvr&scenarioid=BLY+EC1HC_HNT