getGrainInstruments API

The getGrainInstruments API is used to request symbol and metadata information regarding physical grain instruments across Barchart's cash bids and grain indexes. Users can request information based on crop type / root symbol, geo-location, or areas that are codified by FIPS standards. Returned instruments and their corresponding symbols can be passed to getQuote or getHistory to retrieve the associated price data - as requested by the end user. Find our more about our commodity data offerings here.

All APIs

Contact Us to Get Access

Inputs

instrumentType required

The type of grain instruments. This parameter should be set to the desired instrument type for the query.

Type
enum (A type which includes a list of valid possible values.) 
Example
indexBasis 
Default
bidBasis 

Valid Values:
bidBasis, bidCash, indexBasis, indexCash

instrumentRoot required

A 2-char indicator for commodities. This parameter should be set to the root that represents the desired commodity for the query. Roots that are denoted as "all" are valid for both bid and index data - if "bids" then there is no index associated with that root.

ZC: All kinds of Corn and Milo/Sorghum (all), ZS: All kinds of Soybeans (all), ZW: All kinds of Soft Red Winter Wheat (all), MW: All kinds of Spring Wheat (all), KE: All kinds of Hard Red Winter Wheat (all), FW: All kinds of Feed Wheat (bids), DW: All kinds of Durum Wheat (bids), CW: Wheat (Club) (bids), ZM: Soybean Meal (bids), HS: Soybeans (Hulls) (bids), ZO: Oats (bids), BB: Barley (bids), ZR: Rice (bids), ZK: Ethanol (E85) (bids), GP: Peas (Green) (bids), YP: Peas (Yellow) (bids), SF: Birdseed or Sunflowers (bids), RY: Rye (bids), RS: Canola (bids), PC: Pulse Crops (Peas, Dry Beans, Lentils & Chickpeas) (bids), PB: Beans (Pinto) (bids), LB: Beans (Lentil) (bids), GB: Beans (Garbonzo) (bids), MI: Millet (bids), MD: Distiller Grains (MWDGS) (bids), DG: Distiller Grains (DDGS) (bids), FL: Flax (bids), CS: Cottonseed (bids)

Type
list (A comma or semi-colon delimited string.) 
Example
ZC 

zipCode optional

A valid zip code to refine the area that cash bids orgin from. This parameter is required if stateFipsCode has not been set. This is the only way to query Canada grain bids.

Type
string (A sequence of characters. (example: GOOG)) 

stateFipsCode optional

A valid 2-digit state code used to define the area that the underlying grain data (bids or indexes) will be returned from. This parameter is required if zipCode and indexGroup have not been set. Note that calls using this field will return instruments for counties and districts that are associated with the requested stateFipsCode - in addition any instruments with an area equal to the user specified stateFipsCode.

Please click here to get a list of possible values.

Type
string (A sequence of characters. (example: GOOG)) 

districtCode optional

A valid 2-digit district code used to define the area that the underlying grain data (bids or indexes) will be returned from. Note that calls using this field will return instruments for counties that are associated with the requested districtCode - in addition any instruments with an area equal to the user specified districtCode.

Please click here to get a list of possible values.

Type
string (A sequence of characters. (example: GOOG)) 

countyFipsCode optional

A valid 3-digit county code use to define the the area that the underlying grain data (bids or indexes) will be returned from.

Please click here to get a list of possible values.

Type
string (A sequence of characters. (example: GOOG)) 

deliveryMonth required

The last month in the delivery window for cash bids or indexes using the following format: "YYYYMM"(i.e. 201812). For example, a bid with a delivery window of 201812 through 201903 can only be retrieved by input of 201903.

For instrumentType = 'IndexBasis' or 'IndexCash', this parameter accepts rolling month codes: 'A' - 'L', which represent the forward delivery month from front month (A) to the 11th (L) forward month

Type
string (A sequence of characters. (example: GOOG)) 
Example
201812 

indexGroup optional

A valid index aggregate level that returns all index instruments belonging to a specific indexGroup.Combining indexGroup and country or region are the only way to query national indexes and regional indexes.

This parameter may required if stateFipsCode has not been set.

Type
enum (A type which includes a list of valid possible values.) 
Example
nation 

Valid Values:
nation, region, state, district, county

country optional

The short country name to further refine the index instruments.

Type
string (A sequence of characters. (example: GOOG)) 
Example
US 

region optional

A short region name to further refine the index instruments.

Type
enum (A type which includes a list of valid possible values.) 

Valid Values:
Delta, Eastern, Western, Others

maxRecords optional

The maximum amount of records returned. This parameter should be set to the maximum number of records desired. Default value is 200

Type
enum (A type which includes a list of valid possible values.) 
Example
25 
Default
200 

Valid Values:
25, 50, 100, 150, 200, 250, 300, 350, 400, 450, 500

page required

The value to set for pagination.

Type
integer (A numeric type defining a whole number. (example: 2)) 
Example
Default

Outputs

