# Forex Factory Calendar Scraper - Economic Events & Forecasts (`topapi/forexfactory-scraper`) Actor

Scrape the Forex Factory economic calendar for this week: every event with UTC and local time, currency, country, impact, type, forecast, previous and parsed numbers. Plus Metals Mine, Energy EXCH and Crypto Craft calendars, filters, news window and monitor mode. $0.36 per 1,000 events.

- **URL**: https://apify.com/topapi/forexfactory-scraper.md
- **Developed by:** [Top Api](https://apify.com/topapi) (community)
- **Categories:** Business, News, Automation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.36 / 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 Calendar Scraper - Economic Events & Forecasts

Scrape the **Forex Factory economic calendar** for the current week: every event (CPI, Non-Farm Payrolls, rate decisions, PMIs, GDP, speeches, bond auctions, holidays) with its **release time in UTC and in your time zone, currency, country, impact (High / Medium / Low / Holiday), event type, consensus forecast and previous value**, the numbers parsed (`0.2%` -> `0.2`, unit `%`), the direction the forecast expects against the previous release, minutes until the release and the event's Forex Factory link. The same for Forex Factory's sister calendars **Metals Mine, Energy EXCH and Crypto Craft**, which rate impact for their own markets. Filters, a news window for trading bots, monitor mode and webhooks. No login, no browser, no API key.

### What you get

| What you choose | Example | What you get |
|---|---|---|
| Forex Factory, this week | the prefilled input | Every event of the week, Sunday to Saturday (105 events in the week of 2026-11-08) |
| A period | `today`, `tomorrow`, `todayAndTomorrow`, `upcoming`, custom dates, or `hoursAhead: 24` | Only those days or hours, counted in your time zone |
| Filters | High impact, USD + EUR, inflation and employment, title contains `CPI` | Only the events you trade |
| Other calendars | `metalsmine`, `energyexch`, `cryptocraft` | The same events rated for metals, energy or crypto (crude oil inventories: Low on Forex Factory, High on Energy EXCH) |
| Monitor mode | scheduled hourly | Only events that are new or whose time, impact, forecast or previous changed since the last run |

### Quick input

```json
{
  "calendars": ["forexfactory"],
  "period": "thisWeek",
  "timezone": "UTC"
}
```

This is the prefilled input: the whole week on Forex Factory in about one second. With no input at all, the same runs.

More examples:

```json
{ "impacts": ["High"], "currencies": ["USD", "EUR", "GBP"], "period": "upcoming", "timezone": "America/New_York" }
```

```json
{ "keywords": ["CPI", "Non-Farm", "Rate"], "onlyWithForecast": true, "sortBy": "impact" }
```

```json
{ "impacts": ["High"], "hoursAhead": 24, "newsWindowMinutes": 30, "timezone": "Europe/London" }
```

```json
{ "calendars": ["forexfactory", "energyexch", "metalsmine", "cryptocraft"], "impacts": ["High", "Medium"] }
```

```json
{ "monitorMode": true, "impacts": ["High", "Medium"], "webhookUrl": "https://example.com/hook" }
```

### Input

| Field | What it does | Default |
|---|---|---|
| `calendars` | `forexfactory`, `metalsmine`, `energyexch`, `cryptocraft`. One row per event per calendar. | `["forexfactory"]` |
| `period` | `thisWeek`, `today`, `tomorrow`, `yesterday`, `todayAndTomorrow`, `upcoming` (still ahead), `custom` (uses `dateFrom` / `dateTo`). Days are counted in `timezone`. | `thisWeek` |
| `dateFrom`, `dateTo` | Custom period, `YYYY-MM-DD`, inclusive, inside the current week. Setting a date switches the period to custom. | - |
| `hoursAhead` | Only events releasing within the next N hours. | - |
| `timezone` | IANA name (`America/New_York`, `Europe/London`, `Asia/Tokyo` ...) for `date`, `time` and `localDateTime`. `dateTimeUtc` is always UTC. | `UTC` |
| `impacts` | Any of `High`, `Medium`, `Low`, `Holiday`. `minImpact` (`high` / `medium` / `low`) works too. | all |
| `currencies` | `USD`, `EUR`, `GBP`, `JPY`, `AUD`, `CAD`, `CHF`, `NZD`, `CNY`, `All` (global events), and `MXN`, `RUB`, `INR`, `ZAR`, `BRL` on the sister calendars. | all |
| `categories` | `growth`, `inflation`, `employment`, `centralBank`, `bonds`, `housing`, `consumerSurveys`, `businessSurveys`, `speeches`, `misc`. | all |
| `keywords` | Keep events whose title, currency or country contains one of these (case-insensitive). | - |
| `excludeKeywords` | Drop events whose title contains one of these, e.g. `Speaks`, `Auction`. | - |
| `eventStatus` | `all`, `upcoming` (release time still ahead), `passed`. `upcomingOnly: true` and `onlyReleased: true` work too. | `all` |
| `onlyWithForecast` | Keep only events that publish a consensus forecast. | `false` |
| `newsWindowMinutes` | `inNewsWindow` is true for events within this many minutes of the run, before or after. | `30` |
| `onlyInNewsWindow` | Keep only events inside the news window ("is high-impact news due now?" with `impacts: ["High"]`). | `false` |
| `sortBy` | `time`, `impact` (High first), `currency`. | `time` |
| `maxItems` | Most rows for the run (0 = no limit). | `1000` |
| `monitorMode` | Deliver only new events and events that changed since the last run. | `false` |
| `monitorKey` | Name of the monitor's memory; use different names for separate watches. | `ff-calendar` |
| `resetMonitor` | Forget what earlier runs delivered. | `false` |
| `webhookUrl` | POST a JSON summary of the delivered events (up to 200) after the run writes them. Not called when nothing is delivered. | - |
| `proxyConfiguration` | Not needed. Used only if the direct request is refused (then Apify residential). | none |

Every filter runs before anything is charged. Field names from other Forex Factory actors are accepted too (`dateRange`, `startDate`, `endDate`, `impactLevels`, `minImpact`, `eventKeywords`, `upcomingOnly`, `onlyReleased`, `changesOnly`, `maxResults`, `max_items`).

### Output

One row per calendar event. A real row from a run on 2026-11-13 (`impacts: ["High","Medium"]`, `timezone: America/New_York`):

```json
{
  "eventId": "79-20261110",
  "calendar": "forexfactory",
  "calendarName": "Forex Factory",
  "title": "Core CPI m/m",
  "currency": "USD",
  "country": "United States",
  "countryCode": "US",
  "ffCountryCode": "us",
  "impact": "High",
  "impactLevel": 3,
  "category": "inflation",
  "dateTimeUtc": "2026-11-10T13:30:00.000Z",
  "timestamp": 1794317400,
  "date": "2026-11-10",
  "time": "08:30",
  "dayOfWeek": "Tuesday",
  "localDateTime": "2026-11-10T08:30:00-05:00",
  "timezone": "America/New_York",
  "utcOffset": "-05:00",
  "allDay": false,
  "forecast": "0.2%",
  "previous": "0.3%",
  "forecastValue": 0.2,
  "previousValue": 0.3,
  "unit": "%",
  "forecastVsPrevious": "lower",
  "forecastChange": -0.1,
  "hasForecast": true,
  "status": "passed",
  "minutesUntil": -4597,
  "inNewsWindow": false,
  "url": "https://www.forexfactory.com/calendar/79-us-core-cpi-mm",
  "seriesId": 79,
  "seriesSlug": "us-core-cpi-mm",
  "source": "https://nfs.faireconomy.media/ff_calendar_thisweek.csv",
  "scrapedAt": "2026-11-13T18:06:38.296Z"
}
```

| Field | Meaning |
|---|---|
| `eventId` | Forex Factory series id + UTC day. Stable across runs; the same event has the same id on all four calendars. |
| `calendar`, `calendarName` | Which calendar the row comes from. |
| `title` | Event title as Forex Factory shows it. |
| `currency` | The currency the event moves (`All` = global events such as G7 or OPEC meetings). |
| `country`, `countryCode`, `ffCountryCode` | Country of the release, from Forex Factory's own series code (`ge` = Germany for a EUR event). |
| `impact`, `impactLevel` | Expected impact (High 3, Medium 2, Low 1, Holiday 0) as rated by that calendar. |
| `category` | Event type, classified from the title. |
| `dateTimeUtc`, `timestamp` | Release time in UTC (ISO) and as Unix seconds. |
| `date`, `time`, `dayOfWeek`, `localDateTime`, `timezone`, `utcOffset` | Release time in your time zone. |
| `allDay` | True when the calendar gives a day but no time. |
| `forecast`, `previous` | As shown on the calendar. |
| `forecastValue`, `previousValue`, `unit` | The same as numbers (`19.2B` -> `19.2`, unit `B`). Bond auctions show "yield|bid-to-cover" and stay text. |
| `forecastVsPrevious`, `forecastChange` | `higher` / `lower` / `same`, and the difference. |
| `hasForecast` | A consensus forecast is published. |
| `status`, `minutesUntil`, `inNewsWindow` | Upcoming or passed at run time, minutes to the release, inside the news window. |
| `url`, `seriesId`, `seriesSlug` | The event's page on the calendar's site (history, specs, source). |
| `changeType`, `changedFields`, `previousValues`, `firstSeenAt` | Monitor mode only. |
| `source`, `scrapedAt` | The calendar file read and when. |

Released **actual** values and past or next weeks are not in this actor: Forex Factory shows them only on its calendar pages, which answer automated requests with a Cloudflare challenge.

#### Fields and how often they are filled

Measured on the Forex Factory week of 2026-11-08 to 2026-11-14 (105 events):

| Field | Filled |
|---|---|
| eventId, title, currency, country, impact, category, dateTimeUtc, date, time, url, seriesId, status, minutesUntil | 100% |
| countryCode, ffCountryCode | 98% (global events have none) |
| previous | 60% |
| previousValue | 55% (bond auctions show "yield|bid-to-cover", kept as text) |
| forecast, forecastValue, forecastVsPrevious | 46% (speeches, meetings and holidays have none) |

Impact in that week: 5 High, 6 Medium, 91 Low, 3 Holiday. Metals Mine had 69 events, Energy EXCH 44, Crypto Craft 15.

### Monitor mode

Turn on `monitorMode` and schedule the actor (hourly is plenty: Forex Factory updates the calendar file about once an hour). The first run delivers every matching event (`changeType: "new"`). Every later run delivers only:

- events not delivered before (`changeType: "new"`), and
- events whose time, impact, title, forecast or previous changed (`changeType: "changed"`, with `changedFields` and the old values in `previousValues`).

A run with nothing new delivers nothing and charges nothing. The memory is kept per `monitorKey` and calendar set; `resetMonitor: true` starts over. With `webhookUrl`, each run that delivers something POSTs a summary:

```json
{ "actor": "forexfactory-scraper", "runId": "...", "calendars": ["forexfactory"], "delivered": 2, "newEvents": 1, "changedEvents": 1, "datasetId": "...", "items": [{ "eventId": "78-20261110", "title": "CPI m/m", "currency": "USD", "impact": "High", "dateTimeUtc": "2026-11-10T13:30:00.000Z", "forecast": "0.3%", "previous": "0.6%", "changeType": "changed", "changedFields": ["forecast"], "url": "https://www.forexfactory.com/calendar/78-us-cpi-mm" }] }
```

### Pricing

**$0.36 per 1,000 events** ($0.00036 per delivered row). No start fee. Rows removed by a filter, rows over `maxItems` and unchanged rows in monitor mode are not charged. A full Forex Factory week (about 100 events) costs about $0.04.

### Speed and limits

- A run reads one small file per calendar (2-13 KB) and takes 1-2 seconds (measured on 120+ runs on 2026-11-13).
- The calendar covers the current week only (Sunday to Saturday, US Eastern), as Forex Factory publishes it.
- Forex Factory allows a few downloads of the calendar file per IP address in five minutes. If the direct download is refused, the run retries through Apify's proxies once per rung; if every rung is refused, the run fails without charging and says so.
- `category` is our classification from the title; it is not a Forex Factory field.

# Actor input Schema

## `calendars` (type: `array`):

Which calendars to read. Each rates impact for its own market: crude oil inventories are Low on Forex Factory and High on Energy EXCH. One row per event per calendar.

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

Which days of the current week, counted in the time zone below. "Upcoming" = events still ahead. "Custom" uses the dates below.

## `dateFrom` (type: `string`):

Custom period start (YYYY-MM-DD, in the chosen time zone), inside the current week.

## `dateTo` (type: `string`):

Custom period end (YYYY-MM-DD, inclusive). Empty = the From date only.

## `hoursAhead` (type: `integer`):

Only events releasing within this many hours from the run (e.g. 24 for a daily trading plan).

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

IANA time zone for date, time and localDateTime, e.g. America/New_York, Europe/London, Asia/Tokyo. dateTimeUtc is always UTC.

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

Only events with these impact levels. Empty = all.

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

Only events for these currencies. "All" = global events (G7, OPEC). Empty = all.

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

Only these event types (classified from the title). Empty = all.

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

Only events whose title (or currency / country) contains one of these words, e.g. CPI, Non-Farm, Powell. Case-insensitive.

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

Drop events whose title contains one of these words, e.g. Speaks, Auction.

## `eventStatus` (type: `string`):

Upcoming = release time still ahead at run time; passed = already released.

## `onlyWithForecast` (type: `boolean`):

Drop speeches, meetings and holidays: keep events that publish a consensus forecast.

## `newsWindowMinutes` (type: `integer`):

inNewsWindow is true for events within this many minutes of the run, before or after (the window trading bots pause around).

## `onlyInNewsWindow` (type: `boolean`):

Keep only events within the news window of the run (with Impact = High: "is high-impact news due now?").

## `sortBy` (type: `string`):

Row order.

## `maxItems` (type: `integer`):

Most rows for the whole run (0 = no limit). A full week is about 70-160 events on Forex Factory.

## `monitorMode` (type: `boolean`):

Each run delivers only events not delivered before and events whose time, impact, forecast or previous changed since (with changeType, changedFields, previousValues). A poll with nothing new charges nothing.

## `monitorKey` (type: `string`):

Name of the memory a monitor uses. Use different names for separate watches of the same calendars.

## `resetMonitor` (type: `boolean`):

Forget what earlier runs delivered: this run delivers every matching event again.

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

POST a JSON summary of the delivered events (up to 200) to this URL after the run writes them (Slack/Discord bridges, n8n, Make). Not called when nothing is delivered.

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

Not needed: the calendar is read directly. A proxy given here is used only when the direct request is refused (then Apify residential).

## Actor input object example

```json
{
  "calendars": [
    "forexfactory"
  ],
  "period": "thisWeek",
  "timezone": "UTC",
  "eventStatus": "all",
  "onlyWithForecast": false,
  "newsWindowMinutes": 30,
  "onlyInNewsWindow": false,
  "sortBy": "time",
  "maxItems": 1000,
  "monitorMode": false,
  "monitorKey": "ff-calendar",
  "resetMonitor": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (type: `string`):

One item per calendar event (per calendar when several are chosen).

# 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 = {
    "calendars": [
        "forexfactory"
    ],
    "timezone": "UTC",
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("topapi/forexfactory-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 = {
    "calendars": ["forexfactory"],
    "timezone": "UTC",
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("topapi/forexfactory-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 '{
  "calendars": [
    "forexfactory"
  ],
  "timezone": "UTC",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call topapi/forexfactory-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,topapi/forexfactory-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/ApmbgeY6fZsq8dMte/builds/K9dcTiUJWmCrfkwLN/openapi.json
