# Trader Calendar (forexfactory.com) (`pintostudio/trader-calendar-forexfactory-com`) Actor

Scrape the Forex Factory economic calendar: NFP, CPI, GDP, PMI, rate decisions and more. Get actual, forecast and previous values, impact level and a better/worse-than-forecast signal. Filter by date range, currency, impact and keyword in any time zone. Export JSON, CSV, Excel or use the API.

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

## Pricing

from $10.00 / 1,000 results

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

> 💬 **Need help? Contact us on Telegram: [@pintoflow](https://t.me/pintoflow)**
> This is the **fastest way to reach us** for questions, bug reports, feature requests or custom versions of this Actor. We usually reply much faster there than through any other channel.

Get the **ForexFactory economic calendar** as clean, structured data: interest rate decisions, CPI (inflation), Non-Farm Payrolls, GDP, PMI, central bank speeches, bank holidays and more. Every event comes with **actual, forecast and previous values** and an **impact level**.

Filter by **currency**, **impact**, **date range** and **keyword**, and get every time in **your own time zone**. Download the results as **JSON, CSV, Excel, XML or HTML**, or pull them from the Apify API.

***

### ✨ What can it do?

- 📅 **Any period:** today, tomorrow, this/next/last week or month, a specific day, week or month, or a **custom range of up to 2 years**
- 💱 **Filter by currency:** USD, EUR, GBP, JPY, AUD, NZD, CAD, CHF, CNY
- 🔴 **Filter by impact:** high, medium, low, holiday
- 🔎 **Search by keyword:** e.g. only "CPI" or "Non-Farm" releases
- 🌍 **Any time zone:** New York, London, Tokyo, Lisbon… Daylight saving time is handled automatically
- 📈 **Actual vs forecast:** each result is marked as `better` or `worse` for the currency
- ⚡ **Fast and light:** no browser needed, so runs finish in seconds and use very few compute units

***

### 🚀 How to use it (3 steps)

1. Click **Try for free** (or **Start**) on this page.
2. In the **Input** tab, pick a **Period** and, if you like, some **Currencies** and **Impact** levels.
3. Click **Start**. When the run finishes, open the **Output** tab to see your events in a table, or click **Export** to download them.

That's it. With the default settings you get **all events for this week** with times in **UTC**.

***

### ⚙️ Input options

| Field | What it does | Example |
|---|---|---|
| **Period** | Which days to scrape (see the list below) | `This week` |
| **Date** | Used with *Specific day* or *Specific week* | `2026-10-07` |
| **Month** | Used with *Specific month* (format `YYYY-MM`) | `2026-11` |
| **Start date / End date** | Used with *Custom range*, up to 731 days | `2026-01-01` → `2026-06-30` |
| **Currencies** | Keep only these currencies (empty = all) | `USD`, `EUR` |
| **Impact** | Keep only these impact levels (empty = all) | `High` |
| **Search in title** | Keep only events whose name contains this text | `CPI` |
| **Time zone** | Time zone for the `date` and `time` fields | `America/New_York` |
| **Include raw data** | Adds every original field from ForexFactory | off |
| **Proxy configuration** | Optional. Usually not needed | off |
| **Max retries** | How many times to retry a failed request | `2` |

**Period options:**

| Option | Meaning |
|---|---|
| Today / Tomorrow / Yesterday | One day |
| This week / Next week / Last week | A full week (Sunday → Saturday) |
| This month / Next month / Last month | A full month |
| Specific day | The day you set in **Date** |
| Specific week | The week containing the **Date** you set |
| Specific month | The month you set in **Month** |
| Custom range | From **Start date** to **End date** |

**Impact levels:**

| Value | Meaning |
|---|---|
| 🔴 `high` | Can move the market strongly (rate decisions, NFP, CPI…) |
| 🟠 `medium` | Moderate effect on the market |
| 🟡 `low` | Usually a small effect |
| ⚪ `holiday` | Bank holidays and non-economic events |

#### Example input (JSON)

High-impact USD and EUR events for next week, in London time:

```json
{
    "period": "next_week",
    "currencies": ["USD", "EUR"],
    "impacts": ["high"],
    "timezone": "Europe/London"
}
```

Every CPI release in the first half of 2026:

```json
{
    "period": "custom_range",
    "startDate": "2026-01-01",
    "endDate": "2026-06-30",
    "search": "CPI"
}
```

***

### 📦 Output

Each event is one row in the dataset:

```json
{
    "id": 147267,
    "title": "ISM Services PMI",
    "currency": "USD",
    "country": "US",
    "impact": "high",
    "date": "2026-10-05",
    "time": "10:00",
    "timezone": "America/New_York",
    "timestamp": "2026-10-05T14:00:00.000Z",
    "actual": "58.3",
    "forecast": "57.1",
    "previous": "56.0",
    "revision": null,
    "actualVsForecast": "better",
    "notice": null,
    "url": "https://www.forexfactory.com/calendar?day=oct5.2026#detail=147267",
    "scrapedAt": "2026-10-07T15:48:48.997Z"
}
```

| Field | Meaning |
|---|---|
| `id` | Unique event ID |
| `title` | Event name, e.g. `CPI m/m` |
| `currency` / `country` | Currency affected and country code |
| `impact` | `high`, `medium`, `low` or `holiday` |
| `date` | Day of the event, in **your time zone** (`YYYY-MM-DD`) |
| `time` | Time in **24-hour format** in your time zone, **or** a label when there's no exact time: `All Day`, `Tentative`, … |
| `timezone` | The time zone used for `date` and `time` |
| `timestamp` | Exact moment in UTC (ISO 8601). `null` when there's no exact time |
| `actual` | The released value. `null` until it's published |
| `forecast` | What economists expected |
| `previous` | The value from the last release |
| `revision` | The corrected previous value, if it was revised |
| `actualVsForecast` | `better` or `worse` for the currency, or `null` |
| `notice` | Special note about the event, if any |
| `url` | Link to the event on ForexFactory |
| `scrapedAt` | When the data was collected (UTC) |

> 💡 **How to read `actualVsForecast`:** `better` means the result came out **good for that currency**, which often pushes it **up**. `worse` means the opposite. It doesn't always mean a *higher number*: for unemployment, for example, a *lower* number is "better".

A **run summary** (period, filters, total vs saved events, source pages) is also saved in the key-value store under the key `OUTPUT`.

***

### 🔌 Use it from your code

Run the Actor and get the results in one call with the Apify API. Replace `YOUR_APIFY_TOKEN` with your token (Apify Console → **Settings → API & Integrations**) and `ACTOR_ID` with this Actor's ID (shown in the **API** tab on this page).

**cURL**

```bash
curl -X POST "https://api.apify.com/v2/acts/ACTOR_ID/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"period":"today","impacts":["high"],"timezone":"America/New_York"}'
```

**JavaScript (apify-client)**

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

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });

