Economic Calendar

This endpoint allows you to retrieve economic events and indicators from the global financial calendar.

The calendar event model

The calendar API returns detailed information about economic events, including forecasts, actual values, and metadata.

Properties

Name
id
Type
string
Description
Unique identifier for the event.
Name
event_id
Type
integer
Description
Numeric identifier for the event.
Name
code
Type
string
Description
Short code representing the event.
Name
name
Type
string
Description
Human-readable name of the event.
Name
importance
Type
integer
Description
Importance level (0-3, where higher is more important). See Importance Levels table below.
Name
impact
Type
integer
Description
Expected market impact level. See Impact Types table below.
Name
frequency
Type
integer
Description
How often the event occurs. See Frequency Types table below.
Name
sector
Type
integer
Description
Economic sector the event belongs to. See Sector Types table below.
Name
source
Type
string
Description
URL to the data source.
Name
type
Type
integer
Description
Type of the event. See Event Types table below.
Name
multiplier
Type
integer
Description
Value multiplier for the indicator. See Multiplier Types table below.
Name
time_mode
Type
integer
Description
Format of the time information. See Time Mode Types table below.
Name
unit
Type
integer
Description
Unit of measurement for the indicator values. See Unit Types table below.
Name
time
Type
string
Description
ISO 8601 timestamp when the event occurs.
Name
currency
Type
string
Description
Currency code related to the event.
Name
country
Type
string
Description
Country code where the event takes place (ISO 3166-1 alpha-2 format).
Name
previous
Type
string
Description
Previous value for the indicator.
Name
forecast
Type
string
Description
Forecasted value for the indicator.
Name
actual
Type
string
Description
Actual reported value for the indicator.
Name
flag
Type
string
Description
URL to the country flag image.

Importance Levels

The importance field indicates how significant the economic event is. Here are the possible values:

Name
NONE (0)
Type
default
Description
No significant importance.
Name
LOW (1)
Type
info
Description
Low importance event with minimal market impact.
Name
MODERATE (2)
Type
warning
Description
Moderately important event with potential market impact.
Name
HIGH (3)
Type
danger
Description
Highly important event with significant market impact.

Impact Types

The impact field indicates the expected market impact of the economic event. Here are the possible values:

Name
NA (0)
Type
default
Description
No specific market impact expected.
Name
POSITIVE (1)
Type
success
Description
Positive impact on the market expected.
Name
NEGATIVE (2)
Type
danger
Description
Negative impact on the market expected.

Frequency Types

The frequency field indicates how often the economic event occurs. Here are the possible values:

Name
NONE (0)
Type
info
Description
One-time event with no regular frequency.
Name
WEEK (1)
Type
info
Description
Weekly recurring event.
Name
MONTH (2)
Type
info
Description
Monthly recurring event.
Name
QUARTER (3)
Type
info
Description
Quarterly recurring event.
Name
YEAR (4)
Type
info
Description
Yearly recurring event.
Name
DAY (5)
Type
info
Description
Daily recurring event.

Multiplier Types

The multiplier field indicates the scale of the numeric values for the economic indicator. Here are the possible values:

Name
NONE (0)
Type
default
Description
No multiplier, value is as reported.
Name
THOUSANDS (1)
Type
info
Description
Value is in thousands (×1,000).
Name
MILLIONS (2)
Type
info
Description
Value is in millions (×1,000,000).
Name
BILLIONS (3)
Type
warning
Description
Value is in billions (×1,000,000,000).
Name
TRILLIONS (4)
Type
danger
Description
Value is in trillions (×1,000,000,000,000).

Sector Types

The sector field indicates the economic sector to which the event belongs. Here are the possible values:

Name
NONE (0)
Type
default
Description
No specific sector.
Name
MARKET (1)
Type
info
Description
Market-related indicators and events.
Name
GDP (2)
Type
info
Description
Gross Domestic Product and related economic output measures.
Name
JOBS (3)
Type
info
Description
Employment, unemployment, and labor market indicators.
Name
PRICES (4)
Type
info
Description
Inflation, consumer prices, and producer prices.
Name
MONEY (5)
Type
info
Description
Monetary policy, interest rates, and money supply.
Name
TRADE (6)
Type
info
Description
International trade, imports, and exports.
Name
GOVERNMENT (7)
Type
info
Description
Government spending, budget, and fiscal policy.
Name
BUSINESS (8)
Type
info
Description
Business activity, manufacturing, and services.
Name
CONSUMER (9)
Type
info
Description
Consumer sentiment, spending, and retail sales.
Name
HOUSING (10)
Type
info
Description
Housing market, construction, and real estate.
Name
TAXES (11)
Type
info
Description
Tax policy and tax-related announcements.
Name
HOLIDAYS (12)
Type
default
Description
Market holidays and closures.

