getCmdtyStats API

The getCmdtyStats API is used to request information on various fundamentals, commodity statistics, and economic data. Users can request information by data series with historical information available through to inception for most series. cmdtyStats™ is the premier source of aggregated commodity statistics – all made available in one easy to use API.

All APIs

Contact Us to Get Access

Inputs

symbol required

A unique symbol that identifies a data series.

Type
string (A sequence of characters. (example: GOOG)) 
Example
USDA-SOYB-PROD-MS-96.CM 

startDate optional

The start date of the historical data query. This parameter should be set to the desired start date/time for the query (the result set will include records back to, and including, this value). If not set, the value will default to the 1 year back from current data. Note that if the date range requested by the user is more extensive than the user's permissions allow for, the output range will be determined based on an offset from the startDate.

Type
dateTime (A date and time in the format of YYYY-MM-DD HH:MI:SS<TIMEZONE_OFFSET>.) 
Example
20171211 
Default
20171211 

endDate optional

The end date of the historical data query. This parameter should be set to the desired end date/time for the query (the result set will include records back to, and including, this value). If not set, the value will default to the last day of current year. Note that if the date range requested by the user is more extensive than the user's permissions allow for, the output range will be determined based on an offset from the startDate.

Type
dateTime (A date and time in the format of YYYY-MM-DD HH:MI:SS<TIMEZONE_OFFSET>.) 
Example
20181211 
Default
20181231 

order optional

An arrangement of fields within a particular record (ascending or descending). This parameter can be set to one of two values ("asc" and "desc") in order to specify the chronological order of the result set returned.

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

Valid Values:
asc, desc

Outputs

Name / Requirement
Description
Type
symbol
always returned
A unique symbol that identifies a data series.
string
A sequence of characters. (example: GOOG)
seriesDescription
always returned
A short description of the data series, that is created via concatenation of the following 4 data elements delimited by semicolons: "item";"measurement,frequency,unitDescription";"area";"sourcing figure"
string
A sequence of characters. (example: GOOG)
item
always returned
The primary subject of data series
string
A sequence of characters. (example: GOOG)
measurement
always returned
The measured aspect of a item
string
A sequence of characters. (example: GOOG)
measurements
as requested
The class hierarchy of measurement
enum
A type which includes a list of valid possible values.
frequency
always returned
Periodicity with which the underlying data series is released, updated, or recorded
string
A sequence of characters. (example: GOOG)
unit
always returned
The unit associated with data series
string
A sequence of characters. (example: GOOG)
multiplier
always returned
The multiplier of unit
int
A numeric type defining a whole number. (example: 2)
area
always returned
Geographic location that defines the data series
string
A sequence of characters. (example: GOOG)
areaType
always returned
Geographic granularity or aggregation level of the data
string
A sequence of characters. (example: GOOG)
sources
always returned
The originating sources of a data series. May include organization, associated report, data table, down to sourcing figure
enum
A type which includes a list of valid possible values.
contents
as requested
The class hierarchy of commodity
enum
A type which includes a list of valid possible values.
unitDescription
always returned
Plain text description of unit associated with data series
string
A sequence of characters. (example: GOOG)
lastRefresh
always returned
Time of last update
date
A date in the format of YYYY-MM-DD.
stats
always returned
A time series array consisting of date and value for each applicable record. Date represents the last day of a period covering the underlying data, which is indicated by frequency. Value will be the underlying data record or null if not available for any reason.
enum
A type which includes a list of valid possible values.

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/getCmdtyStats.json?apikey=YOUR_API_KEY&symbol=USDA-SOYB-PROD-MS-96.CM&startDate=20171211&endDate=20181211&order=asc
Host: ondemand.websol.barchart.com

POST

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

apikey=YOUR_API_KEY&symbol=USDA-SOYB-PROD-MS-96.CM&startDate=20171211&endDate=20181211&order=asc

Response

