Cash Grain Instruments API

getGrainInstruments

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.

View All APIs

First Name^*

Last Name^*

Email Address^*

Phone^*

Company^*

Role^*

Industry^*

Country^*

What you are looking for?^*

Please provide as much information as possible (e.g. exchanges, markets or other data sources), the APIs you are interested in (e.g. getQuote, getHistory, getChart, getCorporateActions, etc.), and your use case.

Here are some examples: Example #1, Example #2, Example #3.

By submitting this form you are opting in to receive email communications from Barchart for related product, service or company information, updates and announcements. You can unsubscribe at anytime. View our Privacy Policy.

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^optional

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

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

202412

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

list-enum (A comma or semi-colon delimited string that must match 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

1

Default

locationId^optional

The locationId for which all cash bid symbol should be returned.

Type

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

Example

4435

Outputs

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

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=202412&indexGroup=nation&country=US&maxRecords=25&page=1&locationId=4435
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=202412&indexGroup=nation&country=US&maxRecords=25&page=1&locationId=4435

Response

{
    "status": {
        "code": 200,
        "message": "Success."
    },
    "results": [
        {
            "symbol": "ZCBZ24US.CM",
            "symbolDescription": "US Corn Basis Idx Dec 2024",
            "commodity": "Corn (#2 Yellow)",
            "underlyingFuture": "ZCH25",
            "deliveryEnd": "2024-12-31T17: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=202412&indexGroup=nation&country=US&maxRecords=25&page=1&locationId=4435
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=202412&indexGroup=nation&country=US&maxRecords=25&page=1&locationId=4435

Response

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

CSV

GET

GET https://ondemand.websol.barchart.com/getGrainInstruments.csv?apikey=YOUR_API_KEY&instrumentType=indexBasis&instrumentRoot=ZC&deliveryMonth=202412&indexGroup=nation&country=US&maxRecords=25&page=1&locationId=4435
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=202412&indexGroup=nation&country=US&maxRecords=25&page=1&locationId=4435

Response

symbol,symbolDescription,commodity,underlyingFuture,deliveryEnd,state,county,indexGroup,country,region,countyFipsCode,districtCode,stateFipsCode
"ZCBZ24US.CM","US Corn Basis Idx Dec 2024","Corn (#2 Yellow)","ZCH25","2024-12-31T17: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' => '202412',
    'indexGroup' => 'nation',
    'country' => 'US',
    'maxRecords' => '25',
    'page' => '1',
    'locationId' => '4435',
];

$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", "202412", "nation", "US", "25", "1", "4435")

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', '202412', 'nation', 'US', '25', '1', '4435');

print $result;

Python

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

result = ondemand.service.getGrainInstruments('YOUR_API_KEY', 'indexBasis', 'ZC', '202412', 'nation', 'US', '25', '1', '4435')

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: '202412',
        indexGroup: 'nation',
        country: 'US',
        maxRecords: '25',
        page: '1',
        locationId: '4435',
    }
)

response.body