Economic Calendar API Reference

The mental model: next_hours is the “what is coming?” window. prev_hours is the “what just released?” window. Combine them when an application needs context on both sides of now.

The country alias. country and currencies accept the same comma-separated currency codes and can be used interchangeably — country simply reads better when you think in terms of the country of origin rather than the currency pair. If both are supplied, currencies takes precedence.

Precedence rule: when either rolling window is present, from and to are ignored entirely. The 30-day ceiling applies to the resolved window, so the two maxima cannot be combined: prev_hours=96 with next_hours=720 resolves to 34 days and returns 400 RANGE_TOO_LARGE.

{
  "success": true,
  "data": {
    "events": [
      {
        "id": "acb808eac77e0bbe",
        "datetime": "2026-09-08T23:50:00+00:00",
        "currency": "JPY",
        "event": "M2 Money Stock y/y",
        "impact": "low",
        "forecast": "2.2%",
        "previous": "2.2%",
        "actual": null,
        "source": "secondary",
        "series_id": null
      },
      {
        "id": "7c1e9a04b2f35d68",
        "datetime": "2026-09-08T23:50:04+00:00",
        "currency": "JPY",
        "event": "BoJ M2 Money Stock y/y",
        "impact": "low",
        "forecast": "2.0%",
        "previous": "2.2%",
        "actual": "2.0%",
        "source": "primary",
        "series_id": "3f8a21c07d9e5b46"
      }
    ],
    "count": 2,
    "range": {
      "from": "2026-09-08T13:45:00",
      "to": "2026-09-12T19:45:00"
    },
    "pagination": {
      "offset": 0,
      "limit": 100,
      "total": 2,
      "has_more": false
    }
  }
}

Use series_id for history. The event id identifies one specific release row; series_id groups recurring releases of the same primary-stream indicator over time. Note that datetime is emitted with a +00:00 offset while data.range is echoed as naive UTC, preserving the original output contract.

Why the totals can look surprising: asking for each stream separately exposes the raw streams, and the default combined view hides a duplicate when both twins land on the same page. The invariant that always holds is primary.total + secondary.total == default.total, while the default count can be lower by exactly those hidden duplicates.

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

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']}")

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}`);
});

# What released in the last 48h, primary stream only
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://tickatlas.com/v1/calendar?prev_hours=48&impact=high&source=primary&limit=100"

# On plans that include live actuals, a released primary row carries
# its published "actual" alongside "forecast" and "previous".

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)

The alert loop is the pattern most teams reach for first: poll for high-impact events on a timer and let the result drive the risk layer — reduce position sizes, widen stops, or pause new entries while a release is imminent. Pair it with the Sessions endpoint to correlate event times with market hours, and with the Quotes endpoint to watch the price reaction as the figure prints.

Prefer SDKs? TickAtlas publishes official clients for Python, JavaScript, PHP and Go. View SDK documentation →

Building specifically around released values? Start at Starter or above. Pay as you go is the right tier for schedule and forecast workflows — it reads the whole calendar, it simply does not expose the released actual. Choosing a window does not change this: prev_hours only changes which events are listed, never which plans see a value.

General API errors: authentication, malformed requests and rate-limit responses are documented centrally. Open error handling →

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, so an unpredictable volatility spike never catches an open book.
• Event-driven strategies — Trade the reaction to a release by comparing actual against forecast and entering on the deviation.
• Economic dashboard — Render a full calendar view in your own product, filtered to the currencies your users actually trade.

Useful companions: pair the calendar with Trading Sessions to reason about market hours, and with Quotes to watch price behaviour around a release.

Adjacent endpoints: Trading Sessions → Market Heatmap → Real-Time Quotes →