Name / Requirement
Description
Type
symbol
always returned
A unique symbol that identifies a grain bid or a grain index.
string
A sequence of characters. (example: GOOG)
symbolDescription
always returned
A short description of a grain bid or a grain index.
string
A sequence of characters. (example: GOOG)
elevator
as requested
Name of the applicable grain buying elevator.
(ONLY returned for instrument type bidBasis or bidCash.)
string
A sequence of characters. (example: GOOG)
commodity
always returned
Standardized commodity name.
string
A sequence of characters. (example: GOOG)
underlyingFuture
always returned
Futures symbol of tied futures contract.
string
A sequence of characters. (example: GOOG)
deliveryStart
as requested
Delivery start date of grain bid.
(ONLY returned for instrument type bidBasis or bidCash.)
dateTime
A date and time in the format of YYYY-MM-DD HH:MI:SS<TIMEZONE_OFFSET>.
deliveryEnd
always returned
Delivery end date of the associated grain instrument.
dateTime
A date and time in the format of YYYY-MM-DD HH:MI:SS<TIMEZONE_OFFSET>.
location
as requested
Name of location that grain bid originated from.
(ONLY returned for instrument type bidBasis or bidCash.)
string
A sequence of characters. (example: GOOG)
facilityType
as requested
The type of facility.
(ONLY returned for instrument type bidBasis or bidCash.)
string
A sequence of characters. (example: GOOG)
phone
as requested
Phone number of location.
(ONLY returned for instrument type bidBasis or bidCash.)
string
A sequence of characters. (example: GOOG)
website
as requested
Website associated with elevator.
(ONLY returned for instrument type bidBasis or bidCash.)
string
A sequence of characters. (example: GOOG)
address
as requested
The street address of the location.
(ONLY returned for instrument type bidBasis or bidCash.)
string
A sequence of characters. (example: GOOG)
city
as requested
City associated with the underlying grain bid.
(ONLY returned for instrument type bidBasis or bidCash.)
string
A sequence of characters. (example: GOOG)
state
always returned
2-char abbreviation of the state that contains the applicable cash bid or index.
string
A sequence of characters. (example: GOOG)
zipCode
as requested
Zip code associated with the underlying grain bid.
string
A sequence of characters. (example: GOOG)
longitude
as requested
The longitude of the location.
(ONLY returned for instrument type bidBasis or bidCash.)
string
A sequence of characters. (example: GOOG)
latitude
as requested
The latitude of the location.
(ONLY returned for instrument type bidBasis or bidCash.)
string
A sequence of characters. (example: GOOG)
county
always returned
The name of the county containing the applicable cash bid or index.
string
A sequence of characters. (example: GOOG)
indexGroup
as requested
A index aggregate level (National, Regional, State, Crop Reporting District, County).
(ONLY returned for instrument type indexBasis or indexCash.)
string
A sequence of characters. (example: GOOG)
country
as requested
The country associated with the indexing area.
(ONLY returned for instrument type indexBasis or indexCash.)
string
A sequence of characters. (example: GOOG)
region
as requested
The region associated with the applicable indexing area.
(ONLY returned for instrument type indexBasis or indexCash.)
string
A sequence of characters. (example: GOOG)
countyCode
as requested
Concatenation of stateFipsCode, countyFipsCode, and classFipsCode.
(ONLY returned for instrument type bidBasis or bidCash.)
string
A sequence of characters. (example: GOOG)
fipsCode
as requested
FIPS code for the county. Concatenation of stateFipsCode and countyFipsCode.
(ONLY returned for instrument type bidBasis or bidCash.)
string
A sequence of characters. (example: GOOG)
countyFipsCode
always returned
3-digit FIPS code of the county is associated with the applicable cash bid or index.
string
A sequence of characters. (example: GOOG)
districtCode
always returned
2-digit district code of crop reporting district that is associated with the applicable cash bid or index.
string
A sequence of characters. (example: GOOG)
stateFipsCode
always returned
2-digit FIPS code of state that is associated with the applicable cash bid or index.
string
A sequence of characters. (example: GOOG)

Status Code Responses

200
OK
Success
400
Bad Request
The request was invalid, please see the message for more information.
500
Internal Server Error
Something is not working correctly, please contact support.


JSON

GET

GET https://ondemand.websol.barchart.com/getGrainInstruments.json?apikey=YOUR_API_KEY&instrumentType=indexBasis&instrumentRoot=ZC&deliveryMonth=201812&indexGroup=nation&country=US&maxRecords=25&page=1
Host: ondemand.websol.barchart.com

POST

POST https://ondemand.websol.barchart.com/getGrainInstruments.json
Host: ondemand.websol.barchart.com
Content-Type: application/x-www-form-urlencoded
Content-Length: length

apikey=YOUR_API_KEY&instrumentType=indexBasis&instrumentRoot=ZC&deliveryMonth=201812&indexGroup=nation&country=US&maxRecords=25&page=1

Response

