Economic Calendar is a live calendar of global economic and political events. An event is a potentially market moving announcement scheduled to come out at a particular date and time, such as:
•economic indicator announcements
•US Treasury announcements
•energy indicators
•political events, such as elections
WebAPI server provides historical calendar events per client request and provides new or updated calendar events in case of client subscription. Calendar events can be grouped into different types depending on the provider, country and categories.
InformationRequest allows requesting the following economic calendar data:
•List of available calendar event providers: InformationRequest.calendar_event_provider_list_request, see CalendarEventProviderListRequest
•List of available calendar event types: InformationRequest.calendar_event_type_list_request, see CalendarEventTypeListRequest
•List of available countries: InformationRequest.country_list_request, see CountryListRequest
•List of calendar events: InformationRequest.calendar_event_list_request, see CalendarEventListRequest
All information requests supports subscription (InformationRequest.subscribe=True) to updates.
Not all calendar events data is allowed to the customer. When requesting WebAPI for a customer, depending on the availability of entitlement to News services, the data in the response will be filtered. For example, if access is granted to “DJ News” for the customer, the Dow Jones calendar event provider and its specific calendar event types will be allowed. In addition, the calendar events themselves will be filtered by the calendar event subject relative to the entitlements for this provider.
Calendar event provider list request
The CalendarEventProviderListRequest does not contain additional parameters.
Client message:
{
"calendar_event_provider_list_request": {}
}
Server message contains CalendarEventProviderListReport report with list of calendar event providers with unique id.
Server message:
{
"calendar_event_provider_list_report": {
"providers": [
{
"id": 18,
"name": "USDA",
"description": "United States Department of
Agriculture"
}
]
}
}
Calendar event type list request
The CalendarEventTypeListRequest does not contain additional parameters.
Client message:
{
"calendar_event_type_list_request": {}
}
Server message contains CalendarEventTypeListReport report with list of calendar event types related to specified provider, country and category.
Server message:
{
"calendar_event_type_list_report": {
"types": [
{
"country_id": 330,
"provider_id": 18,
"provider_event_category_id": "1412",
"provider_event_detail_id": "1",
"category_description": "Foreign Coarse
Grains",
"detail_description": "Ending Stocks, Million Metric
Tons"
}
]
}
}
The CountryListRequest does not contain additional parameters.
Client message:
{
"country_list_request": {}
}
Server message contains CountryListReport report with list of available countries with unique id.
Server message:
{
"country_list_report": {
"countries": [
{
"country_id": 1,
"name": "United Arab Emirates",
"description": "United Arab Emirates",
"abbreviation": "UNI",
"country_code": "AE"
}
]
}
}
CalendarEventListRequest contains a number of parameters with which the customer can specify the expected results in the report:
•filter to skip events with specified empty attributes,
•time range for events.
Time range is limited by a number of full calendar days (in UTC) of past events. The default is 65 days. When subscribing to events, the updates sent do not depend on the time specified in the request, but only on the entitlements of a specific customer.
Client message:
{
"calendar_event_list_request": {
"from_utc_timestamp": {
"seconds": 1735719634,
"nanos": 897000000
},
"to_utc_timestamp": {
"seconds": 1748776834,
"nanos": 897000000
},
"skip_events_without_provider_event_category_id": false,
"skip_events_without_details": false
}
}
CalendarEventListReport contains list of calendar events filtered by request parameters and by the customer entitlements.
Server message:
{
"calendar_event_list_report": {
"calendar_events": [
{
"provider_id": 18,
"provider_event_id": "141220251",
"event_utc_timestamp": {
"seconds": 1736528400
},
"event_has_time": true,
"period": "Jan",
"description": "Foreign Coarse Grains",
"event_url": "https://www.usda.gov/",
"organization_name": "USDA",
"organization_url": "https://www.usda.gov/oce/commodity/wasde",
"details": [
{
"provider_event_detail_id": "2",
"description": "Output, Million Metric Tons",
"actual_value": {
"value": 1103.44,
"cqg_contract_symbol": "X.US.WSUGFCGOP",
"contract_id": 1669,
"time_bar_unit": 4
}
},
{
"provider_event_detail_id": "3",
"description": "Total Supply, Million Metric Tons",
"actual_value": {
"value": 1401.66,
"cqg_contract_symbol": "X.US.WSUGFCGTS",
"contract_id": 1671,
"time_bar_unit": 4
}
},
{
"provider_event_detail_id": "5",
"description": "Trade, Million Metric Tons",
"actual_value": {
"value": 162.07,
"cqg_contract_symbol": "X.US.WSUGFCGT",
"contract_id": 1670,
"time_bar_unit": 4
}
},
{
"provider_event_detail_id": "4",
"description": "Total Use, Million Metric Tons",
"actual_value": {
"value": 1191.54,
"cqg_contract_symbol": "X.US.WSUGFCGTU",
"contract_id": 1672,
"time_bar_unit": 4
}
},
{
"provider_event_detail_id": "1",
"description": "Ending Stocks, Million Metric Tons",
"actual_value": {
"value": 278.15,
"cqg_contract_symbol": "X.US.WSUGFCGES",
"contract_id": 1668,
"time_bar_unit": 4
}
}
],
"is_key_event": false,
"country_id": 330,
"actual_expected": false,
"provider_event_category_id": "1412"
}
]
}
}
Calendar event can refer to a specific time or to the entire day depending on the CalendarEvent.event_has_time attribute.
The similar events can be filtered by tuple of attributes:
•CalendarEvent.country_id
•CalendarEvent.provider_id
•CalendarEvent.provider_event_category_id
Calendar event can be related to several calendar event types by the presence of several details (additional filtering attribute CalendarEventDetail.provider_event_detail_id can be used).