# Forex Factory Economic Calendar Scraper (`trev0n/forexfactory-calendar-scraper`) Actor

Economic calendar events from Forex Factory.

- **URL**: https://apify.com/trev0n/forexfactory-calendar-scraper.md
- **Developed by:** [Paweł](https://apify.com/trev0n) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 calendar events

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 📅 Forex Factory Economic Calendar Scraper

🎯 **Every market-moving release from the Forex Factory economic calendar — actual, forecast, previous and revised figures — in your timezone, ready for your trading models, bots and dashboards.**

Get every scheduled event for USD, EUR, GBP, JPY, AUD, CAD, CHF, NZD and CNY: date and time converted to the timezone you choose, impact level (high / medium / low / holiday), category (inflation, employment, central bank…), the actual figure next to forecast and previous, revisions, and whether the print beat or missed. Add each indicator's specs (source, what it measures, usual effect, frequency, next release) and its past releases, back to 2000 for the major prints. Run it in **monitor mode** every few minutes and get only the actuals that were just released — straight to Telegram, Discord, Slack or your webhook.

### 🚀 What Does It Do?

This scraper reads the Forex Factory economic calendar and collects **structured, ready-to-use data** for any date range from 2007 to the end of next year. No copying tables by hand, no timezone math — pick your days, filters and timezone and hit Start.

💡 **Three ways to use it:**

1. **📆 Date range** — today, tomorrow, this / next / last week, this / next / last month, or any custom dates (years of history in one run).
2. **🔗 Calendar links** — paste any Forex Factory calendar link (a day, week, month or range — or one event) and get exactly what that page shows.
3. **🔔 Monitor mode** — schedule it every 1–15 minutes; each run outputs only the events whose actual just came out (or, if you prefer, every change: new events, forecast revisions, reschedules).

### 👥 Who Is This For?

| 🏢 Use Case | 💬 How It Helps |
| --- | --- |
| 🤖 **Algo & bot traders** | Feed actual vs forecast into your strategy seconds after the release, and pause trading around high-impact news |
| 📈 **Discretionary FX traders** | A clean weekly plan of high-impact events in your own timezone, plus alerts the moment NFP, CPI or a rate decision lands |
| 🧪 **Quants & researchers** | Years of releases with forecasts and revisions for backtesting news-driven moves and surprise indices |
| 📰 **Financial media & newsletters** | Auto-build "week ahead" calendars and "what just printed" posts |
| 🏦 **Brokers & fintech apps** | Power an in-app economic calendar or news-risk warnings without maintaining a scraper |
| 📊 **Analysts & dashboards** | Send the calendar to Google Sheets, Power BI or your database on a schedule |

### ✨ Features

- 🕒 **Your timezone, done right** — every date and time converted to any timezone (with daylight saving), plus the UTC time and Unix timestamp
- 🔥 **Impact levels** — high, medium, low and holiday / non-economic events
- 🏷️ **Categories** — growth, inflation, employment, central bank, bonds, housing, consumer and business surveys, speeches, misc
- 📊 **Actual / Forecast / Previous / Revised** — both as shown ("29K", "0.3%") and as numbers with their unit
- ✅ **Beat or miss** — whether the actual came in better or worse than forecast for the currency, and which way the previous was revised
- 📖 **Event specs** — source, what it measures, usual effect, frequency, next release date, notes and why traders care
- 🗂️ **Value history** — the last releases of each indicator, or the full series back to 2000 for major prints
- 🔔 **Monitor mode** — outputs only the actuals released since the last run; you pay only for what is new
- 📣 **Instant alerts** — Telegram, Discord, Slack or any webhook, with the figures and the surprise in the message
- 🎛️ **Smart Filters** — currencies, impact, category, keywords, exclusions, released-only
- 📜 **Deep history** — any range from 2007 onwards; long ranges are handled automatically
- ⚡ **Fast & Scalable** — a full month (400+ events) in about 10 seconds, years of history in one run
- 🔁 **Deduplication** — every event appears once, even across overlapping ranges
- 📤 **Export Anywhere** — Download results as JSON, CSV, Excel, or push to Google Sheets, Zapier, Make, or your CRM

### 🎛️ Filters & Options

| Option | What It Does |
| --- | --- |
| 📅 **Date range** | Today, tomorrow, yesterday, today + tomorrow, this / next / last week, this / next / last month, or custom dates |
| 📆 **Start / End date** | The exact days for a custom range |
| 🕒 **Timezone** | Timezone for all dates and times (and for what "today" means) |
| 🗓️ **Week starts on** | Sunday like Forex Factory, or Monday |
| 💱 **Currencies** | Only events for the currencies you trade |
| 🔥 **Impact** | Only high, medium, low or holiday events |
| 🏷️ **Categories** | Only inflation, employment, central bank, speeches… |
| 🔤 **Keywords** | Only events whose title contains words like "CPI", "Non-Farm", "PMI" |
| 🚫 **Exclude keywords** | Drop noise such as "Bond Auction" or "Speaks" |
| ✅ **Only events with an actual** | Keep only events that have already been released |
| 📖 **Include details & history** | Add each event's specs and past releases |
| 🗂️ **History length** | How many past releases per event — or the full series |
| 🔔 **Monitor mode** | Output only what changed since the last run |
| 🎯 **What to output in monitor mode** | Released actuals only, or all changes |
| 🧾 **Also output unchanged events** | Get the full list, each event tagged new / updated / unchanged |
| 🏷️ **Monitor name** | Keep several independent monitors side by side |
| 📣 **Alerts** | Webhook, Telegram, Discord and Slack, with how many events per message |
| 🔢 **Max Results** | Control how many events to extract per run |
| 🔗 **Direct URLs** | Optionally provide Forex Factory calendar links to scrape |

### 🧪 Example Inputs

**🔴 This week's high-impact USD and EUR events, in New York time**

```json
{
    "period": "thisWeek",
    "timezone": "America/New_York",
    "currencies": ["USD", "EUR"],
    "impacts": ["high"]
}
```

**🔔 "Just released" feed — run every 5 minutes, alert in Telegram**

```json
{
    "period": "today",
    "timezone": "Europe/London",
    "impacts": ["high", "medium"],
    "incrementalMode": true,
    "monitorEmit": "releases",
    "stateKey": "my-actuals-feed",
    "telegramBotToken": "123456:ABC-your-bot-token",
    "telegramChatId": "-1001234567890"
}
```

**🧪 Five years of US CPI and NFP with forecasts, for backtesting**

```json
{
    "period": "custom",
    "startDate": "2021-01-01",
    "endDate": "2025-12-31",
    "currencies": ["USD"],
    "keywords": ["CPI m/m", "Non-Farm Employment Change"]
}
```

**📖 Next week's central bank events with full specs and the last 12 releases**

```json
{
    "period": "nextWeek",
    "timezone": "Europe/Warsaw",
    "categories": ["centralBank"],
    "includeDetails": true,
    "historyLimit": 12
}
```

**🔗 A calendar link you already use**

```json
{
    "startUrls": [{ "url": "https://www.forexfactory.com/calendar?month=last" }],
    "impacts": ["high"]
}
```

### 📦 What You Get (Output Fields)

Every calendar event includes:

#### 🗓️ Event

| Field | Example |
| --- | --- |
| eventId | `146912` |
| title | `Non-Farm Employment Change` |
| fullTitle | `US Non-Farm Employment Change` |
| currency | `USD` |
| countryCode / country | `US` / `United States` |
| impact | `high` |
| impactTitle | `High Impact Expected` |
| category | `Employment` |
| eventUrl | `https://www.forexfactory.com/calendar?day=oct2.2026#detail=146912` |
| eventTypeUrl | `https://www.forexfactory.com/calendar/66-us-non-farm-employment-change` |

#### 🕒 Time

| Field | Example |
| --- | --- |
| date | `2026-10-02` |
| time | `08:30` |
| dateTime | `2026-10-02T08:30:00-04:00` |
| dateTimeUtc | `2026-10-02T12:30:00.000Z` |
| timestamp | `1790944200` |
| timezone | `America/New_York` |
| timeStatus | `scheduled` (or `allDay`, `tentative`, `other`) |
| timeLabel | `null` (or `All Day`, `Tentative`, `Day 2`) |

#### 📊 Figures

| Field | Example |
| --- | --- |
| actual / forecast / previous | `29K` / `89K` / `162K` |
| revisedPrevious | `133K` |
| actualValue / forecastValue / previousValue / revisedPreviousValue | `29` / `89` / `162` / `133` |
| unit | `K` |
| isReleased | `true` |
| actualVsForecast | `worse` |
| revisionDirection | `worse` |
| notice | `Source released data 2 days earlier than scheduled` |

#### 📖 Details & History (when details are on)

| Field | Example |
| --- | --- |
| details.source | `Bureau of Labor Statistics` |
| details.measures | `Change in the number of employed people during the previous month, excluding the farming industry` |
| details.usualEffect | `'Actual' greater than 'Forecast' is good for currency` |
| details.frequency | `Released monthly, usually on the first Friday after the month ends` |
| details.nextReleaseDate | `2026-11-06` |
| details.whyTradersCare | `Job creation is an important leading indicator of consumer spending…` |
| history | `[{ "date": "2026-09-04", "actual": "162K", "forecast": "55K", "revisedActual": "133K" }, …]` |

#### 🔔 Monitor mode

| Field | Example |
| --- | --- |
| changeType | `UPDATED` |
| actualReleased | `true` |
| changedFields | `["actual"]` |
| previousActual | `null` |
| firstSeenAt | `2026-10-02T12:00:04.512Z` |

### 📊 Example Output

```json
{
    "eventId": 146912,
    "eventTypeId": 66,
    "title": "Non-Farm Employment Change",
    "fullTitle": "US Non-Farm Employment Change",
    "currency": "USD",
    "region": "US",
    "countryCode": "US",
    "country": "United States",
    "impact": "high",
    "impactTitle": "High Impact Expected",
    "category": "Employment",
    "date": "2026-10-02",
    "time": "08:30",
    "dateTime": "2026-10-02T08:30:00-04:00",
    "dateTimeUtc": "2026-10-02T12:30:00.000Z",
    "timestamp": 1790944200,
    "timezone": "America/New_York",
    "timeStatus": "scheduled",
    "timeLabel": null,
    "actual": "29K",
    "forecast": "89K",
    "previous": "162K",
    "revisedPrevious": "133K",
    "actualValue": 29,
    "forecastValue": 89,
    "previousValue": 162,
    "revisedPreviousValue": 133,
    "unit": "K",
    "isReleased": true,
    "actualVsForecast": "worse",
    "revisionDirection": "worse",
    "hasDataValues": true,
    "notice": null,
    "eventUrl": "https://www.forexfactory.com/calendar?day=oct2.2026#detail=146912",
    "eventTypeUrl": "https://www.forexfactory.com/calendar/66-us-non-farm-employment-change",
    "details": {
        "source": "Bureau of Labor Statistics",
        "sourceUrl": "https://www.bls.gov/",
        "latestReleaseUrl": "http://www.bls.gov/news.release/empsit.nr0.htm",
        "measures": "Change in the number of employed people during the previous month, excluding the farming industry",
        "usualEffect": "'Actual' greater than 'Forecast' is good for currency",
        "frequency": "Released monthly, usually on the first Friday after the month ends",
        "nextRelease": "Nov 6, 2026",
        "nextReleaseDate": "2026-11-06",
        "nextReleaseUrl": "https://www.forexfactory.com/calendar?day=nov6.2026#detail=146914",
        "notes": "This is vital economic data released shortly after the month ends. The combination of importance and earliness makes for hefty market impacts",
        "whyTradersCare": "Job creation is an important leading indicator of consumer spending, which accounts for a majority of overall economic activity",
        "alsoCalled": "Non-Farm Payrolls, NFP, Employment Change"
    },
    "history": [
        {
            "eventId": 146911,
            "date": "2026-09-04",
            "period": "Sep 2026",
            "actual": "162K",
            "forecast": "55K",
            "revisedActual": "133K",
            "actualValue": 162,
            "forecastValue": 55,
            "revisedActualValue": 133
        }
    ],
    "scrapedAt": "2026-10-20T20:18:33.764Z"
}
```

### 📋 Dataset Views

The Apify Console gives you **5 ready-made table views** to quickly browse your results:

| View | What It Shows |
| --- | --- |
| 📊 **Overview** | Date, time, currency, impact, event, actual / forecast / previous, beat or miss |
| 🔢 **Figures** | The parsed numbers with units, ready for analysis |
| 🔔 **Monitor** | What changed since the last run and which actuals were just released |
| 📖 **Details** | Event specs and history |
| 📋 **Full Details** | Every single field — the complete dataset |

### ❓ FAQ

**🤔 Which timezone are the times in?**
The one you choose — any timezone name such as `America/New_York`, `Europe/London` or `Asia/Tokyo`, daylight saving included. Every event also has its UTC time and a Unix timestamp, so nothing is ambiguous. "Today" and "this week" are counted in your timezone too.

**🤔 How fast do I get a fresh actual?**
As fast as you schedule it. A monitor run takes a few seconds; scheduled every minute or every few minutes, you see the actual shortly after Forex Factory shows it. Only the new releases are output, so frequent runs stay cheap.

**🤔 What about holidays and "Tentative" events?**
They are included with `timeStatus` set to `allDay`, `tentative` or `other`, the original label (e.g. "Day 2") and no clock time — they stay on the calendar day Forex Factory lists them under.

**🤔 How far back does the history go?**
The calendar itself goes back to 2007 — ask for any custom date range. With details on, the history of a major indicator goes back to 2000.

**🤔 Can I export the data?**
Yes — JSON, CSV, Excel, XML, HTML, RSS. You can also push data directly to Google Sheets, Zapier, Make, or any webhook/API endpoint.

**🤔 How often should I run this?**
Weekly or daily for planning; every few minutes in monitor mode for live releases. You can schedule automatic runs on Apify with just a few clicks.

**🤔 Does it work with proxies?**
Yes — it works with Apify's built-in proxy service and the standard datacenter proxy is all it needs. No residential proxy required.

### 🛠️ Need Custom Filters or Features?

**I'm happy to customize this scraper for your specific needs!** 🤝

Whether you need:

- 🎯 Additional filters (only surprises above a threshold, only first-tier indicators, per-currency watchlists)
- 📊 Extra data fields or custom output formats
- 🔄 Integration with your CRM, Google Sheets, or database
- ⏰ Scheduled scraping with automatic deduplication
- 🌐 Scraping from other economic calendar platforms alongside Forex Factory

👉 **Don't hesitate to reach out via private message** — I respond quickly and I'm always open to building exactly what you need. No request is too small or too specific!

### ⚖️ Legal & Ethical Use

This scraper collects **only publicly available information** from the Forex Factory calendar. It does not log in, access private data or touch the forum. Forex Factory is an independent site not affiliated with this tool; please use the data responsibly and in compliance with applicable laws and the site's terms of service.

# Actor input Schema

## `period` (type: `string`):

Which days to scrape, counted in the timezone you pick below. Weeks run Sunday to Saturday like the Forex Factory week view (switch to Monday below). Choose "Custom" to set exact dates.

## `startDate` (type: `string`):

First day for the "Custom dates" range, YYYY-MM-DD. History goes back to 2007-01-01; long ranges are split automatically.

## `endDate` (type: `string`):

Last day (inclusive) for the "Custom dates" range, YYYY-MM-DD. Leave empty for a single day.

## `timezone` (type: `string`):

IANA timezone for every date and time in the output and for the date range, e.g. "UTC", "America/New_York", "Europe/London", "Europe/Warsaw", "Asia/Tokyo", "Australia/Sydney". UTC times are always included too.

## `weekStartsOn` (type: `string`):

First day of the week for "This / Next / Last week".

## `currencies` (type: `array`):

Only events for these currencies. Leave empty for all. "All" = global events such as IMF or OPEC meetings.

## `impacts` (type: `array`):

Only events with these expected impact levels. Leave empty for all.

## `categories` (type: `array`):

Only these event categories (Forex Factory's own classification). Leave empty for all. Every event carries its category either way.

## `keywords` (type: `array`):

Only events whose title contains any of these words (case-insensitive), e.g. "CPI", "Non-Farm", "PMI", "Rate", "Lagarde".

## `excludeKeywords` (type: `array`):

Drop events whose title contains any of these words, e.g. "Bond Auction", "Speaks".

## `onlyReleased` (type: `boolean`):

Keep only events whose actual figure is already published.

## `includeDetails` (type: `boolean`):

Add each event's specs (source, what it measures, usual effect, frequency, next release, notes, why traders care) and its past releases. One extra request per event.

## `historyLimit` (type: `integer`):

How many past releases to add per event when details are on. 5 comes with the details; more (e.g. 24, 120) reads the full series, back to 2000 for major indicators. 0 = none, -1 = everything.

## `incrementalMode` (type: `boolean`):

Remember figures between runs and output only what moved. Schedule the actor every few minutes to get a "just released" feed of actuals.

## `monitorEmit` (type: `string`):

"Released actuals" outputs only events whose actual is new or changed since the last run (the first run outputs the actuals already out). "All changes" also reports new events, forecast revisions and reschedules.

## `emitUnchanged` (type: `boolean`):

Output every event, each tagged NEW / UPDATED / UNCHANGED.

## `stateKey` (type: `string`):

Name of the memory used to compare runs. Runs with the same name share it. Leave empty to derive it from your filters.

## `webhookUrl` (type: `string`):

POST a JSON alert (message + events) here whenever there is something to output.

## `telegramBotToken` (type: `string`):

Bot token from @BotFather, to get alerts in Telegram.

## `telegramChatId` (type: `string`):

Chat or channel ID the bot posts to.

## `discordWebhookUrl` (type: `string`):

Discord channel webhook for alerts.

## `slackWebhookUrl` (type: `string`):

Slack incoming-webhook URL for alerts.

## `notificationLimit` (type: `integer`):

How many events to list in one alert message.

## `startUrls` (type: `array`):

Optional: paste calendar links instead of a date range, e.g. https://www.forexfactory.com/calendar?week=next, ?day=oct2.2026, ?month=last, ?range=oct1.2026-oct31.2026. A link with #detail=… returns just that event. Filters above still apply.

## `maxResults` (type: `integer`):

Stop after this many events. 0 = no limit.

## `maxConcurrency` (type: `integer`):

How many requests run at once.

## `proxyConfiguration` (type: `object`):

Apify datacenter proxy is the default and works. Residential is not needed.

## Actor input object example

```json
{
  "period": "thisWeek",
  "timezone": "UTC",
  "weekStartsOn": "sunday",
  "onlyReleased": false,
  "includeDetails": false,
  "historyLimit": 5,
  "incrementalMode": false,
  "monitorEmit": "releases",
  "emitUnchanged": false,
  "notificationLimit": 10,
  "maxResults": 0,
  "maxConcurrency": 5,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

## `details` (type: `string`):

No description

## `runSummary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "timezone": "UTC",
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("trev0n/forexfactory-calendar-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "timezone": "UTC",
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("trev0n/forexfactory-calendar-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "timezone": "UTC",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call trev0n/forexfactory-calendar-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,trev0n/forexfactory-calendar-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/vSnZ4mjkeEGpI6z3E/builds/eoDgpLCBraCKxyjGa/openapi.json