v2.0 • REST API

API Documentation

Economic Calendar REST API - Get real-time economic news with AI-powered analysis for traders.

Overview

Forex Calendar Pro provides real-time economic calendar data scraped from financial sources, with optional AI-powered analysis for traders. The API supports multiple timezones, impact filtering, and intelligent caching.

Base URL

https://api.forex-calendar.pro

Telegram Notifications

Pro users can receive a daily digest of economic news via Telegram before the trading day starts.

Find the bot

Search for @ForexCalendarProBot on Telegram

Get your ID

Send /start to the bot

Save your ID

Enter your Telegram ID in the application dashboard and save

Configure

From the dashboard: enable Telegram notifications and choose the types of announcements you want to receive

Enjoy

Receive your daily briefing and list of economic announcements every day

Authentication

Use the X-API-Key header to authenticate requests:

curl -H "X-API-Key: your_api_key" https://api.forex-calendar.pro/api/announcements

To get your API key, go to the dashboard

Dashboard

Plans & Access Levels

Feature	Free	Basic
/api/announcements (NY TZ)
/api/announcements (All TZ)
/api/announcements/week
/api/account/usage
/api/briefing/daily
/api/announcements/analyze
/api/notifications/settings
Telegram Daily Digest
AI Response Language	—	—

Endpoints

GET/

Returns API information and available endpoints.

GET/api/announcements

Get today's economic news with impact filtering.

GET/api/announcements/weekFree+

Get all news for the current week.

GET/api/briefing/dailyPro

Get an AI-generated daily briefing for traders.

GET/api/announcements/analyzePro

Get AI analysis of a specific economic news item.

GET/api/account/usageFree+

Get your account usage and rate limit status.

GET/api/notifications/settingsBasic+

Get or update your notification preferences.

GET/api/health

Health check endpoint.

GET /api/announcements

Get today's economic news.

Parameter	Type	Default	Description
`impact`	string	high,medium	Filter by impact level
`tz`	string	ny	Timezone code (Pro only)

{
  "scrapeDate": "2025-12-23T10:30:00.000Z",
  "announcementsCount": 5,
  "timezone": "paris",
  "announcements": [
    {
      "date": "Mon Dec 23",
      "time": "8:30am",
      "currency": "USD",
      "impact": "high",
      "announcement": "GDP q/q",
      "actual": "2.1%",
      "forecast": "2.0%",
      "previous": "1.8%"
    }
  ]
}

GET /api/announcements/week

Get all news for the current week. Requires Free plan or higher.

Parameter	Type	Default	Description
`impact`	string	all	Filter by impact level

Response format is the same as /api/announcements

{
  "scrapeDate": "2025-12-25T15:02:57.863Z",
  "announcementsCount": 3,
  "announcements": [
    {
      "date": "Tue Dec 23",
      "time": "8:30am",
      "currency": "CAD",
      "impact": "high",
      "announcement": "GDP m/m",
      "actual": "-0.3%",
      "forecast": "-0.3%",
      "previous": "0.2%"
    },
    {
      "date": "Tue Dec 23",
      "time": "8:30am",
      "currency": "USD",
      "impact": "high",
      "announcement": "Prelim GDP q/q",
      "actual": "4.3%",
      "forecast": "3.3%",
      "previous": "3.8%"
    },
    {
      "date": "Wed Dec 24",
      "time": "8:30am",
      "currency": "USD",
      "impact": "high",
      "announcement": "Unemployment Claims",
      "actual": "214K",
      "forecast": "224K",
      "previous": "224K"
    }
  ]
}

GET /api/briefing/daily

Get an AI-generated daily briefing for traders. Requires Pro plan.

Timezones	AI Response Language
paris	French
frankfurt	German
london, ny, dubai, mumbai, singapore, sydney	English
tokyo	Japanese
hongkong	Chinese

