# Forex Economic Calendar: Market-Moving Events (`precious_bathmat/forex-economic-calendar`) Actor

Upcoming and released economic events by currency and impact, with the actual figure against the forecast so you can see which prints missed. Combines two public calendars: one has the impact ratings, the other has the actual numbers. No API key.

- **URL**: https://apify.com/precious\_bathmat/forex-economic-calendar.md
- **Developed by:** [Mariam Ahmed](https://apify.com/precious_bathmat) (community)
- **Categories:** Business, News
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$2.00 / 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 Economic Calendar: Market-Moving Events

Every economic release that moves a currency, **with the actual figure against the forecast** so you can see which prints missed and by how much.

No API key, no login, no proxy.

### What does this do?

An economic calendar is only half the story. Knowing that US inflation is out at 12:30 is useful; knowing it came in at **0.6% against a forecast of -0.2%** is the part that actually moved the pound.

The problem is that no single free calendar gives you both. One has the **impact ratings** traders filter on but never publishes the actual number. The other has **actual figures for any date** but no impact rating and lists events by country rather than currency. This Actor reads both and joins them.

```mermaid
flowchart LR
    A[ForexFactory feed<br/>impact · currency · forecast] --> C[One calendar]
    B[Nasdaq calendar<br/>actual · consensus · description] --> C
    C --> D[Above or below forecast,<br/>and by how much]
```

### Who is it for?

| You are | You use it to |
|---|---|
| **A forex trader** | See what is due today for your pairs, filtered to the releases that matter |
| **Running a trading bot** | Feed a schedule of high-impact events, and avoid holding through them |
| **An analyst** | Review which prints surprised last week and by how much |
| **Building a finance app** | Get a clean calendar feed without paying for a data licence |

### What data do you get?

| Field | What it is |
|---|---|
| `at`, `hoursUntil`, `status` | When it lands in UTC, how long away, and whether it has been released |
| `currency`, `country` | The currency it moves, and the country that published it |
| `title`, `description` | The release, and what the indicator measures |
| `impact`, `impactKnown` | High, Medium, Low or Holiday — and whether it was rated at all |
| `actual`, `forecast`, `previous` | The three figures |
| `versusForecast` | Above forecast, below forecast, or in line |
| `surpriseFormatted`, `surpriseAbsolute`, `surprisePercent` | How far it missed, in the same units as the figures |
| `whySurprise` | The comparison in a sentence you can paste into a note |
| `sources`, `matchedAcrossSources` | Which feeds the row came from |

### Example: one week, September 2026

A run covering five days back and seven forward returned **250 events, 175 with an actual figure and 54 that missed their forecast**, in 38 seconds.

| Currency | Release | Result |
|---|---|---|
| **GBP** | Core Retail Sales | **0.6% against a forecast of -0.2%** — beat by 0.8 percentage points |
| **CAD** | Building Permits | **-17.3% against -4.7%** — missed by 12.6 percentage points |
| USD | Retail Control | 1.4% against 0.4% |
| USD | Manufacturing Production | -0.3% against 0.3% |
| CHF | SNB Policy Rate | Upcoming, forecast 0.00%, previous 0.00% |

Two UK retail sales prints beating a negative forecast by nearly a point is the kind of thing that shows up in the pound before it shows up in the commentary.

### What it refuses to do

- **It does not tell you whether a number is good or bad.** A figure above forecast is excellent news for GDP and poor news for unemployment. The direction is reported against the forecast and nothing more, because a tool that guessed would be confidently wrong about half the time.
- **It does not invent an impact rating.** Impact comes from one feed which covers **the current week only**. Events outside that week are reported as unrated rather than quietly labelled Low. `impactKnown` tells you which is which.
- **If you ask for High impact and no ratings are available**, it returns everything and says so on every row instead of handing you an empty list you could not explain. That failure mode was found in testing and fixed.
- **It will not attach an actual figure to the wrong event.** Matching across the two feeds requires the same currency, a strong name overlap and a release time within a day and a half. A loose match would silently pin one country's inflation print onto another's, which is far worse than an empty cell.
- **It reports the miss in the units you are reading.** An early version said a stocks figure missed by "1485000" while displaying the values as "1.585M". It now says "+1.485M".

### A limit worth knowing

Both feeds rate-limit. In testing, repeated runs from one address had the ForexFactory feed return HTTP 429 for several minutes. A single run is comfortably inside that; firing several back to back is not. If the impact feed is refused, the Actor carries on with the other source and marks every row so you know the ratings are missing rather than absent.

### Popular economic calendars

Ready-made runs you can open and start, or copy as a starting point:

- [Forex Economic Calendar This Week](https://apify.com/precious_bathmat/forex-economic-calendar/examples/forex-economic-calendar-this-week)
- [High Impact Economic Events](https://apify.com/precious_bathmat/forex-economic-calendar/examples/high-impact-economic-events)
- [US Economic Calendar](https://apify.com/precious_bathmat/forex-economic-calendar/examples/us-economic-calendar)
- [Euro Area Economic Calendar](https://apify.com/precious_bathmat/forex-economic-calendar/examples/euro-area-economic-calendar)
- [UK Economic Calendar](https://apify.com/precious_bathmat/forex-economic-calendar/examples/uk-economic-calendar)
- [Japan Economic Calendar](https://apify.com/precious_bathmat/forex-economic-calendar/examples/japan-economic-calendar)
- [Canada Economic Calendar](https://apify.com/precious_bathmat/forex-economic-calendar/examples/canada-economic-calendar)
- [Australia Economic Calendar](https://apify.com/precious_bathmat/forex-economic-calendar/examples/australia-economic-calendar)
- [New Zealand Economic Calendar](https://apify.com/precious_bathmat/forex-economic-calendar/examples/new-zealand-economic-calendar)
- [Switzerland Economic Calendar](https://apify.com/precious_bathmat/forex-economic-calendar/examples/switzerland-economic-calendar)
- [EUR/USD Economic Calendar](https://apify.com/precious_bathmat/forex-economic-calendar/examples/eur-usd-economic-calendar)
- [GBP/USD Economic Calendar](https://apify.com/precious_bathmat/forex-economic-calendar/examples/gbp-usd-economic-calendar)
- [USD/JPY Economic Calendar](https://apify.com/precious_bathmat/forex-economic-calendar/examples/usd-jpy-economic-calendar)
- [Emerging Market Economic Calendar](https://apify.com/precious_bathmat/forex-economic-calendar/examples/emerging-market-economic-calendar)
- [Asia Pacific Economic Calendar](https://apify.com/precious_bathmat/forex-economic-calendar/examples/asia-pacific-economic-calendar)
- [Economic Data Surprises](https://apify.com/precious_bathmat/forex-economic-calendar/examples/economic-data-surprises)

### Pricing

**$0.002 per event returned.** A typical week of majors at medium impact and above is about 250 events, so roughly **$0.50 a run**. Narrow it to High impact on two currencies and the same run costs a few cents.

### Input

| Setting | What it does |
|---|---|
| **Currencies** | The eight majors by default. German and French data both count towards the euro |
| **Minimum impact** | High is the releases that typically move a currency; Medium and above is the usual working filter |
| **Days of history** | How far back to include released figures and their misses |
| **Days ahead** | How far forward to include scheduled events |
| **Only events that have been released** | For reviewing what surprised rather than planning ahead |
| **Include what each indicator measures** | Adds a plain-English description where one exists |
| **Maximum events** | Caps the run, earliest first |

### Integrations

Runs on a schedule and connects to Google Sheets, Slack, Zapier, Make or your own code through the Apify API. A run every morning gives you the day's releases for your pairs; a run every evening gives you what missed.

# Actor input Schema

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

Which currencies to follow. Events are matched to a currency, so German and French data both count towards the euro.

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

High impact means the releases that typically move a currency, such as interest rate decisions, inflation and employment. Impact ratings cover the current week; events outside it are kept unless you ask for High only.

## `daysBack` (type: `integer`):

How many days back to include. Past events carry the actual figure and how far it missed the forecast.

## `daysAhead` (type: `integer`):

How many days forward to include. Upcoming events carry the forecast and the previous reading.

## `onlyWithActual` (type: `boolean`):

Keep only events whose actual figure has been published. Useful for reviewing what surprised rather than planning ahead.

## `includeDescriptions` (type: `boolean`):

Adds a plain-English description of the indicator where one is available.

## `maxEvents` (type: `integer`):

How many events to return. Each costs $0.002.

## Actor input object example

```json
{
  "currencies": [
    "USD",
    "EUR",
    "GBP",
    "JPY",
    "AUD",
    "CAD",
    "CHF",
    "NZD"
  ],
  "minImpact": "Medium",
  "daysBack": 3,
  "daysAhead": 7,
  "onlyWithActual": false,
  "includeDescriptions": true,
  "maxEvents": 200
}
```

# Actor output Schema

## `events` (type: `string`):

Every event in the window, earliest first.

## `summary` (type: `string`):

What each feed returned and what matched.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("precious_bathmat/forex-economic-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("precious_bathmat/forex-economic-calendar").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 '{}' |
apify call precious_bathmat/forex-economic-calendar --silent --output-dataset

```

## MCP server setup

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

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/5hKQkswkElR7GneQr/builds/KglSyORzEAVpRUl2h/openapi.json