getCmdtyCalendar API

The getCmdtyCalendar API provides user the latest updates of US economic activity and commodity trading events, including previous, revised, and actual values, updated 3 times a day. Users can request calendar events for desired period, and filter the output via various methods - category, importance, event country, and event symbol.

All APIs

Contact Us to Get Access

Inputs

startDate required

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 beginning of this data series. 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
20180520 
Default
20180520 

endDate required

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.

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

category optional

Filter returned result by category. Accept string concat category code by comma.

Type
list-enum (A comma or semi-colon delimited string that must match a list of valid possible values.) 
Example
Ag,Energy 
Default
All 

Valid Values:
All, Ag, Energy, Econ, Freight, Metals, Rates

country optional

Filter returned result by country/countries. Accept string concat iso-3 country code by comma.

Type
list (A comma or semi-colon delimited string.) 
Example
USA,CHN 
Default
All 

importance optional

Filter returned result by importance level/levels. Accept string concat integer by comma.
1 = low, 2 = medium, 3 = high

Type
list-enum (A comma or semi-colon delimited string that must match a list of valid possible values.) 
Example
2,1 

Valid Values:
1, 2, 3

symbol optional

Filter returned result by symbol. Accept valid symbol, which is a unique identifier of a time series, and multiple symbols separated by a comma.

Type
list (A comma or semi-colon delimited string.) 
Example
USCB-WHSLETRADE-SALES-CHG-SA-USA-13652.CM,USCB-WHSLETRADE-INV-CHG-SA-USA-13610.CM 

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

fields optional

Return extra columns if requested, invalid input is a string concats optional output fields by comma.

Type
list-enum (A comma or semi-colon delimited string that must match a list of valid possible values.) 
Example
reference_ending,prior_reference_ending 

Valid Values:
reference_ending, prior_reference_ending, status

Outputs

Name / Requirement
Description
Type
date
always returned
Release time and date in UTC.
dateTime
A date and time in the format of YYYY-MM-DD HH:MI:SS<TIMEZONE_OFFSET>.
country
always returned
Country Name.
string
A sequence of characters. (example: GOOG)
event
always returned
Specific event name in the calendar.
string
A sequence of characters. (example: GOOG)
report
always returned
Report that event data released from.
string
A sequence of characters. (example: GOOG)
source
always returned
Source of data.
string
A sequence of characters. (example: GOOG)
category
always returned
Category of event.
string
A sequence of characters. (example: GOOG)
reference
always returned
Reference period for latest released value.
string
A sequence of characters. (example: GOOG)
reference_ending
as requested
Ending date of the reference period in "YYYY-MM-DD" format.
date
A date in the format of YYYY-MM-DD.
actual
always returned
Latest released value.
double
A numeric type defining a number with fractional parts. (example: 2.14)
prior_reference_ending
as requested
Ending date of the prior reference period in "YYYY-MM-DD" format.
date
A date in the format of YYYY-MM-DD.
prior
always returned
Value for the previous period before the revision (if revision is applicable).
double
A numeric type defining a number with fractional parts. (example: 2.14)
revised
always returned
Value for the previous period after the revision (if revision is applicable).
double
A numeric type defining a number with fractional parts. (example: 2.14)
unit
always returned
Unit of the value.
string
A sequence of characters. (example: GOOG)
status
as requested
Event updating status.
string
A sequence of characters. (example: GOOG)
refreshed
always returned
Last refresh timestamp.
date
A date in the format of YYYY-MM-DD.
symbol
always returned
A unique identifier for event's time series stored in cmdtyStats.
string
A sequence of characters. (example: GOOG)
importance
always returned
The priority level of the event.
int
A numeric type defining a whole number. (example: 2)

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/getCmdtyCalendar.json?apikey=YOUR_API_KEY&startDate=20180520&endDate=20191231&category=Ag%2CEnergy&country=USA%2CCHN&importance=2%2C1&symbol=USCB-WHSLETRADE-SALES-CHG-SA-USA-13652.CM%2CUSCB-WHSLETRADE-INV-CHG-SA-USA-13610.CM&order=asc&fields=reference_ending%2Cprior_reference_ending
Host: ondemand.websol.barchart.com

POST

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

apikey=YOUR_API_KEY&startDate=20180520&endDate=20191231&category=Ag%2CEnergy&country=USA%2CCHN&importance=2%2C1&symbol=USCB-WHSLETRADE-SALES-CHG-SA-USA-13652.CM%2CUSCB-WHSLETRADE-INV-CHG-SA-USA-13610.CM&order=asc&fields=reference_ending%2Cprior_reference_ending

Response

{
    "status": {
        "code": 204,
        "message": "Success, but no content to return."
    },
    "results": null
}

XML

GET