{
    "status": {
        "code": 200,
        "message": "Success."
    },
    "results": [
        {
            "symbol": "ZCBZ18US.CM",
            "symbolDescription": "National Corn Dec 2018 Basis Index",
            "commodity": "Corn (#2 Yellow)",
            "underlyingFuture": "ZCZ18",
            "deliveryEnd": "2018-12-31T23:59:59-06:00",
            "state": "",
            "county": "",
            "indexGroup": "nation",
            "country": "US",
            "region": "",
            "countyFipsCode": "",
            "districtCode": "",
            "stateFipsCode": ""
        }
    ]
}

XML

GET

GET https://ondemand.websol.barchart.com/getGrainInstruments.xml?apikey=YOUR_API_KEY&instrumentType=indexBasis&instrumentRoot=ZC&deliveryMonth=201812&indexGroup=nation&country=US&maxRecords=25&page=1
Host: ondemand.websol.barchart.com

POST

POST https://ondemand.websol.barchart.com/getGrainInstruments.xml
Host: ondemand.websol.barchart.com
Content-Type: application/x-www-form-urlencoded
Content-Length: length

apikey=YOUR_API_KEY&instrumentType=indexBasis&instrumentRoot=ZC&deliveryMonth=201812&indexGroup=nation&country=US&maxRecords=25&page=1

Response


<?xml version="1.0" encoding="utf-8"?>
 <getGrainInstruments>
  <status>
   <code>200</code>
   <message>Success.</message>
  </status>
  <item>
   <symbol>ZCBZ18US.CM</symbol>
   <symbolDescription>National Corn Dec 2018 Basis Index</symbolDescription>
   <commodity>Corn (#2 Yellow)</commodity>
   <underlyingFuture>ZCZ18</underlyingFuture>
   <deliveryEnd>2018-12-31T23:59:59-06:00</deliveryEnd>
   <state></state>
   <county></county>
   <indexGroup>nation</indexGroup>
   <country>US</country>
   <region></region>
   <countyFipsCode></countyFipsCode>
   <districtCode></districtCode>
   <stateFipsCode></stateFipsCode>
  </item>
 </getGrainInstruments>

CSV

GET

GET https://ondemand.websol.barchart.com/getGrainInstruments.csv?apikey=YOUR_API_KEY&instrumentType=indexBasis&instrumentRoot=ZC&deliveryMonth=201812&indexGroup=nation&country=US&maxRecords=25&page=1
Host: ondemand.websol.barchart.com

POST

POST https://ondemand.websol.barchart.com/getGrainInstruments.csv
Host: ondemand.websol.barchart.com
Content-Type: application/x-www-form-urlencoded
Content-Length: length

apikey=YOUR_API_KEY&instrumentType=indexBasis&instrumentRoot=ZC&deliveryMonth=201812&indexGroup=nation&country=US&maxRecords=25&page=1

Response

symbol,symbolDescription,commodity,underlyingFuture,deliveryEnd,state,county,indexGroup,country,region,countyFipsCode,districtCode,stateFipsCode
"ZCBZ18US.CM","National Corn Dec 2018 Basis Index","Corn (#2 Yellow)","ZCZ18","2018-12-31T23:59:59-06:00","","","nation","US","","","",""


PHP

<?php

$ondemand = new SoapClient('https://ondemand.websol.barchart.com/service?wsdl');

$params = [
    'apikey' => 'YOUR_API_KEY',
    'instrumentType' => 'indexBasis',
    'instrumentRoot' => 'ZC',
    'deliveryMonth' => '201812',
    'indexGroup' => 'nation',
    'country' => 'US',
    'maxRecords' => '25',
    'page' => '1',
];

$result = $ondemand->getGrainInstruments($params);
var_dump($result);

Classic ASP

Dim ondemand
Dim result

Set ondemand = Server.CreateObject("MSSOAP.SoapClient30")
ondemand.ClientProperty("ServerHTTPRequest") = True
ondemand.MSSoapInit("https://ondemand.websol.barchart.com/service?wsdl")

Set result = ondemand.getGrainInstruments("YOUR_API_KEY", "indexBasis", "ZC", "201812", "nation", "US", "25", "1")

Perl

use SOAP::Lite;
use SOAP::WSDL;

my $ondemand = SOAP::Lite
    -> service('https://ondemand.websol.barchart.com/service?wsdl');

my $result = $ondemand->getGrainInstruments('YOUR_API_KEY', 'indexBasis', 'ZC', '201812', 'nation', 'US', '25', '1');

print $result;

Python

from suds.client import Client
ondemand = Client('https://ondemand.websol.barchart.com/service?wsdl')

result = client.service.getGrainInstruments('YOUR_API_KEY', 'indexBasis', 'ZC', '201812', 'nation', 'US', '25', '1')

print result

Ruby

require 'savon'

ondemand = Savon.client(wsdl: 'https://ondemand.websol.barchart.com/service?wsdl')

response = ondemand.call(
    :getGrainInstruments,
    message: {
        apikey: 'YOUR_API_KEY',
        instrumentType: 'indexBasis',
        instrumentRoot: 'ZC',
        deliveryMonth: '201812',
        indexGroup: 'nation',
        country: 'US',
        maxRecords: '25',
        page: '1',
    }
)

response.body