{
  "date": "2025-12-25",
  "announcementsCount": 14,
  "briefing": {
    "summary": "A mixed bag of economic data today, with Japan's Housing Starts y/y surprising with a -8.5% decline...",
    "key_announcements": [
      "12:00am | JPY | LOW | Housing Starts y/y",
      "6:50pm | JPY | LOW | Prelim Industrial Production m/m",
      "6:50pm | JPY | LOW | Retail Sales y/y"
    ],
    "market_movers": [
      "JPY: Housing Starts y/y (-8.5%) deviated significantly from forecast (0.2%)",
      "JPY: Prelim Industrial Production m/m and Retail Sales y/y may also have a significant impact"
    ],
    "risk_windows": [
      "6:50pm | JPY | LOW | Prelim Industrial Production m/m",
      "6:50pm | JPY | LOW | Retail Sales y/y"
    ],
    "currencies_in_focus": [
      "JPY: Surprising economic data and bank holidays will impact JPY pairs",
      "CHF: Bank holiday will lead to reduced trading volumes"
    ],
    "recommendation": "Focus on JPY pairs and be cautious of potential market volatility...",
    "volatility_forecast": "medium"
  },
  "announcements": [
    { "date": "Thu Dec 25", "time": "12:00am", "currency": "JPY", "impact": "low", "announcement": "Housing Starts y/y", "actual": "-8.5%", "forecast": "0.2%", "previous": "3.2%" },
    { "date": "Thu Dec 25", "time": "All Day", "currency": "CHF", "impact": "holiday", "announcement": "Bank Holiday", "actual": "", "forecast": "", "previous": "" },
    { "date": "Thu Dec 25", "time": "All Day", "currency": "EUR", "impact": "holiday", "announcement": "French Bank Holiday", "actual": "", "forecast": "", "previous": "" },
    "..."
  ],
  "language": "English",
  "generatedAt": "2025-12-25T15:05:15.245Z"
}

GET /api/announcements/analyze

Get AI analysis of a specific economic news item. Requires Pro plan.

Parameter	Type	Required	Description
announcement	string	Yes	Today's news title (the 'announcement' field returned by /api/announcements)
`currency`	string	No	Filter by currency
`tz`	string	No	Timezone for language selection

{
  "announcement": {
    "date": "Thu Dec 25",
    "time": "All Day",
    "currency": "EUR",
    "impact": "holiday",
    "announcement": "German Bank Holiday",
    "actual": "",
    "forecast": "",
    "previous": ""
  },
  "analysis": {
    "explanation": "A German Bank Holiday may cause reduced market liquidity and trading volumes in the EUR...",
    "importance": "This announcement is important for Forex traders as it can impact EUR price movements.",
    "scenarios": {
      "above_forecast": "If the holiday results in a significant increase in economic activity, the EUR may strengthen...",
      "below_forecast": "If the holiday leads to a decrease in economic activity, the EUR may weaken..."
    },
    "pairs_to_watch": ["EUR/USD", "EUR/GBP", "EUR/JPY", "EUR/CHF"],
    "risk_level": "medium",
    "trading_tip": "Consider scaling back positions or adjusting stop-loss levels ahead of the holiday..."
  },
  "language": "English",
  "generatedAt": "2025-12-25T15:06:33.662Z"
}

GET /api/account/usage

Get your account usage and rate limit status. Requires Free plan or higher.

{
  "plan": "pro",
  "email": "user@example.com",
  "language": "en",
  "telegramConfigured": true,
  "usage": {
    "requestsToday": 45,
    "requestsLimit": 100,
    "resetAt": "2025-12-23T11:00:00.000Z"
  },
  "createdAt": "2025-01-15T10:00:00.000Z",
  "lastUsedAt": "2025-12-23T10:30:00.000Z"
}

GET /api/notifications/settings

Get or update your notification preferences. Requires Basic plan or higher.

{
  "telegramEnabled": true,
  "telegramId": "123456789",
  "impactLevels": ["high", "medium"],
  "alertDelay": 15,
  "language": "en"
}

Timezones

Code	City	UTC Offset
ny	New York (default)	-5
paris	Paris	+1
frankfurt	Frankfurt	+1
london	London	+0
dubai	Dubai	+4
mumbai	Mumbai	+5:30
singapore	Singapore	+8
hongkong	Hong Kong	+8
tokyo	Tokyo	+9
sydney	Sydney	+11

Impact Levels

🔴

high

Major market-moving news (NFP, Interest Rates, GDP)

🟠

medium

Moderate impact news

🟡

low

Minor news with limited market impact

⚪

holiday

Bank holidays

Caching

Cache	Duration	Invalidation
News (Today)	Until midnight	Cron at 5 AM UTC
News (Week)	Until Monday	Cron on Mondays at 5 AM UTC
AI Briefing	Daily	When new results are published
AI Analysis	Daily	Per announcement

Error Responses

Rate Limiting

100 requests per 15 minutes per IP

Usage Examples

JavaScript (Fetch)

const response = await fetch('https://api.forex-calendar.pro/api/announcements?impact=high', {
  headers: { 'X-API-Key': 'your_api_key' }
});
const data = await response.json();

Python

import requests

headers = {'X-API-Key': 'your_api_key'}
response = requests.get(
    'https://api.forex-calendar.pro/api/announcements',
    params={'impact': 'high,medium'},
    headers=headers
)
data = response.json()

cURL

curl -H "X-API-Key: your_api_key" \
  "https://api.forex-calendar.pro/api/announcements?impact=all"

Need help? Contact us at wdltradingapi@gmail.com

Back to Home