Economic Calendar

Parameters

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 prev_hours Window — released actuals

prev_hours is the backward mirror of next_hours: it returns events that released in the past N hours together with their published actual values — a rolling "what just released" window purpose-built for release monitors, without the manual date math of from/to. The maximum is 96 hours; values above 96 are rejected (422). It is a live monitoring window, not a historical archive.

A pure prev_hours query is returned newest-first, so the latest release is on page 1. Set prev_hours and next_hours together for a window that straddles now ([now − prev_hours, now + next_hours], returned oldest-first); set neither to fall back to from/to or the default today-00:00 → +7d window. When prev_hours is set it overrides from/to, exactly like next_hours.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://tickatlas.com/v1/calendar?prev_hours=48&impact=high&limit=100"

actual values are a paid feature (Starter and above) — see Calendar Fields below. prev_hours changes only which events are listed; it does not unlock actuals for free-tier keys, which continue to receive actual: null.

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 -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

{
  "success": true,
  "data": {
    "events": [
      {
        "id": "fed-rate-decision-20260404",
        "datetime": "2026-04-04T18:00:00+00:00",
        "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:00+00:00",
        "currency": "USD",
        "event": "Non-Farm Payrolls",
        "impact": "high",
        "forecast": "185K",
        "previous": "151K",
        "actual": "203K"
      }
    ],
    "count": 23,
    "range": {
      "from": "2026-04-04T00:00:00",
      "to": "2026-04-11T00:00:00"
    },
    "pagination": {
      "offset": 0,
      "limit": 100,
      "total": 23,
      "has_more": false
    }
  }
}

Python Example

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

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

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:

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.

Calendar Fields

The actual field is populated the moment the figure is released, sourced from our live MT5 calendar feed (Forex Factory fills forecast/previous where the feed hasn't yet). It is available on plans that include live calendar actuals (Starter and above by default) — on Free/demo tiers it returns null by design, regardless of the time window queried. Use prev_hours to fetch recently released events with their actuals. 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.