GET https://ondemand.websol.barchart.com/getCmdtyCalendar.xml?apikey=YOUR_API_KEY&startDate=20180520&endDate=20191231&category=Ag%2CEnergy&country=USA%2CCHN&importance=2%2C1&symbol=USCB-WHSLETRADE-SALES-CHG-SA-USA-13652.CM%2CUSCB-WHSLETRADE-INV-CHG-SA-USA-13610.CM&order=asc&fields=reference_ending%2Cprior_reference_ending
Host: ondemand.websol.barchart.com

POST

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

apikey=YOUR_API_KEY&startDate=20180520&endDate=20191231&category=Ag%2CEnergy&country=USA%2CCHN&importance=2%2C1&symbol=USCB-WHSLETRADE-SALES-CHG-SA-USA-13652.CM%2CUSCB-WHSLETRADE-INV-CHG-SA-USA-13610.CM&order=asc&fields=reference_ending%2Cprior_reference_ending

Response


<?xml version="1.0" encoding="utf-8"?>
 <getCmdtyCalendar>
  <status>
   <code>204</code>
   <message>Success, but no content to return.</message>
  </status>
 </getCmdtyCalendar>

CSV

GET

GET https://ondemand.websol.barchart.com/getCmdtyCalendar.csv?apikey=YOUR_API_KEY&startDate=20180520&endDate=20191231&category=Ag%2CEnergy&country=USA%2CCHN&importance=2%2C1&symbol=USCB-WHSLETRADE-SALES-CHG-SA-USA-13652.CM%2CUSCB-WHSLETRADE-INV-CHG-SA-USA-13610.CM&order=asc&fields=reference_ending%2Cprior_reference_ending
Host: ondemand.websol.barchart.com

POST

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

apikey=YOUR_API_KEY&startDate=20180520&endDate=20191231&category=Ag%2CEnergy&country=USA%2CCHN&importance=2%2C1&symbol=USCB-WHSLETRADE-SALES-CHG-SA-USA-13652.CM%2CUSCB-WHSLETRADE-INV-CHG-SA-USA-13610.CM&order=asc&fields=reference_ending%2Cprior_reference_ending

Response


PHP

<?php

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

$params = [
    'apikey' => 'YOUR_API_KEY',
    'startDate' => '20180520',
    'endDate' => '20191231',
    'category' => 'Ag,Energy',
    'country' => 'USA,CHN',
    'importance' => '2,1',
    'symbol' => 'USCB-WHSLETRADE-SALES-CHG-SA-USA-13652.CM,USCB-WHSLETRADE-INV-CHG-SA-USA-13610.CM',
    'order' => 'asc',
    'fields' => 'reference_ending,prior_reference_ending',
];

$result = $ondemand->getCmdtyCalendar($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.getCmdtyCalendar("YOUR_API_KEY", "20180520", "20191231", "Ag,Energy", "USA,CHN", "2,1", "USCB-WHSLETRADE-SALES-CHG-SA-USA-13652.CM,USCB-WHSLETRADE-INV-CHG-SA-USA-13610.CM", "asc", "reference_ending,prior_reference_ending")

Perl

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

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

my $result = $ondemand->getCmdtyCalendar('YOUR_API_KEY', '20180520', '20191231', 'Ag,Energy', 'USA,CHN', '2,1', 'USCB-WHSLETRADE-SALES-CHG-SA-USA-13652.CM,USCB-WHSLETRADE-INV-CHG-SA-USA-13610.CM', 'asc', 'reference_ending,prior_reference_ending');

print $result;

Python

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

result = client.service.getCmdtyCalendar('YOUR_API_KEY', '20180520', '20191231', 'Ag,Energy', 'USA,CHN', '2,1', 'USCB-WHSLETRADE-SALES-CHG-SA-USA-13652.CM,USCB-WHSLETRADE-INV-CHG-SA-USA-13610.CM', 'asc', 'reference_ending,prior_reference_ending')

print result

Ruby

require 'savon'

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

response = ondemand.call(
    :getCmdtyCalendar,
    message: {
        apikey: 'YOUR_API_KEY',
        startDate: '20180520',
        endDate: '20191231',
        category: 'Ag,Energy',
        country: 'USA,CHN',
        importance: '2,1',
        symbol: 'USCB-WHSLETRADE-SALES-CHG-SA-USA-13652.CM,USCB-WHSLETRADE-INV-CHG-SA-USA-13610.CM',
        order: 'asc',
        fields: 'reference_ending,prior_reference_ending',
    }
)

response.body


Barchart OnDemand



Contact:
(312) 566-9235
solutions@barchart.com

Get updates on fintech and new products:

© 2019 Barchart.com, Inc.  |  Terms of Use & Privacy Policy

209 W. Jackson, 2nd Floor  |  Chicago, IL 60606