Time Mode Types

The time_mode field indicates how the time information for the event should be interpreted. Here are the possible values:

Name
DATETIME (0)
Type
info
Description
Exact date and time are known and specified.
Name
DATE (1)
Type
info
Description
Only the date is known, without a specific time.
Name
NO_TIME (2)
Type
warning
Description
No specific time information is available.
Name
TENTATIVE (3)
Type
warning
Description
The date and time are tentative and subject to change.

Event Types

The type field indicates the category of the calendar entry. Here are the possible values:

Name
EVENT (0)
Type
info
Description
General economic event (e.g., central bank meeting, speech).
Name
INDICATOR (1)
Type
warning
Description
Economic indicator with numeric values (e.g., GDP, CPI).
Name
HOLIDAY (2)
Type
default
Description
Market or bank holiday.

Unit Types

The unit field indicates the unit of measurement for the indicator values. Here are the possible values:

Name
NONE (0)
Type
default
Description
No specific unit.
Name
PERCENT (1)
Type
info
Description
Percentage (%).
Name
CURRENCY (2)
Type
info
Description
Currency units (specific currency defined by the currency field).
Name
HOUR (3)
Type
info
Description
Hours of time.
Name
JOB (4)
Type
info
Description
Number of jobs.
Name
RIG (5)
Type
info
Description
Number of oil rigs.
Name
USD (6)
Type
info
Description
US Dollars, regardless of the event's country.
Name
PEOPLE (7)
Type
info
Description
Number of people.
Name
MORTGAGE (8)
Type
info
Description
Number of mortgages.
Name
VOTE (9)
Type
info
Description
Number of votes.
Name
BARREL (10)
Type
info
Description
Barrels (typically for oil).
Name
CUBIC_FEET (11)
Type
info
Description
Cubic feet (typically for natural gas).
Name
POSITION (12)
Type
info
Description
Number of positions.
Name
BUILDING (13)
Type
info
Description
Number of buildings.

GET/v1/marketplace/calendar

List calendar events

This endpoint retrieves a list of economic calendar events, with various filtering options.

Optional attributes

Name
per_page
Type
integer
Description
Number of events per page (default: 15, max: 100).
Name
page
Type
integer
Description
Page number for pagination.
Name
search
Type
string
Description
Search term to filter events by name or code.
Name
sort_by
Type
string
Description
Field to sort by (time, name, importance, impact, country, currency, sector).
Name
sort_direction
Type
string
Description
Sort direction (asc, desc).
Name
importance
Type
string
Description
Comma-separated list of importance levels to include. See Importance Levels table.
Name
impact
Type
string
Description
Comma-separated list of impact levels to include. See Impact Types table.
Name
country
Type
string
Description
Comma-separated list of country codes to include (ISO 3166-1 alpha-2 format, e.g., US,JP,GB).
Name
currency
Type
string
Description
Comma-separated list of currency codes to include.
Name
sector
Type
string
Description
Comma-separated list of sector IDs to include. See Sector Types table.
Name
type
Type
string
Description
Comma-separated list of event types to include. See Event Types table.
Name
time_mode
Type
string
Description
Comma-separated list of time mode types to include. See Time Mode Types table.
Name
unit
Type
string
Description
Comma-separated list of unit types to include. See Unit Types table.
Name
frequency
Type
string
Description
Comma-separated list of frequency types to include. See Frequency Types table.
Name
date_from
Type
string
Description
Start date for events (ISO 8601 format).
Name
date_to
Type
string
Description
End date for events (ISO 8601 format).

Request

GET

/v1/marketplace/calendar

curl -X GET "https://api.tradevps.net/v1/marketplace/calendar?date_from=2025-05-10&date_to=2025-05-15&importance=2,3&country=US,JP&per_page=15" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}"

Response

{
  "ok": true,
  "msg": "Calendar events fetched",
  "data": [
    {
      "id": "9eef2114-fef2-453c-a958-afac726bd851",
      "event_id": 156010001,
      "code": "cpi-mm",
      "name": "CPI m/m",
      "importance": 2,
      "impact": 1,
      "frequency": 2,
      "sector": 4,
      "source": "http://www.stats.gov.cn/english/",
      "type": 1,
      "multiplier": 0,
      "time_mode": 0,
      "period": "2025-03-31T21:00:00.000000Z",
      "unit": 1,
      "time": "2025-05-10T01:30:00.000000Z",
      "currency": "CNY",
      "country": "CN",
      "previous": "-0.4",
      "forecast": "-0.5",
      "actual": "0.1",
      "flag": "https://flags.apis.tradevps.net/cn.svg",
      "created_at": "2025-05-17T16:21:33.000000Z",
      "updated_at": "2025-05-17T16:21:33.000000Z"
    },
    // Additional events...
  ]
}

TradeVPS