# Economic Calendar Pro (ForexFactory) (`ichigowa/economic-calendar-pro`) Actor

Fetch and normalize the ForexFactory economic calendar (FOMC, CPI, NFP...) as clean JSON with currency/impact/keyword filters, change-detection alerts and webhook delivery. Unofficial, not affiliated with ForexFactory.

- **URL**: https://apify.com/ichigowa/economic-calendar-pro.md
- **Developed by:** [kyle herman](https://apify.com/ichigowa) (community)
- **Categories:** Business, Automation
- **Stats:** 3 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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/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

## Economic Calendar API — ForexFactory Calendar as Clean JSON (FOMC, CPI, NFP)

**Economic Calendar Pro** is an economic calendar API that turns the free **ForexFactory calendar** feed into clean, normalized JSON you can pipe into trading bots, dashboards, n8n/Make automations, or cron jobs. It covers every scheduled macro release — **FOMC statements, CPI, Non-Farm Payrolls (NFP), rate decisions, PMI, GDP** and more — for USD, EUR, GBP, JPY, CAD, AUD, NZD, CHF, CNY and other major currencies.

> ⚠️ **Unofficial.** This Actor is not affiliated with, endorsed by, or sponsored by ForexFactory or Fair Economy, Inc. It consumes their publicly available calendar feed.

### What it does

- Fetches the ForexFactory economic calendar for **this week, next week, and/or last week**.
- **Normalizes** every event: stable `event_id`, ISO 8601 **UTC** timestamps, consistent field names.
- **Filters** by currency (`USD`, `EUR`, …), impact (`High` / `Medium` / `Low` / `Holiday`), and event-name keyword (`CPI`, `FOMC`, `Non-Farm`…).
- **Change detection**: run it on a schedule with `changesOnly: true` and get only *new* events or events whose forecast/previous/actual/time changed — perfect for alerts.
- **Webhook delivery**: optionally POSTs changed events to your endpoint as JSON.

### Output schema

Each dataset row:

| Field | Type | Description |
|---|---|---|
| `source` | string | Always `forexfactory` |
| `event_id` | string | Stable 16-char hash of title + currency + scheduled time |
| `title` | string | Event name, e.g. `CPI m/m`, `Non-Farm Employment Change`, `FOMC Statement` |
| `country` / `currency` | string | Currency code the event affects, e.g. `USD` |
| `date_utc` | string | Scheduled time as ISO 8601 UTC, e.g. `2026-07-22T12:30:00Z` |
| `impact` | string | `High`, `Medium`, `Low`, or `Holiday` |
| `forecast` | string | Consensus forecast, e.g. `2.1%` (may be empty) |
| `previous` | string | Previous reading (may be empty) |
| `actual` | string | Released value (the free feed does not publish it; kept for schema stability) |
| `url` | string | Deep link to the ForexFactory calendar day page |
| `week` | string | Which fetch window the event came from: `this` / `next` / `last` |

In changes-only mode rows additionally carry:

| Field | Type | Description |
|---|---|---|
| `change_type` | string | `new` or `updated` |
| `changed_fields` | array | Which watched fields changed, e.g. `["forecast"]` |
| `old_<field>` | string | Previous value for each changed field |

### Input examples

**Default (empty input `{}`):** this week + next week, all currencies, all impacts.

**High-impact USD events only:**

```json
{
  "currencies": ["USD"],
  "impacts": ["High"]
}
```

**CPI releases across all majors, next week included:**

```json
{
  "weeks": ["this", "next"],
  "keyword": "CPI"
}
```

**Scheduled change alerts with webhook (run hourly):**

```json
{
  "currencies": ["USD", "EUR"],
  "impacts": ["High"],
  "changesOnly": true,
  "webhookUrl": "https://hooks.example.com/econ-calendar"
}
```

### Use cases

- **n8n / Make.com pipelines** — trigger workflows when a high-impact event is added or a forecast is revised; the webhook payload plugs straight into an HTTP trigger node.
- **Trading bots** — pause strategies around FOMC/NFP windows using `date_utc` (already UTC, no timezone math).
- **Cron + API** — schedule the Actor on Apify and read the dataset via the Apify API as your own **forexfactory calendar API** endpoint (JSON/CSV/Excel export built in).
- **Dashboards & research** — join `event_id` across runs to track forecast revisions over time.

### Change detection details

The Actor keeps a snapshot of every event (keyed by `event_id`) in the named key-value store **`economic-calendar-state`**. On each run it diffs the fresh calendar against the snapshot. With `changesOnly: true`, only new/updated events are pushed to the dataset; with the default `false`, the full filtered calendar is pushed and the snapshot is still updated, so you can warm up the state before enabling alerts.

### Pricing

Pay-per-event: you are charged a small fee per calendar row delivered (`event-fetched`) and per change alert (`change-alert`) — no subscriptions, no minimums. Exact prices are shown on the Actor's Apify Store page.

### FAQ

**Is this a free economic calendar API?** The data source is the free public ForexFactory feed; running the Actor is billed per event delivered (see Pricing).

**What timezone are the dates in?** Everything is normalized to UTC ISO 8601 (`...Z`). The upstream feed publishes US/Eastern offsets; conversion is handled for you.

**Does it include actual/released values?** The free JSON feed only carries `forecast` and `previous`. The `actual` field is present in the schema but empty; time/forecast/previous revisions are still detected.

**Why is next week's calendar sometimes empty?** The upstream CDN occasionally hasn't published the `nextweek` file yet (HTTP 404). The Actor logs a warning and continues with the available weeks.

**How often should I schedule it?** Hourly is plenty for forecast-revision alerts; every 5–15 minutes if you want to catch late schedule changes before big releases.

**Is `event_id` stable?** Yes — it is a hash of title + currency + the feed's scheduled time, so it is identical across runs until the event itself is rescheduled (which is then reported as a change).

# Actor input Schema

## `weeks` (type: `array`):

Which calendar weeks to download. Options: `this` (current week), `next` (upcoming week), `last` (previous week). Note: the upstream feed occasionally has no `next`/`last` file published yet; those weeks are then skipped with a warning.

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

Only output events for these currency codes (e.g. `USD`, `EUR`, `GBP`, `JPY`, `CAD`, `AUD`, `NZD`, `CHF`, `CNY`). Leave empty for all currencies.

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

Only output events with these impact levels. Leave empty for all levels (including `Holiday`).

## `keyword` (type: `string`):

Case-insensitive substring match on the event title, e.g. `CPI`, `Non-Farm`, `FOMC`, `Rate`. Leave empty to disable.

## `changesOnly` (type: `boolean`):

When enabled, the Actor compares the calendar against the snapshot saved by the previous run (in the named key-value store `economic-calendar-state`) and outputs only new events or events whose forecast/previous/actual/time/impact changed, annotated with `change_type` and `changed_fields`. Ideal for scheduled alert pipelines.

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

Optional HTTPS endpoint. When set and changes are detected, the changed rows are POSTed there as JSON (`{source, count, events}`). Webhook failures are logged but never fail the run.

## Actor input object example

```json
{
  "weeks": [
    "this",
    "next"
  ],
  "currencies": [
    "USD",
    "EUR"
  ],
  "impacts": [],
  "keyword": "CPI",
  "changesOnly": false,
  "webhookUrl": "https://hooks.example.com/economic-calendar"
}
```

# Actor output Schema

## `results` (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 = {
    "weeks": [
        "this",
        "next"
    ],
    "currencies": [],
    "impacts": [],
    "keyword": "",
    "changesOnly": false,
    "webhookUrl": ""
};

// Run the Actor and wait for it to finish
const run = await client.actor("ichigowa/economic-calendar-pro").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 = {
    "weeks": [
        "this",
        "next",
    ],
    "currencies": [],
    "impacts": [],
    "keyword": "",
    "changesOnly": False,
    "webhookUrl": "",
}

# Run the Actor and wait for it to finish
run = client.actor("ichigowa/economic-calendar-pro").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 '{
  "weeks": [
    "this",
    "next"
  ],
  "currencies": [],
  "impacts": [],
  "keyword": "",
  "changesOnly": false,
  "webhookUrl": ""
}' |
apify call ichigowa/economic-calendar-pro --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

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