Economic Calendar API

getCmdtyCalendar

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.

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

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

20231221

Default

20231221

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

20241231

Default

20241231

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

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

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=20231221&endDate=20241231&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=20231221&endDate=20241231&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": []
}

XML

GET

GET https://ondemand.websol.barchart.com/getCmdtyCalendar.xml?apikey=YOUR_API_KEY&startDate=20231221&endDate=20241231&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=20231221&endDate=20241231&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=20231221&endDate=20241231&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=20231221&endDate=20241231&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' => '20231221',
    'endDate' => '20241231',
    '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", "20231221", "20241231", "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', '20231221', '20241231', '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 = ondemand.service.getCmdtyCalendar('YOUR_API_KEY', '20231221', '20241231', '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: '20231221',
        endDate: '20241231',
        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