FXStreet owns useful macroeconomic data on the most relevant economic events. This data can be accessed using the Economic Calendar API.
In this document:
- Basic Concepts
- Event Types
- Supported Languages
- Data Schema
- Data Format
- REST API
- Streaming (WebSocket) API
- Code Samples
- Appendix
You can take a quick look at some of this data in the Economic Calendar section of FXStreet's website.
Basic Concepts
The Economic Calendar data is composed of hundreds of important events. There are two kinds of entities that must be clearly understood when using our API.
Event
An event is a noteworthy entity that FXStreet editors have picked to include in the economic calendar. It is not associated with a specific date, as this is related to the concept of the event, such as the Nonfarm Payrolls.
An event can be recurrent (and have a frequency in which happens or in which data is released) and not. It may have one or many occurrences (that are associated with the event and a specific date and time).
It is specific to a country, related to a currency, has a category and other properties that are common for all occurrences of that recurrent event. This entity can also be referred to as Event.
Event Occurrence
An event occurrence is an instance of an event that happens in a specific date and time. An example of an event occurrence can be the data release of the Nonfarm Payrolls for December 2019.
An occurrence is usually related to a data release, so it can contain relevant values like the actual, consensus, etc.
This entity can also be referred to as EventDate.
Event Types
- Holidays
- Economic Activity
- Inflation
- Consumption & Inflation
- Liquidity & Balance
- Industrial & Non-Industrial Activity
- Central Banks
- Employment
- Labor Market
- Capital Flows
- Politics
- Confidence Indices
- Interest Rates
- Government
- Consumption
- Housing Market
- Bond Auctions
- Energy
Supported Languages
|
Language |
LanguageCode |
|
English |
en-GB |
|
Spanish |
es-ES |
|
German |
de-DE |
|
French |
fr-FR |
|
Italian |
it-IT |
|
Russian |
ru-RU |
|
Hungarian |
hu-HU |
|
Polish |
pl-PL |
|
Simplified Chinese |
zh-CN |
|
Traditional Chinese |
zh-HK |
|
Vietnamese |
vi-VN |
|
Persian |
fa-IR |
|
Arabic |
ar-AE |
|
Japanese |
ja-JP |
|
Indonesian |
id-ID |
|
Turkish |
tr-TR |
|
Thai |
th-TH |
|
Portuguese |
pt-PT |
Data Schema
The root element, Event, has the following attributes. These attributes are provided with an @ symbol preceding the name within the Event element of the parsed-event element in the API response.
This information is included in the FXStreet response type (ResponseType: 0 in the API).
The data schema is the same for both the Corporate Calendar and the Economic Calendar data from FXStreet.
|
Field Name |
Definition |
Data Type |
|
Id |
The unique identifier for an instance of the event. |
string |
|
EventId |
Id code which identifies a particular recurrent event (e.g., US GDP). |
string |
|
Name |
Name of the recurrent event |
string |
|
Description |
Description of the recurrent event. |
string |
|
HTMLDescription |
Description of the recurrent event in HTML format. |
string |
|
CountryId |
Unique identifier of the country of the event. |
string |
|
CountryCode |
Country code of the recurrent event (country code according to ISO 3166-1). |
string |
|
CountryName |
Name of the country. |
string |
|
EventTypeId |
Unique identifier of the event type (e.g., Economic Activity). |
string |
|
EventTypeDescription |
Description of the event type. |
string |
|
Potency |
Potency of the recurrent event |
int |
|
PotencySymbol |
Potency symbol of the recurring event (0, K, M, B, T) |
string |
|
CurrencyId |
Unique ID of the currency of the country of the recurring event. |
string |
|
CurrencySymbol |
Symbol of the currency of the country of the recurring event. |
string |
|
Symbol |
The "unit" of the indicator reported in the event. For example, will be % for Percentage values. |
string |
|
IsSpeech |
A flag to indicate that this event is a speech. |
boolean |
|
IsReport |
A flag to indicate that this event is a report. |
boolean |
|
RiseType |
Rise type of the recurrent event data (could be NEUTRAL, NEGATIVE, POSITIVE, if available). |
string |
|
IdEventDate |
Unique combination of the recurring event and the date which allows to track the instance of this specific recurring event. |
string |
|
DateUtc |
Date and time of the event occurrence (in date-time notation as defined by RFC 3339, section 5.6) |
string |
|
Comments |
Comments for the recurring event. |
string |
|
IsPreliminary |
A flag to indicate that the results in this event are preliminary. |
string |
|
PeriodType |
Period of the event data (could be NONE, DAY, MONTH, QUARTER) |
string |
|
ForPeriod |
The period this event covers (for example Q3 2022). |
string |
|
Volatility |
Volatility of the event occurrence (could be NONE, LOW, MEDIUM, HIGH) |
int |
|
Actual |
Actual value of the event occurrence |
float |
|
Consensus |
Consensus value of the event occurrence |
float |
|
Previous |
Value of the previous occurrence of its recurrent event |
float |
|
Revised |
Revised value of the event occurrence |
float |
|
IsTentative |
Indicates whether the event occurrence is tentative |
boolean |
|
IsAllDay |
Indicates whether the event occurrence lasts for the whole day |
boolean |
|
IsBetterThanExpected |
Indicates whether the actual value of the event occurrence is better than expected |
boolean |
|
UrlSource |
Official Source Link of the recurrent event. Example: https://www.bls.gov/news.release/empsit.toc.htm |
string |
|
CreateDateUtc |
Date when this event was originally added to the database. |
string |
|
AssetIds |
List of Acuity Asset IDs that this event affects. |
list of ints |
|
AssetClassIds |
List of the Acuity Asset Class IDs that this event affects. |
list of ints |
Data Format
There are two data formats that are currently supported: the full response and the simplified response.
The full response ("ResponseFormat": 0) is a JSON representation of the fields, attributes and values described above in the Data Schema section.
The simplified response ("ResponseFormat:" 1) is a JSON representation of only the required fields from the Data Schema section.
REST API
REST API should generally be used to retrieve an arbitrary or filtered list of Signal Stream trade ideas on demand for a specific time period in the past. For real time report retrieval please use the Streaming (WebSocket) API.
Documentation
Overview: https://api.acuitytrading.com/
Swagger URL: https://api.acuitytrading.com/swagger/index.html
Authentication
Documentation URL: https://api.acuitytrading.com/Security
Exchange your username and password for a Bearer token that you can pass with any request. The token is valid for 14 days.
Sample request
|
curl -L -X POST "https://api.acuitytrading.com/token" ^ |
Sample response
|
{ |
The retrieved access_token is the Bearer token that you can pass in the Authorization header of your API requests.
Common Requests
Endpoint: POST /api/fxevents
Get Events By Countries
Description:
Retrieve Events by a collection of ISO2 country codes.
Sample request
|
curl -L -X POST "https://api.acuitytrading.com/api/fxevents" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_BEARER_TOKEN" \ -d "{ \"StartDate\": \"2023-05-09T15:24:46+02:00\", \"EndDate\": \"2023-05-16T15:24:46+02:00\", \"LanguageCode\": \"en-gb\", \"Countries\": [\"EMU\", \"US\"], \"Count\": 100, \"FillAssetInfo\": true, \"ResponseFormat\": 0 }" |
A response sample is provided in the Appendix - REST API Response Sample section.
Get Events by Acuity Asset IDs
Description:
Retrieve a list of economic events for EURUSD (asset ID: 50) and Gold (asset ID: 46). It’s possible to retrieve corporate events this way as well, it’s simply necessary to obtain a list of Acuity Asset IDs before doing that.
Sample request
|
curl -L -X POST "https://api.acuitytrading.com/api/fxevents" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_BEARER_TOKEN" \ -d "{ \"StartDate\": \"2023-05-09T15:24:46+02:00\", \"EndDate\": \"2023-05-16T15:24:46+02:00\", \"LanguageCode\": \"en-gb\", \"AssetIds\": [50, 46], \"Count\": 100, \"FillAssetInfo\": true, \"ResponseFormat\": 0 }" |
Sample response is identical to the previous requests. A sample is provided in the Appendix - REST API Response Sample section.
Streaming (WebSocket) API
The purpose of this API is to deliver the Signal Stream trade ideas in real time after their publication and/or modification.
Documentation
Overview: https://api.acuitytrading.com/
Streaming API: https://api.acuitytrading.com/Streaming
FXStreet Calendar: https://api.acuitytrading.com/Streaming#fx-calendar-parameters
Authentication
To authenticate, you need to pass your API key in the server URL when connecting to Acuity API. Example: wss://api.acuitytrading.com/api/streaming?apiKey=YOUR_API_KEY
Common Subscription Parameters
Each subscription in the Streaming API has the following parameters:
|
{ |
"action" (string) could be either subscribe or unsubscribe
"topic" (string) could be assets or fxevents. Other topics are also supported, but require additional services to be enabled.
"format" (int) - either 0 (full response) or 1 (simplified response). Simplified response delivers only mandatory fields and can be easier to process.
Subscribe to All Economic Events
Sample subscription message
|
{ |
Subscribe to Events by Countries
Sample subscription message
|
{ |
Response Samples
insert message
This message type is sent when a brand new report is published. The same message type is also sent with an update. The user simply needs to replace the previously received event with the new data in full. Please see a sample message in the Appendix.
delete message
This message type is sent when a report has any of the fields updated. Please see a sample message in the Appendix.
Code Samples
For REST API you can use any language that supports sending/receiving web requests in JSON format.
For the Streaming (WebSocket) API, please consult the following pages:
Appendix
REST API Response Sample
|
[ { "Id": "55eed53c-cb46-4353-9e72-3a882247a6fe", "EventId": "7503eefc-3e94-46e7-bfe7-02f280d8b4f9", "Name": "IBD/TIPP Economic Optimism (MoM)", "Description": null, "HTMLDescription": "Economic optimism index, by <a href=\"http://www.tipponline.com/\" target=\"_blank\"> TechnoMetrica Institute of Policy and Politics (TIPP) of The Investor's Business Daily (IBD) </a> published, this index measures consumers' sentiments related to economic conditions. The report is based on a monthly survey in which nearly 1,000 adults nationwide assess their economic prospects over the next six months, their personal financial views and beliefs about economic policies. federal. If consumers are optimistic, they will buy more goods and services, which will cause domestic demand to grow and stimulate the economy. An index above 50 indicates consumer optimism and a index below 50 indicates consumer pessimism.", "CountryId": "0345d08a-7068-42e0-a65f-e2c6243c4de1", "CountryCode": "US", "CountryName": "United States", "EventTypeId": "e229c890-80fc-40f3-b6f4-b658f3a02635", "EventTypeDescription": "Consumption", "Potency": 0, "PotencySymbol": "", "CurrencyId": "USD", "CurrencySymbol": "$", "Symbol": "", "IsSpeech": false, "IsReport": false, "RiseType": "Positive", "IdEventDate": "55eed53c-cb46-4353-9e72-3a882247a6fe", "DateUtc": "2023-05-09T14:00:00Z", "Comments": "", "IsPreliminary": false, "PeriodType": "M", "ForPeriod": "2023-05-01T00:00:00Z", "Volatility": 1, "Actual": 41.6, "Consensus": 48.2, "HasRelatedContent": true, "Previous": 47.4, "Revised": null, "IsTentative": false, "IsAllDay": false, "IsBetterThanExpected": false, "HasNews": true, "HasRelateds": false, "HasHistory": true, "UrlSource": "https://tippinsights.com/", "CreateDateUtc": "2022-11-02T11:21:33.75Z", "AssetIds": [ 50 ], "AssetClassIds": [ 10027 ] } ] |
Streaming - INSERT message sample
|
{ "topic": "fxcalendar", "messageType": "insert", "id": "743304d2-c80b-496f-9a44-945542726228", "lang": "en-gb", "doc": { "Id": "935af7fa-c58d-4541-ae15-95a42ecd980a", "Name": "Nonfarm Productivity", "Description": null, "HTMLDescription": "The Non-farm Productivity released by the <a href=\"http://www.bls.gov/lpc/\" target=\"_blank\">Bureau of Labor Statistics of the US Department of Labor</a> shows the output per Hour of labor worked. Non-farm Productivity indicates the overall business health in the US, which has an influence on GDP. A high reading is positive (or bullish) for the USD, while a low reading is negative (or bearish).", "CountryId": "0345d08a-7068-42e0-a65f-e2c6243c4de1", "CountryName": "United States", "EventTypeId": "91da97bd-d94a-4ce8-a02b-b96ee2944e4c", "EventTypeDescription": "Labor Market", "Potency": 0, "PotencySymbol": "", "CurrencyId": "USD", "CurrencySymbol": "$", "Symbol": "%", "IsSpeech": false, "IsReport": false, "RiseType": "Positive", "IdEventDate": "743304d2-c80b-496f-9a44-945542726228", "DateUtc": "2023-06-01T12:30:00Z", "Comments": "", "IsPreliminary": false, "PeriodType": "Q", "ForPeriod": "2022-01-01T00:00:00Z", "Volatility": 2, "Actual": null, "Consensus": -2.7, "HasRelatedContent": true, "Previous": -2.7, "Revised": null, "IsTentative": false, "IsAllDay": false, "IsBetterThanExpected": null, "HasNews": false, "HasRelateds": false, "HasHistory": true, "UrlSource": null, "CreateDateUtc": "2022-11-04T15:31:46.323Z", "AssetIds": [ 3, 18, 28 ], "AssetClassIds": [ 6, 8, 10027, 10031 ] } } |
Streaming - Update sample
|
{ "topic": "fxcalendar", "messageType": "update", "id": "acf31575-8bb1-456c-8c52-6a882f7c8cac", "lang": "en-gb", "doc": { "Id": "4f50e4f8-cd33-428b-b721-5fb620b7f097", "Name": "ADP Employment Change", "Description": null, "HTMLDescription": "The Employment Change released by the <a href=\"http://adpemploymentreport.com/\" target=\"_blank\">Automatic Data Processing, Inc</a>, Inc is a measure of the change in the number of employed people in the US. Generally speaking, a rise in this indicator has positive implications for consumer spending, stimulating economic growth. So a high reading is traditionally seen as positive, or bullish for the USD, while a low reading is seen as negative, or bearish.", "CountryId": "0345d08a-7068-42e0-a65f-e2c6243c4de1", "CountryName": "United States", "EventTypeId": "91da97bd-d94a-4ce8-a02b-b96ee2944e4c", "EventTypeDescription": "Labor Market", "Potency": 3, "PotencySymbol": "K", "CurrencyId": "USD", "CurrencySymbol": "$", "Symbol": "", "IsSpeech": false, "IsReport": false, "RiseType": "Positive", "IdEventDate": "acf31575-8bb1-456c-8c52-6a882f7c8cac", "DateUtc": "2023-06-01T12:15:00Z", "Comments": "", "IsPreliminary": false, "PeriodType": "M", "ForPeriod": "2023-05-01T00:00:00Z", "Volatility": 3, "Actual": null, "Consensus": -22.0, "HasRelatedContent": true, "Previous": 296.0, "Revised": null, "IsTentative": false, "IsAllDay": false, "IsBetterThanExpected": null, "HasNews": false, "HasRelateds": false, "HasHistory": false, "UrlSource": null, "CreateDateUtc": "2022-03-24T11:19:23.213Z", "AssetIds": [ 3, 18, 28, 50, 58, 59, 69592 ], "AssetClassIds": [ 6, 8, 10027, 10031 ] } } |
If you haven't found what you're looking for yet, don't worry! Our team is here to assist you.