const run = await client.actor('ACTOR_ID').call({
    period: 'this_week',
    currencies: ['USD'],
    impacts: ['high'],
    timezone: 'America/New_York',
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((e) => console.log(`${e.date} ${e.time} ${e.currency} ${e.title}`));
```

**Python (apify-client)**

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run = client.actor("ACTOR_ID").call(run_input={
    "period": "today",
    "impacts": ["high", "medium"],
    "timezone": "Europe/London",
})

for event in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(event["time"], event["currency"], event["impact"], event["title"], event["actual"])
```

***

### ⏰ Schedule it

Want fresh data automatically? In Apify Console go to **Schedules → Create new**, choose this Actor and pick when to run it. For example:

- **Every Sunday evening:** `period = next_week`, to plan your trading week
- **Every morning:** `period = today`, `impact = high`, for a daily briefing
- **Every 15 minutes during the day:** `period = today`, to collect `actual` values as they're released

Connect it to **Google Sheets, Slack, Discord, Telegram, Zapier, Make or webhooks** using Apify **Integrations**.

***

### ❓ FAQ

**Do I need a proxy?**
Usually not. The Actor works without one. If you ever see blocked requests in the log, enable **Proxy configuration**.

**How far back can I go?**
Any date from 2007 onwards. One run can cover up to about 2 years with **Custom range**.

**Why is `actual` empty?**
The event hasn't happened yet, or it has no number (speeches, holidays, meetings).

**Why is `time` "All Day" or "Tentative" and `timestamp` empty?**
Some events have no exact release time. In that case `date` is still the scheduled day.

**Which time zone are times in?**
UTC by default. Set **Time zone** to any IANA name, such as `America/New_York`, `Europe/Berlin`, `Asia/Singapore` or `Australia/Sydney`.

**The run failed with "Invalid input". What did I do wrong?**
The message tells you exactly what's wrong. Most often it's a missing **Date** for *Specific day/week*, or a missing **Start/End date** for *Custom range*.

**Can I use it for a trading bot or Expert Advisor (EA)?**
Yes. A common pattern is a news filter: run it with `period = today` and `impact = high`, then pause trading for a few minutes around each event's `timestamp`.

***

### 📖 Glossary: economic calendar terms

| Term | What it is | Why traders care |
|---|---|---|
| **Interest Rate Decision** | The central bank sets its main rate (Fed, ECB, BoE, BoJ, RBA, BoC, SNB, RBNZ) | Usually the biggest market mover for a currency |
| **CPI (Consumer Price Index)** | Measures inflation, i.e. how fast prices are rising | High inflation can lead to higher rates and a stronger currency |
| **Core CPI / Core PCE** | Inflation without volatile food and energy prices | Central banks watch it closely |
| **NFP (Non-Farm Payrolls)** | Number of US jobs added last month, usually released on the first Friday | One of the most volatile releases for USD, gold and indices |
| **Unemployment Rate / Claims** | Share of people without a job / weekly jobless claims | A read on the labor market |
| **GDP** | Total economic output and growth | Overall health of the economy |
| **PMI** | Business activity survey; above 50 means expansion, below 50 means contraction | An early signal of where the economy is heading |
| **Retail Sales** | Change in consumer spending | Consumer spending drives a large part of growth |
| **FOMC Minutes / Statements** | Notes and statements from the US Federal Reserve | Hints about future rate moves |
| **m/m, q/q, y/y** | Month-over-month, quarter-over-quarter, year-over-year | Tells you what period the number compares against |
| **Flash / Prelim / Final** | First, preliminary and final estimates | Flash readings usually move the market most |
| **Bank Holiday** | Markets or banks closed in that country | Lower liquidity, so spreads can widen |

***

#### Who uses this Actor?

- **Forex traders** checking high-impact news before entering a trade
- **Trading bot and EA developers** adding a news filter to avoid volatility spikes
- **Fintech apps and websites** showing an economic calendar to their users
- **Discord and Telegram bots** posting daily or weekly market events and results
- **Analysts, researchers and students** building historical datasets of macroeconomic releases to study their effect on currencies, gold, oil, stocks and crypto
- **Content creators** preparing a weekly "news to watch" post

***

### 💬 Support

**Questions, problems or ideas? Message us on Telegram: [@pintoflow](https://t.me/pintoflow)**

Telegram is the **fastest way to get a response**. Reach out there for:

- Help setting up a run, schedule or integration
- Bug reports (please include your input and the error from the run log)
- Feature requests, such as new filters, fields or output formats
- Custom versions of this Actor

You can also open an issue in the **Issues** tab on this page.

***

**Keywords:** forex factory scraper, forexfactory calendar API, economic calendar scraper, forex calendar data, forex news API, high impact news, NFP release dates, CPI release dates, central bank calendar, interest rate decision dates, macroeconomic events dataset, historical economic calendar, trading bot news filter, MT4 / MT5 news filter, economic events export to CSV / Excel / JSON.

# Actor input Schema

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

Which days to scrape. Choose a ready-made period, or one of the 'Specific…' / 'Custom range' options and fill in the matching date field below.

## `date` (type: `string`):

Used when Period is 'Specific day' or 'Specific week'. Format YYYY-MM-DD. For a week, any day inside it works (weeks run Sunday → Saturday).

## `month` (type: `string`):

Used when Period is 'Specific month'. Format YYYY-MM, e.g. 2026-11.

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

Used when Period is 'Custom range'. Format YYYY-MM-DD.

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

Used when Period is 'Custom range'. Format YYYY-MM-DD. Ranges of up to 731 days (~2 years) are supported.

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

Only keep events for these currencies. Leave empty for all. 'ALL' = global events such as OPEC meetings.

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

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

## `search` (type: `string`):

Only keep events whose title contains this text (case-insensitive), e.g. 'CPI', 'Non-Farm', 'Rate'.

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

IANA time zone used for the 'date' and 'time' fields, e.g. UTC, America/New_York, Europe/London, Asia/Tokyo.

## `includeRaw` (type: `boolean`):

Add a 'raw' object to each event with every original field from ForexFactory.

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

Optional. The Actor works without a proxy in most cases. Enable a proxy only if you see blocked requests.

## `maxRetries` (type: `integer`):

How many times to retry a failed page request before switching to the fallback method.

## Actor input object example

```json
{
  "period": "this_week",
  "timezone": "UTC",
  "includeRaw": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  },
  "maxRetries": 2
}
```

# Actor output Schema

## `calendarEvents` (type: `string`):

Economic events with actual, forecast and previous values and impact level

## `allFields` (type: `string`):

Every scraped field, including exact UTC timestamp, revisions and notices

# 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 = {
    "period": "this_week",
    "timezone": "UTC",
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("pintostudio/trader-calendar-forexfactory-com").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 = {
    "period": "this_week",
    "timezone": "UTC",
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("pintostudio/trader-calendar-forexfactory-com").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 '{
  "period": "this_week",
  "timezone": "UTC",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call pintostudio/trader-calendar-forexfactory-com --silent --output-dataset

```

## MCP server setup

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

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/ek6Vlu4FsV18dTIxb/builds/NLgbg1Hx0GKMmLXho/openapi.json