# The Economic Calendar (`aldines/economic-calendar`) Actor

The economic calendar to explore key global events on the horizon that could subtly shift or substantially shake up the financial markets.

- **URL**: https://apify.com/aldines/economic-calendar.md
- **Developed by:** [Aldines](https://apify.com/aldines) (community)
- **Categories:** Other
- **Stats:** 84 total users, 1 monthly users, 100.0% runs succeeded, 2 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 results

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?

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 Scraper

Pull scheduled macroeconomic events (CPI, interest rate decisions, jobless claims, PMIs, bond auctions, central bank speeches and more) for 47 countries and regions, as clean structured JSON.

Every event comes with its actual, forecast and previous values as real numbers, the unit and scale they are in, the surprise versus forecast, and the agency that publishes it.

### ⚙️ What it does

- Covers **47 countries and regions**, including the US, Euro Area, UK, Japan, China, Germany, Canada and Australia
- Filters by **country, date range, importance and category**, so you only get (and pay for) the events you need
- Returns events **sorted by date**, with times in UTC plus your own timezone
- Works for **past releases** (backtesting) and **upcoming events** (planning, alerts)

With no input at all, it returns US, Euro Area and Japan events from 3 days ago to 3 days ahead.

### 📥 Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `countries` | array | `["US", "EU", "JP"]` | Country or region codes to include |
| `daysBack` | integer | `3` | Days before today to include (0–30). Ignored when `fromDate` is set |
| `daysAhead` | integer | `3` | Days after today to include (0–30). Ignored when `toDate` is set |
| `fromDate` | string | – | Fixed start date, `YYYY-MM-DD` |
| `toDate` | string | – | Fixed end date, `YYYY-MM-DD` |
| `importance` | array | all | Any of `high`, `medium`, `low` |
| `categories` | array | all | Any of `prce` (prices & inflation), `lbr` (labour), `gdp`, `mny` (money & interest rates), `bsnss` (business), `cnsm` (consumer), `hse` (housing), `trd` (trade), `gov` (government), `bnd` (bonds), `enrg` (energy), `mrkt` (markets) |
| `timezone` | string | `UTC` | IANA timezone for `local_date` and `local_time`, e.g. `Europe/Berlin` |
| `maxEvents` | integer | no limit | Stop after this many events |
| `proxyConfiguration` | object | none | Optional Apify proxy settings |

A few events have no category. They are left out whenever `categories` is set.

#### Example: US and UK high-impact inflation and jobs data this week

```json
{
  "countries": ["US", "GB"],
  "importance": ["high", "medium"],
  "categories": ["prce", "lbr"],
  "daysBack": 0,
  "daysAhead": 7,
  "timezone": "America/New_York"
}
```

#### Example: every German release in a fixed window

```json
{
  "countries": ["DE"],
  "fromDate": "2026-09-01",
  "toDate": "2026-09-30"
}
```

### 📤 Output

Each dataset item is one event:

```json
{
  "id": "403228",
  "date": "2026-09-14T04:30:00.000Z",
  "country": "JP",
  "currency": "JPY",
  "title": "Industrial Production MoM Final",
  "indicator": "Industrial Production Mom",
  "ticker": "ECONOMICS:JPIPMM",
  "category": "bsnss",
  "categoryName": "Business",
  "importance": -1,
  "importanceLabel": "low",
  "actual": -0.2,
  "actualRaw": -0.2,
  "forecast": 0.1,
  "forecastRaw": 0.1,
  "previous": 1.9,
  "previousRaw": 1.9,
  "surprise": -0.3,
  "unit": "%",
  "scale": null,
  "referenceDate": "2026-07-31T00:00:00Z",
  "period": "Jul",
  "source": "Ministry of Economy Trade and Industry (METI)",
  "source_url": "http://www.meti.go.jp",
  "comment": "In Japan, industrial production measures the output of businesses integrated in industrial sector of the economy such as manufacturing, mining, and utilities.",
  "local_date": "2026-09-14",
  "local_time": "04:30:00",
  "scrapedAt": "2026-09-15T15:29:52.114Z"
}
```

| Field | Description |
|-------|-------------|
| `date` | Release time in UTC |
| `local_date`, `local_time` | Release time in the `timezone` you chose |
| `importance` / `importanceLabel` | `-1` / `low`, `0` / `medium`, `1` / `high` |
| `category` / `categoryName` | Category code and its readable name |
| `actual`, `forecast`, `previous` | Values in the display scale, e.g. `206` for 206K jobless claims |
| `actualRaw`, `forecastRaw`, `previousRaw` | Full values, e.g. `206000` |
| `unit`, `scale` | What the values are in: `%`, `$`, `€`… and `K`, `M`, `B`, `T` |
| `surprise` | `actual − forecast`, in the same unit and scale. `null` until the event is released or when there is no forecast |
| `ticker` | Indicator ticker, e.g. `ECONOMICS:USCPI` |
| `period`, `referenceDate` | The period the release covers |
| `source`, `source_url` | The agency that publishes the figure |
| `comment` | Short description of the indicator |
| `scrapedAt` | When the data was fetched (UTC) |

Fields with no value are `null`.

### 💰 Pricing

You pay per event returned. Use the filters to pull only what you need: a single country with `importance: ["high"]` typically returns a handful of events per week.

### 🔁 Use cases

- Feed macro data into trading bots, backtests and AI agents
- Build economic dashboards and reports
- Get alerted before high-impact releases, or react to surprises as they print

### ❗ Notes

- A run fails with a clear message if the input is invalid (unknown timezone, `fromDate` after `toDate`) or the calendar source does not respond, so you never get a silent empty dataset.
- Upcoming events have `actual: null` until they are released. Schedule the Actor to run again after the release to pick up the actual value.

***

*This actor is intended for internal analytics and research purposes. Ensure compliance with any third-party data terms.*

# Actor input Schema

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

Countries or regions to pull events for. Defaults to United States, Euro Area and Japan.

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

How many days before today to include. Ignored when From date is set.

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

How many days after today to include. Ignored when To date is set.

## `fromDate` (type: `string`):

Optional fixed start date (YYYY-MM-DD). Overrides Days back.

## `toDate` (type: `string`):

Optional fixed end date (YYYY-MM-DD). Overrides Days ahead.

## `importance` (type: `array`):

Keep only events with these importance levels. Leave empty for all.

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

Keep only events in these categories. Leave empty for all. A few events have no category and are dropped when this is set.

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

IANA timezone used for local\_date and local\_time, e.g. Europe/Berlin or America/New\_York. The date field always stays in UTC.

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

Stop after this many events. Leave empty for no limit.

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

Proxy servers let you bypass website protections, avoid IP address blocking and view content for other countries. Try to use the proxy if you are experiencing timeout errors.

## Actor input object example

```json
{
  "countries": [
    "US",
    "EU",
    "JP"
  ],
  "daysBack": 3,
  "daysAhead": 3,
  "importance": [],
  "categories": [],
  "timezone": "UTC",
  "proxyConfiguration": {}
}
```

# 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",
        "EU",
        "JP"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("aldines/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 = { "countries": [
        "US",
        "EU",
        "JP",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("aldines/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 '{
  "countries": [
    "US",
    "EU",
    "JP"
  ]
}' |
apify call aldines/economic-calendar --silent --output-dataset

```

## MCP server setup

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