# Economic Calendar Scraper — Actual, Forecast & Previous (`yugenox/economic-calendar-scraper`) Actor

Economic calendar for 140+ countries: every macro release (CPI, jobs, GDP, PMI, rates) with time in UTC, country, currency, period, importance, actual, consensus, forecast, previous, revisions, unit and surprise. Date presets or custom dates, only-changes monitor. No login.

- **URL**: https://apify.com/yugenox/economic-calendar-scraper.md
- **Developed by:** [Yugenox Corp](https://apify.com/yugenox) (community)
- **Categories:** Business, News
- **Security:** Limited permissions
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 economic 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

## Economic Calendar Scraper: Actual, Consensus, Forecast & Previous

Scrape the **economic calendar** of **140+ countries** into clean rows. You get every macro release, including CPI, inflation, non-farm payrolls, unemployment, GDP, PMIs, retail sales, central-bank rate decisions, bond auctions, holidays and elections. Each row has the **release time in UTC**, country, currency, reference period, **importance (1–3)**, **actual, consensus, forecast and previous** values (as shown and as numbers), the **revised previous value**, the unit and the **surprise** (actual minus consensus). Pick a date preset or your own dates, filter by country, currency, region, importance and keywords, and schedule it with **Only new or updated events** to catch each release as it comes out. No login, no API key.

### What you get

| | |
|---|---|
| **When** | Release date and time in UTC (`2026-10-27T12:30:00Z`), all-day flag for holidays and tentative releases |
| **Where** | Country, ISO code (US, EA, GB, JP …), currency (USD, EUR, GBP, JPY …) |
| **What** | Event name ("Durable Goods Orders MoM"), indicator category, reference period ("SEP", "Q3", "OCT/24"), ticker, link to the indicator page |
| **Importance** | 1 (low), 2 (medium) or 3 (high, market-moving) |
| **Values** | Actual, consensus, forecast and previous as published ("1.8%", "$-52.8B", "194K") **and** as numbers, unit and currency sign, the previous value before its revision |
| **Surprise** | Actual minus consensus, when both are known in the same unit |
| **Status** | Released (has an actual value) or upcoming; in monitor mode, `new` or `updated` plus which fields changed |

### How to use it

1. Enter **Countries**: ISO codes (`US`, `EU`, `GB`, `JP`, `CA`, `DE`, `CN`), names (`United States`, `Euro Area`), currencies (`USD`, `EUR`; `EUR` is the euro area plus every euro country) or regions (`G20`, `G7`, `Europe`, `Asia`, `America`, `Africa`). Leave it empty for every country.
2. Pick **Dates**: today, tomorrow, yesterday, this week, next week, last 7 days, this month, next month or last 30 days. Or fill in **From** / **Until** (e.g. `2026-11-02`, or `-7 days`, `+14 days`).
3. Optionally set **Minimum importance**, **Event keywords** (`CPI`, `non farm payrolls`, `interest rate decision`, `PMI`), **Released / upcoming** and **Include holidays**.
4. Set **Max events** and run.

The calendar covers the **last 30 days through the end of next month**. Days outside that window are skipped, and the status message says so.

#### Input examples

This week's US events (the example input):

```json
{
  "countries": ["US"],
  "dateRange": "thisWeek",
  "maxItems": 20
}
```

Next week's high-importance releases for the major currencies:

```json
{
  "countries": ["USD", "EUR", "GBP", "JPY", "CAD", "AUD", "CHF", "NZD"],
  "dateRange": "nextWeek",
  "minImportance": "high",
  "includeHolidays": false,
  "maxItems": 0
}
```

Every inflation and jobs release in the G20 over custom dates:

```json
{
  "countries": ["G20"],
  "dateFrom": "2026-11-01",
  "dateTo": "2026-11-30",
  "keywords": ["inflation rate", "CPI", "non farm payrolls", "unemployment rate"],
  "maxItems": 0
}
```

A release monitor: schedule this every 5–15 minutes and each run saves only the events that were just released or changed:

```json
{
  "countries": ["US", "EU", "GB"],
  "dateRange": "today",
  "minImportance": "medium",
  "onlyChanges": true,
  "maxItems": 0
}
```

### Output example

```json
{
  "eventId": "398125",
  "date": "2026-10-27",
  "time": "12:30",
  "datetimeUtc": "2026-10-27T12:30:00Z",
  "allDay": false,
  "country": "United States",
  "countryCode": "US",
  "currency": "USD",
  "event": "Durable Goods Orders MoM",
  "category": "durable goods orders",
  "period": "SEP",
  "importance": 3,
  "importanceLabel": "high",
  "actual": "1.8%",
  "consensus": "1.5%",
  "forecast": "1.3%",
  "previous": "0.1%",
  "previousRevisedFrom": "0%",
  "actualValue": 1.8,
  "consensusValue": 1.5,
  "forecastValue": 1.3,
  "previousValue": 0.1,
  "unit": "%",
  "valuePrefix": null,
  "surprise": 0.3,
  "released": true,
  "ticker": "UNITEDSTADURGOOORD",
  "url": "https://tradingeconomics.com/united-states/durable-goods-orders",
  "source": "Trading Economics",
  "changeType": null,
  "changedFields": [],
  "scrapedAt": "2026-10-29T18:53:13.069Z"
}
```

Every row has the same columns. A value the calendar doesn't show is `null`. For example, `actual` stays `null` until the release.

### Pricing

Pay per event: **$1.50 per 1,000 events** saved, plus **$0.002 per run**. Wide searches cost a little extra. The calendar shows at most 1,000 events per page, so a range with more events than that (every country over a whole month), or custom dates that span two of the calendar's ranges, needs more pages. Each page after the first costs **$0.001**. A typical run reads one page and never pays that. Events skipped by your filters or by **Only new or updated events** are never charged.

Examples: this week's US calendar (about 90 events) ≈ $0.13. Every country for a week (about 570 events) ≈ $0.86. A 5-minute monitor that finds nothing new costs $0.002 per run.

### Use cases

- **FX and macro trading**: the week ahead with consensus and forecast, and the surprise the moment a number is released.
- **Trading bots and alerts**: a scheduled monitor run that saves only new and updated events, ready for a webhook, Slack or Telegram.
- **Newsletters and dashboards**: next week's market-moving releases by country, ready to paste into a newsletter or load into a dashboard.
- **Research**: actual versus consensus surprises across countries for the last 30 days.

### Tips

- Use **Minimum importance: High only** for the releases that move markets (CPI, payrolls, rate decisions, GDP).
- **Only new or updated events** remembers what earlier runs with the *same input* saved. An event is saved again (with `changeType: "updated"` and `changedFields`) when its actual, consensus, forecast, previous value or time changes.
- Times are always UTC. Convert with `datetimeUtc` in your own tool.
- `surprise` is only filled when actual and consensus use the same unit.

### FAQ

**Do I need an account, an API key or a login?** No. The scraper reads the same public calendar any visitor sees.

**How far back and ahead does it go?** From 30 days ago to the end of next month, which is what the calendar shows without an account. Older history is not available here.

**How quickly does a new number show up?** As soon as the calendar publishes it. For a release monitor, schedule a run every few minutes with **Only new or updated events**. Each run costs $0.002 plus the events it saves.

**Why did a run say some events may be missing?** The calendar sometimes answers with a different selection of countries. The scraper checks every answer and asks again. If the calendar keeps sending the wrong selection, the run keeps only the matching events and says so in its status message; if it happens on two pages of one run, the run stops early rather than spend your time on more of them. Running it again a few minutes later usually completes them.

**Which proxy should I use?** Keep the default (Apify Proxy, datacenter). It comes with every Apify plan, including the free one.

**Is it legal to scrape Trading Economics?** This Actor only collects publicly available data: the economic calendar that anyone can see on Trading Economics without an account (release times, countries, indicator names and the published values). It contains no personal data. Collecting publicly available data is generally legal, but you're responsible for how you use it and for following Trading Economics' terms. If you're unsure, check with a lawyer. More on this: [Is web scraping legal?](https://blog.apify.com/is-web-scraping-legal/)

**Does it access any private data?** No. Everything comes from the public calendar page that is shown without logging in. The scraper never touches accounts, never uses paid data feeds and follows the site's robots.txt.

*This Actor is not affiliated with, endorsed by or sponsored by Trading Economics.*

# Actor input Schema

## `countries` (type: `array`):

Countries to include: ISO codes (US, EU, GB, JP, CA, DE, CN, AU …), country names ("United States", "Euro Area"), currencies (USD, EUR, GBP, JPY — EUR = the Euro Area and every euro country) or regions (G20, G7, Europe, Asia, America, Africa). Leave empty for all 140+ countries.

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

Which days to get. Weeks run Sunday to Sunday. Times are in UTC. Ignored when you fill in From / Until below.

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

Optional custom start date, e.g. 2026-11-02, or relative like "today" or "-7 days". The calendar shows the last 30 days through the end of next month; days outside that are skipped (and named in the status message).

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

Optional custom end date (inclusive), e.g. 2026-11-13, or relative like "+14 days". Empty = 7 days from From.

## `minImportance` (type: `string`):

Low = every event; Medium = 2- and 3-star events; High = only the market-moving 3-star releases (CPI, payrolls, rate decisions, GDP …).

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

Optional: only events whose name or category contains one of these, e.g. "CPI", "inflation rate", "non farm payrolls", "interest rate decision", "PMI", "GDP". Every word of a keyword must appear; case is ignored.

## `releaseStatus` (type: `string`):

All events, only events already released (with an actual value), or only upcoming events (no actual yet).

## `includeHolidays` (type: `boolean`):

Keep all-day calendar entries such as bank holidays, market closures and elections (they have no values).

## `onlyChanges` (type: `boolean`):

Monitor mode for schedules: save an event only if an earlier run with the same input did not save it yet, or if its actual, consensus, forecast, previous value or time changed since (see changeType / changedFields). Unchanged events are skipped and not charged.

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

Maximum number of events to save in this run. 0 = no limit (up to 20,000).

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

Apify Proxy (datacenter) is the default and comes with every Apify plan. You can also paste your own proxy URLs.

## Actor input object example

```json
{
  "countries": [
    "US"
  ],
  "dateRange": "thisWeek",
  "minImportance": "low",
  "releaseStatus": "all",
  "includeHolidays": true,
  "onlyChanges": false,
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

All scraped economic calendar events.

## `run` (type: `string`):

Status and statistics for this run.

## `report` (type: `string`):

RUN_REPORT: how the run ended, the date range read, counts, requests and proxy use.

# 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 = {
    "countries": [
        "US"
    ],
    "dateRange": "thisWeek",
    "maxItems": 20,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("yugenox/economic-calendar-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 = {
    "countries": ["US"],
    "dateRange": "thisWeek",
    "maxItems": 20,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("yugenox/economic-calendar-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 '{
  "countries": [
    "US"
  ],
  "dateRange": "thisWeek",
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call yugenox/economic-calendar-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,yugenox/economic-calendar-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/WeGb2ulJ70GRXprc4/builds/xFAdaFXEg2Hrh0YTG/openapi.json