GET /v1/calendar Premium (2x)

Economic Calendar

Query upcoming and recent economic events — interest rate decisions, employment reports, GDP releases, and more. Essential for risk-aware algorithmic trading: know what is coming before it moves the market.

Parameters

Parameter	Type	Required	Description
from	string	No	Start date in ISO 8601 or YYYY-MM-DD format. Defaults to today.
to	string	No	End date. Maximum 30-day range from the start date.
currencies	string	No	Comma-separated currency codes to filter by (e.g., USD,EUR,GBP).
impact	string	No	Filter by impact level: high, medium, or low.
q	string	No	Search event titles (max 100 characters). Example: "interest rate".
next_hours	integer	No	Return events in the next N hours (1-168). Overrides from/to when set.
country	string	No	Alias for currencies. Accepts the same comma-separated currency codes.
offset	integer	No	Number of results to skip. Default: 0.
limit	integer	No	Maximum events to return (1-500). Default: 100.

The `next_hours` Shortcut

The next_hours parameter is a convenience shortcut that replaces manual date math. Instead of calculating from and to values, pass next_hours=4 to retrieve all events within the next 4 hours from the current time. This is particularly useful for pre-session checks — for example, querying high-impact events 4 hours before the US session open to decide whether to reduce exposure or pause automated strategies.

When next_hours is set, it overrides any from and to values. The range starts from the current server time (UTC) and extends forward by the specified number of hours. Maximum value is 168 (one week).

The `country` Alias

The country parameter is an alias for currencies. Both accept the same comma-separated currency codes (USD, EUR, GBP, JPY, etc.) and can be used interchangeably. This provides a more intuitive parameter name when filtering events by country of origin rather than thinking in terms of currency pairs. If both are provided, currencies takes precedence.

Example Request

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://tickatlas.com/v1/calendar?currencies=USD&impact=high&next_hours=24&offset=0&limit=100"

Success Response

200 OK

{
  "success": true,
  "data": {
    "events": [
      {
        "id": "fed-rate-decision-20260404",
        "datetime": "2026-04-04T18:00:00Z",
        "currency": "USD",
        "event": "Fed Interest Rate Decision",
        "impact": "high",
        "forecast": "4.50%",
        "previous": "4.75%",
        "actual": null
      },
      {
        "id": "nfp-20260404",
        "datetime": "2026-04-04T12:30:00Z",
        "currency": "USD",
        "event": "Non-Farm Payrolls",
        "impact": "high",
        "forecast": "185K",
        "previous": "151K",
        "actual": "203K"
      }
    ],
    "count": 23,
    "range": {
      "from": "2026-04-04T00:00:00Z",
      "to": "2026-04-11T00:00:00Z"
    },
    "pagination": {
      "offset": 0,
      "limit": 100,
      "total": 23,
      "has_more": false
    }
  }
}

Python Example

Fetch high-impact USD events for the next 24 hours:

Python

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://tickatlas.com"

# Get high-impact USD events for the next 24 hours
resp = requests.get(f"{BASE}/v1/calendar", headers={
    "X-API-Key": API_KEY
}, params={
    "currencies": "USD",
    "impact": "high",
    "next_hours": 24
})

data = resp.json()
for event in data["data"]["events"]:
    print(f"{event['datetime']} | {event['event']} | "
          f"Forecast: {event['forecast']} | Previous: {event['previous']}")

JavaScript Example

JavaScript

const API_KEY = "YOUR_API_KEY";
const BASE = "https://tickatlas.com";

const params = new URLSearchParams({
  currencies: "USD",
  impact: "high",
  next_hours: "24",
  offset: "0",
  limit: "100"
});

const resp = await fetch(`${BASE}/v1/calendar?${params}`, {
  headers: { "X-API-Key": API_KEY }
});

const { data } = await resp.json();
console.log(`${data.count} events found`);

data.events.forEach(ev => {
  console.log(`${ev.datetime} | ${ev.currency} | ${ev.event}`);
});

Building an Upcoming Events Alert System

One of the most effective uses of the calendar endpoint is integrating it into your trading bot's risk management layer. The following example polls for high-impact events every 30 minutes and signals when exposure should be reduced:

Python · alert loop

import requests
import time
from datetime import datetime, timezone

API_KEY = "YOUR_API_KEY"
BASE = "https://tickatlas.com"

def check_upcoming_events(hours_ahead=4):
    """Check for high-impact events in the next N hours."""
    resp = requests.get(f"{BASE}/v1/calendar", headers={
        "X-API-Key": API_KEY
    }, params={
        "impact": "high",
        "next_hours": hours_ahead
    })

    events = resp.json()["data"]["events"]
    if events:
        print(f"[WARNING] {len(events)} high-impact event(s) "
              f"in the next {hours_ahead} hours:")
        for ev in events:
            print(f"  {ev['datetime']} - {ev['currency']} "
                  f"{ev['event']}")
        return True  # Signal to reduce position sizes or pause trading
    return False

# Poll every 30 minutes during trading hours
while True:
    risk_elevated = check_upcoming_events(hours_ahead=4)
    if risk_elevated:
        # Implement your risk reduction logic here
        pass
    time.sleep(1800)

Pair this with the Sessions endpoint to correlate event times with market session hours, and the Quotes endpoint to monitor real-time price reactions as events are released.

Data Source

Calendar data is sourced from ForexFactory and updated every 15 minutes. The actual field is populated once the data is released — until then it returns null. Forecast and previous values are available as soon as the event is scheduled. All timestamps are in UTC.

Use Cases

News-aware trading — Adjust strategy parameters or widen stop-losses ahead of scheduled high-impact releases like NFP or FOMC decisions.
Risk management — Automatically reduce position sizes or halt new entries when high-impact events are imminent. Prevents exposure to unpredictable volatility spikes.
Event-driven strategies — Build systems that trade the reaction to economic releases by comparing actual vs. forecast values and entering positions on the deviation.
Economic dashboard — Display a comprehensive calendar view in your trading dashboard, filtered by the currencies you actively trade.