# ForexFactory Economic Calendar Scraper (`xtracto/forexfactory-calendar`) Actor

Scrape the ForexFactory economic calendar with released actual values alongside forecast and previous readings, plus revision, impact level and currency. Choose this/next/last week, a month, a day or any date range. Clean JSON, no account or API key.

- **URL**: https://apify.com/xtracto/forexfactory-calendar.md
- **Developed by:** [Farhan Febrian Nauval](https://apify.com/xtracto) (community)
- **Categories:** Lead generation, Integrations, Developer tools
- **Stats:** 12 total users, 2 monthly users, 95.2% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.99 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## ForexFactory Economic Calendar Scraper

Scrape the **ForexFactory economic calendar** as clean JSON — every scheduled event with its **actual** released value alongside the **forecast** and **previous** readings, plus revisions, impact level, currency, and event time. Pick this week, next/last week, a month, a single day, or any custom date range.

### Why use this actor

- **No account, no login, no API key** — just press Run.
- **Actual vs forecast vs previous** on every data release — the numbers traders and analysts actually watch, not just the schedule.
- **Revision, impact level, and "better/worse than expected"** signals included, so you can rank surprises at a glance.
- **Any date window** — this/next/last week, the current month, a single day, or a custom `From`–`To` range (long ranges are fetched and merged automatically).
- **Filter by currency and minimum impact** (e.g. only high-impact USD & EUR events).
- **Stable JSON output** ready for spreadsheets, databases, dashboards, or trading pipelines. Automatic retries; runs on Apify's schedule.

### How it works

1. Choose a **date range** (or a specific day / custom span).
2. Optionally narrow to specific **currencies** and a **minimum impact** level, or keep only **upcoming** events.
3. The actor pulls the calendar for that window and returns one clean row per event.
4. Export to JSON, CSV, or Excel, or pull it straight from the dataset via the API.

You don't manage any scrapers, browsers, or blocks — just the inputs.

### Input

```json
{
  "dateRange": "lastWeek",
  "currencies": ["USD", "CAD"],
  "minImpact": "medium",
  "upcomingOnly": false,
  "maxItems": 500
}
```

| Field | Type | Description |
| --- | --- | --- |
| `dateRange` | string | `thisWeek`, `nextWeek`, `lastWeek`, `thisMonth`, `day`, or `range`. |
| `day` | string | Used when `dateRange = day`. A single date, `YYYY-MM-DD` (e.g. `2026-07-06`). |
| `rangeFrom` | string | Used when `dateRange = range`. Start date, `YYYY-MM-DD`. |
| `rangeTo` | string | Used when `dateRange = range`. End date, `YYYY-MM-DD`. Long spans are split and merged automatically. |
| `currencies` | array | Keep only these currencies (`USD`, `EUR`, `GBP`, `JPY`, `AUD`, `CAD`, `CHF`, `NZD`, `CNY`). Empty = all. |
| `minImpact` | string | `low` (all, incl. holidays), `medium` (medium + high), or `high` (high only). |
| `upcomingOnly` | boolean | Keep only events scheduled from now onward. |
| `maxItems` | integer | Max events to return (0 = no cap). |
| `proxyConfiguration` | object | Optional. Not required — ForexFactory is a public source. |

### Output

One row per event. Real sample (a released US-session data event from `lastWeek`):

```json
{
  "_input": "lastWeek",
  "_source": "S1-onsite",
  "_scrapedAt": "2026-07-10T20:21:57Z",
  "id": 149224,
  "title": "GDP m/m",
  "prefixedName": "CA GDP m/m",
  "currency": "CAD",
  "country": "CA",
  "dateline": 1782822600,
  "datetimeISO": "2026-06-30T12:30:00Z",
  "timeLabel": "7:30pm",
  "impact": "high",
  "impactTitle": "High Impact Expected",
  "actual": "0.5%",
  "forecast": "0.4%",
  "previous": "-0.1%",
  "revision": "",
  "actualBetterWorse": 1,
  "revisionBetterWorse": 0,
  "leaked": false,
  "soloUrl": "/calendar/29-ca-gdp-mm",
  "url": "/calendar?day=jun30.2026#detail=149224"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `_input` | string | The date range you requested. |
| `_source` | string | Where the row came from (`S1-onsite` = live calendar with actuals). |
| `_scrapedAt` | string | When the row was captured (UTC). |
| `id` | number | Stable event ID (used to de-duplicate across a long range). |
| `title` | string | Event name (e.g. `GDP m/m`, `Core CPI m/m`). |
| `prefixedName` | string | Event name prefixed with its currency/region. |
| `currency` | string | Currency the event affects. |
| `country` | string | Country/region code. |
| `dateline` | number | Event time as a Unix timestamp. |
| `datetimeISO` | string | Event time as UTC ISO 8601. |
| `timeLabel` | string | Human-readable event time as shown on the calendar. |
| `impact` | string | Expected impact: `high`, `medium`, `low`, or `holiday`. |
| `impactTitle` | string | Full impact label. |
| `actual` | string / null | The released value. `null` for events that haven't been released yet (all future events) and for speeches/holidays with no reading. |
| `forecast` | string | Consensus forecast (may be empty). |
| `previous` | string | Prior period's value (may be empty). |
| `revision` | string | Revised prior value, if any. |
| `actualBetterWorse` | number | `1` = better than forecast, `-1` = worse, `0` = in line / n/a. |
| `revisionBetterWorse` | number | Same scale, applied to the revision. |
| `leaked` | boolean | Whether the figure was released early. |
| `soloUrl` | string | Path to the event's dedicated page. |
| `url` | string | Path to the event on the calendar. |

### Notes / limits

- **Actual values are populated at release time.** Past events carry a filled `actual`; future events return `actual: null` by design (the forecast and previous are still provided). Speeches, meetings, and holidays have no numeric `actual`.
- **Custom ranges** longer than about two months are fetched in several windows and merged, with duplicate events removed automatically.
- A proxy is **not required**. If your own network can't reach the source, enable Residential proxy in the input.

### Other finance actors

| Actor | What it does |
| --- | --- |
| TradingView Screener, Ideas & Quotes | Screen stocks/crypto/forex, community ideas, live quotes. |
| CoinMarketCap Listings & Airdrops | Crypto market data, new coins, airdrops, per-coin detail. |
| TipRanks Stock Signals | Analyst ratings and price-target signals per ticker. |

# Actor input Schema

## `dateRange` (type: `string`):

Which calendar window to pull. Use 'This week' / 'Next week' / 'Last week' for quick runs, 'This month' for the current month, 'Specific day' with the Day field, or 'Custom range' with the From/To fields (spans over ~60 days are split automatically).

## `day` (type: `string`):

Used when Date range = 'Specific day'. A single date in YYYY-MM-DD format, e.g. 2026-07-06.

## `rangeFrom` (type: `string`):

Used when Date range = 'Custom range'. Start date in YYYY-MM-DD format, e.g. 2026-07-01.

## `rangeTo` (type: `string`):

Used when Date range = 'Custom range'. End date in YYYY-MM-DD format, e.g. 2026-08-31. Spans longer than ~60 days are fetched in several windows and merged.

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

Keep only events for these currencies. Leave empty for all currencies.

## `minImpact` (type: `string`):

Keep only events at or above this expected impact. 'Low (all)' returns everything including holidays; 'Medium' returns medium + high; 'High' returns high-impact events only.

## `upcomingOnly` (type: `boolean`):

When enabled, keep only events scheduled from now onward (skip events that have already passed in the window).

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

Maximum number of events to push to the dataset (0 = no cap). Applied across the whole run.

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

Residential proxy is recommended so the actor reads live released values (actual vs forecast) directly from the source. Without it, results fall back to a forecast-only feed with no 'actual' figures.

## Actor input object example

```json
{
  "dateRange": "thisWeek",
  "day": "2026-07-06",
  "rangeFrom": "2026-07-01",
  "rangeTo": "2026-08-31",
  "currencies": [],
  "minImpact": "low",
  "upcomingOnly": false,
  "maxItems": 500,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# 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 = {
    "dateRange": "thisWeek",
    "day": "2026-07-06",
    "rangeFrom": "2026-07-01",
    "rangeTo": "2026-08-31",
    "currencies": [],
    "minImpact": "low",
    "maxItems": 500
};

// Run the Actor and wait for it to finish
const run = await client.actor("xtracto/forexfactory-calendar").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 = {
    "dateRange": "thisWeek",
    "day": "2026-07-06",
    "rangeFrom": "2026-07-01",
    "rangeTo": "2026-08-31",
    "currencies": [],
    "minImpact": "low",
    "maxItems": 500,
}

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

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

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

```

## CLI example

```bash
echo '{
  "dateRange": "thisWeek",
  "day": "2026-07-06",
  "rangeFrom": "2026-07-01",
  "rangeTo": "2026-08-31",
  "currencies": [],
  "minImpact": "low",
  "maxItems": 500
}' |
apify call xtracto/forexfactory-calendar --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=xtracto/forexfactory-calendar",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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