{
    "status": {
        "code": 200,
        "message": "Success."
    },
    "results": [
        {
            "symbol": "USDA-SOYB-PROD-MS-96.CM",
            "seriesDescription": "Soybeans;Production,Annual,Bushel;Mississippi;Soybeans for Beans Area Harvested, Yield, and Production",
            "item": "Soybeans",
            "measurement": "Production",
            "frequency": "Annual",
            "unit": "Bushel",
            "multiplier": 1,
            "area": "Mississippi",
            "areaType": "State",
            "sources": [
                "USDA",
                "NASS",
                "Crop Production",
                "Soybeans for Beans Area Harvested, Yield, and Production"
            ],
            "unitDescription": "Bushel",
            "lastRefresh": "2018-08-10",
            "stats": [
                {
                    "date": "2017-12-31",
                    "value": "115010000"
                }
            ]
        }
    ]
}

XML

GET

GET https://ondemand.websol.barchart.com/getCmdtyStats.xml?apikey=YOUR_API_KEY&symbol=USDA-SOYB-PROD-MS-96.CM&startDate=20171211&endDate=20181211&order=asc
Host: ondemand.websol.barchart.com

POST

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

apikey=YOUR_API_KEY&symbol=USDA-SOYB-PROD-MS-96.CM&startDate=20171211&endDate=20181211&order=asc

Response


<?xml version="1.0" encoding="utf-8"?>
 <getCmdtyStats>
  <status>
   <code>200</code>
   <message>Success.</message>
  </status>
  <item>
   <symbol>USDA-SOYB-PROD-MS-96.CM</symbol>
   <seriesDescription>Soybeans;Production,Annual,Bushel;Mississippi;Soybeans for Beans Area Harvested, Yield, and Production</seriesDescription>
   <item>Soybeans</item>
   <measurement>Production</measurement>
   <frequency>Annual</frequency>
   <unit>Bushel</unit>
   <multiplier>1</multiplier>
   <area>Mississippi</area>
   <areaType>State</areaType>
   <sources>
    <source>USDA</source>
    <source>NASS</source>
    <source>Crop Production</source>
    <source>Soybeans for Beans Area Harvested, Yield, and Production</source>
   </sources>
   <unitDescription>Bushel</unitDescription>
   <lastRefresh>2018-08-10</lastRefresh>
   <stats>
    <stat>
     <date>2017-12-31</date>
     <value>115010000</value>
    </stat>
   </stats>
  </item>
 </getCmdtyStats>

CSV

GET

GET https://ondemand.websol.barchart.com/getCmdtyStats.csv?apikey=YOUR_API_KEY&symbol=USDA-SOYB-PROD-MS-96.CM&startDate=20171211&endDate=20181211&order=asc
Host: ondemand.websol.barchart.com

POST

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

apikey=YOUR_API_KEY&symbol=USDA-SOYB-PROD-MS-96.CM&startDate=20171211&endDate=20181211&order=asc

Response

symbol,seriesDescription,item,measurement,frequency,unit,multiplier,area,areaType,sources,unitDescription,lastRefresh,stats
"USDA-SOYB-PROD-MS-96.CM","Soybeans;Production,Annual,Bushel;Mississippi;Soybeans for Beans Area Harvested, Yield, and Production","Soybeans","Production","Annual","Bushel","1","Mississippi","State","USDA|NASS|Crop Production|Soybeans for Beans Area Harvested, Yield, and Production","Bushel","2018-08-10",""


PHP

<?php

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

$params = [
    'apikey' => 'YOUR_API_KEY',
    'symbol' => 'USDA-SOYB-PROD-MS-96.CM',
    'startDate' => '20171211',
    'endDate' => '20181211',
    'order' => 'asc',
];

$result = $ondemand->getCmdtyStats($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.getCmdtyStats("YOUR_API_KEY", "USDA-SOYB-PROD-MS-96.CM", "20171211", "20181211", "asc")

Perl

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

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

my $result = $ondemand->getCmdtyStats('YOUR_API_KEY', 'USDA-SOYB-PROD-MS-96.CM', '20171211', '20181211', 'asc');

print $result;

Python

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

result = client.service.getCmdtyStats('YOUR_API_KEY', 'USDA-SOYB-PROD-MS-96.CM', '20171211', '20181211', 'asc')

print result

Ruby

require 'savon'

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

response = ondemand.call(
    :getCmdtyStats,
    message: {
        apikey: 'YOUR_API_KEY',
        symbol: 'USDA-SOYB-PROD-MS-96.CM',
        startDate: '20171211',
        endDate: '20181211',
        order: 'asc',
    }
)

response.body