# Economic Calendar (`amdcode/economic-calendar-aggregator`) Actor Official economic calendar API for the US and UK: CPI, NFP, GDP, retail sales, jobless claims, and Fed/BoE rate decisions, sourced live from FRED and ONS. Includes exact release times and first-print vs. revised values for backtesting. No API key to register. - **URL**: https://apify.com/amdcode/economic-calendar-aggregator.md - **Developed by:** [Amos Dorceus](https://apify.com/amdcode) (community) - **Categories:** News, Real estate - **Stats:** 3 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.50 / 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 **Official Economic Calendar** is an **economic calendar API** that returns **official economic release events** — Employment, Inflation (CPI, PPI, Core PCE), GDP, Retail Sales, Industrial Production, Housing Starts, Trade Balance, Consumer Sentiment, Wage Growth, Jobless Claims, and central bank rate decisions — sourced directly from primary statistical authorities: the **Federal Reserve Bank of St. Louis (FRED)** for the United States and the **UK Office for National Statistics (ONS) / Bank of England** for the United Kingdom — the same data trading desks, analysts and researchers use as ground truth. Unlike a scraped forex/trading economic calendar website, every event links back to its original government release. Pick a date range as wide as you need (multiple years of history, or upcoming scheduled releases), one or more countries, and one or more indicators, and get every matching event back as structured data ready for backtesting, dashboards, or alerting. Eurozone and France coverage are on the roadmap. Running on [Apify](https://apify.com) means you get programmatic API access, scheduling to catch new releases automatically, integrations (Zapier/Make/Slack), and full run monitoring — with zero setup on your side: no API key to register, no rate limits to manage yourself. ### Why use this Actor? - **Backtesting & quant research** — pull years of official release dates and actual values in one call to test how markets historically reacted around specific indicators. - **Trading dashboards & alerts** — schedule runs to catch newly published figures the moment they're released. - **Reliable, primary-source data** — everything comes from each country's own statistical authority (FRED, ONS, Bank of England), not a third-party aggregator, so figures are authoritative and traceable back to the original release. - **No maintenance overhead** — official statistical APIs are stable and don't change their HTML layout under you the way scraped websites do. ### How to use it 1. Click **Try for free** (or **Start**) on the Actor page. 2. Set **From date** / **To date** for the period you want to analyze — this can span multiple years. 3. Optionally select one or more **Countries** (United States, United Kingdom). Leave empty to get all of them. 4. Optionally select one or more **Indicators** (18 available across both countries — employment, inflation, growth, trade, sentiment, and central bank rate decisions; see the Input table below for the full list). Leave empty to get all indicators available for the selected countries. 5. Click **Start** and wait for the run to finish. 6. Open the **Dataset** tab to view, filter, and export the results. ### Input | Field | Type | Description | |---|---|---| | `countries` | array | Which countries to include (`US`, `GB`). Empty = all. | | `dateFrom` | string (YYYY-MM-DD) | Start of the date range. | | `dateTo` | string (YYYY-MM-DD) | End of the date range. | | `categories` | array | Which indicators to include. Empty = all available for the selected countries. Country-specific indicators (e.g. `NFP`) are only fetched for the countries they apply to. See the full list below. | | `maxEventsPerCategory` | integer | Safety cap per indicator per country. `0` = unlimited within the date range. | Available `categories` values: | Code | Indicator | Countries | |---|---|---| | `NFP` | Non-Farm Payrolls | US | | `UNEMPLOYMENT_RATE` | Unemployment Rate | US, GB | | `CPI` | Consumer Price Index | US, GB | | `PPI` | Producer Price Index | US | | `GDP` | Gross Domestic Product | US, GB | | `FED_FUNDS_RATE` | Federal Funds Rate Decision | US | | `BOE_BANK_RATE` | Bank of England Bank Rate Decision | GB | | `RETAIL_SALES` | Retail Sales | US, GB | | `INDUSTRIAL_PRODUCTION` | Industrial Production | US, GB | | `HOUSING_STARTS` | Housing Starts | US | | `DURABLE_GOODS_ORDERS` | Durable Goods Orders | US | | `TRADE_BALANCE` | Trade Balance | US | | `CONSUMER_SENTIMENT` | Consumer Sentiment (University of Michigan) | US | | `AVERAGE_HOURLY_EARNINGS` | Average Hourly Earnings | US | | `CORE_PCE_PRICE_INDEX` | Core PCE Price Index (the Fed's preferred inflation gauge) | US | | `PERSONAL_SPENDING` | Personal Spending (PCE) | US | | `INITIAL_JOBLESS_CLAIMS` | Initial Jobless Claims (weekly) | US | | `AVERAGE_EARNINGS_GROWTH` | Average Earnings Growth | GB | Example input: ```json { "countries": ["US", "GB"], "dateFrom": "2020-01-01", "dateTo": "2026-12-31", "categories": ["CPI", "CORE_PCE_PRICE_INDEX", "FED_FUNDS_RATE", "BOE_BANK_RATE"] } ```` ### Output Each dataset item is one economic event: ```json { "country": "US", "continent": "North America", "category": "NFP", "eventName": "Non-Farm Payrolls", "impactStars": 3, "releaseDateTime": "2024-02-02T13:30:00+00:00", "actualValue": 157032.0, "actualValueDisplay": "157M", "forecastValue": null, "previousValue": 216000.0, "previousValueDisplay": "216M", "firstPrintValue": 156933.0, "firstPrintValueDisplay": "157M", "unit": "Thousands of Persons", "frequency": "Monthly", "sourceName": "FRED (Federal Reserve Bank of St. Louis)", "sourceUrl": "https://fred.stlouisfed.org/release/50" } ``` You can download the dataset in various formats such as JSON, HTML, CSV, or Excel. #### Data fields | Field | Description | |---|---| | country | ISO country code (`US`, `GB`) | | continent | Continent, derived from country | | category | Normalized indicator code | | eventName | Human-readable event name | | impactStars | Editorial market-impact rating, 1 (low) to 3 (high) — see methodology below | | releaseDateTime | Official publication date/time, converted to UTC (ISO 8601) from the real local release time (e.g. 08:30 America/New\_York for most US releases, 07:00 Europe/London for ONS) | | actualValue / actualValueDisplay | Latest (most revised) published value — raw number, and a compact human-readable string (e.g. `"215k"`, `"28.7T"`) for display. See methodology below. | | forecastValue | Market consensus estimate. Always `null` for now — no free official source publishes this; reserved for a future paid data source | | previousValue / previousValueDisplay | The value of this same indicator's immediately preceding release (same reference-period cadence), raw and compact | | firstPrintValue / firstPrintValueDisplay | The value as originally published on the release date, before later revisions — US/FRED only for now. `null` where not available (UK, or rate-decision events where there's no revision) | | unit | Unit of the value (percent, index, thousands of persons...) | | frequency | How often this indicator is published | | sourceName / sourceUrl | Traceability back to the original FRED/ONS/Bank of England release or series | ### Pricing / Cost estimation Runs are lightweight (structured API calls, no browser), so even multi-year, multi-country, multi-indicator requests complete in seconds. Check the **Pricing** tab for exact rates. A free tier is available for new Apify accounts to try the Actor. ### Tips / advanced options - Combine a narrow `categories` selection with a scheduled run to build a near real-time alert pipeline for a specific indicator. - `FED_FUNDS_RATE` and `BOE_BANK_RATE` events represent actual rate **decision** dates (detected from the daily target-rate series), not every daily interest-rate bulletin — you get one event per real policy change, not noise. - Some US indicators occasionally show two close release dates in the same month (e.g. an annual benchmark revision published shortly after the regular release) — this reflects FRED's own official release calendar, not a duplicate. - UK indicators (`CPI`, `UNEMPLOYMENT_RATE`, `GDP`, `RETAIL_SALES`, `INDUSTRIAL_PRODUCTION`, `AVERAGE_EARNINGS_GROWTH`) use each ONS observation's own recorded date, since ONS does not expose a separate announcement-date calendar the way FRED does — dates are correct but reflect the reference period rather than a distinct bulletin date. - `INITIAL_JOBLESS_CLAIMS` is the only weekly indicator; its `releaseDateTime` is the actual Thursday announcement date, matched to the correct reference week's value. - `firstPrintValue` (US indicators only, `release_calendar` strategy) uses FRED's free ALFRED vintage data to show the value exactly as it was first published, before any later revisions — useful for backtesting what the market actually reacted to, since `actualValue` reflects today's fully revised figure. Not available for UK indicators or for `FED_FUNDS_RATE`/`BOE_BANK_RATE` (rate decisions aren't revised). - `*Display` fields (`actualValueDisplay`, `previousValueDisplay`, `firstPrintValueDisplay`) are compact, human-readable strings (`"215k"`, `"700B"`, `"28.7T"`) — the raw number is unit-aware first (e.g. a `"Millions of Dollars"` value is scaled to real dollars before picking k/M/B/T, so a $700B retail sales figure reads as `"700B"`, never a misleading `"700k"`). Percent and Index units are never compacted, just cleanly trimmed (`5.25`, not `5.250000`). Always use the plain numeric field (`actualValue`, etc.) for calculations — the `Display` fields are for presentation only. - `previousValue` is this indicator's prior release, computed from the same underlying series — not a separate API call, so it's always in sync with `actualValue`. - `impactStars` is a static editorial classification (1-3), similar to what ForexFactory/Investing.com show — it is **not** published by FRED/ONS/BoE. NFP, CPI, GDP, Core PCE, and central bank rate decisions are rated 3 (high); PPI, Retail Sales, Industrial Production, Jobless Claims, and earnings/sentiment indicators are 2 (medium); the remainder are 1 (low). ### FAQ, disclaimers, and support **Is there a free economic calendar API?** Yes — this Actor wraps the free FRED, ONS, and Bank of England APIs, so there's no third-party API key to register and Apify's free tier covers light usage. **How do I get economic calendar data via API?** Set `countries`, `dateFrom`/`dateTo`, and optionally `categories` as input (see above), run the Actor, and read the results from the Dataset via the Apify API, webhook, or a scheduled export to JSON/CSV. **Does this include CPI, NFP, GDP, and interest rate decisions?** Yes, along with 14 other indicators across the US and UK — see the full `categories` table above. This Actor only uses free, public official APIs: the **FRED API** (Federal Reserve Bank of St. Louis), the **ONS API** (UK Office for National Statistics), and the **Bank of England Statistical Database** — all explicitly designed for reuse, including commercial use. Every value (`actualValue`, `previousValue`, `firstPrintValue`) reflects real published government/central bank statistics. `impactStars` is our own editorial classification (see above), and `forecastValue` is reserved but always `null`, since market consensus forecasts aren't published as objective facts by any official source. Coverage currently spans the United States and United Kingdom — Eurozone and France are planned next. If you have suggestions, run into an issue, or want a custom extension (more indicators, more countries, alerting, or a forecast/consensus data source), open an issue in the Actor's **Issues** tab. # Actor input Schema ## `countries` (type: `array`): Which countries to include. Leave empty to include all available countries. ## `dateFrom` (type: `string`): Start of the date range (YYYY-MM-DD) ## `dateTo` (type: `string`): End of the date range (YYYY-MM-DD) ## `categories` (type: `array`): Which economic indicators to include. Leave empty to include all available indicators. Some indicators are country-specific (see labels) and are only fetched for the countries they apply to. ## `maxEventsPerCategory` (type: `integer`): Safety cap on the number of data points fetched per indicator (0 = unlimited within the date range). ## Actor input object example ```json { "countries": [], "dateFrom": "2024-01-01", "dateTo": "2026-12-31", "categories": [], "maxEventsPerCategory": 0 } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "dateFrom": "2024-01-01", "dateTo": "2026-12-31" }; // Run the Actor and wait for it to finish const run = await client.actor("amdcode/economic-calendar-aggregator").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "dateFrom": "2024-01-01", "dateTo": "2026-12-31", } # Run the Actor and wait for it to finish run = client.actor("amdcode/economic-calendar-aggregator").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 '{ "dateFrom": "2024-01-01", "dateTo": "2026-12-31" }' | apify call amdcode/economic-calendar-aggregator --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=amdcode/economic-calendar-aggregator", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Economic Calendar", "description": "Official economic calendar API for the US and UK: CPI, NFP, GDP, retail sales, jobless claims, and Fed/BoE rate decisions, sourced live from FRED and ONS. Includes exact release times and first-print vs. revised values for backtesting. No API key to register.", "version": "0.0", "x-build-id": "joEC3In6XvytDE2Ot" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/amdcode~economic-calendar-aggregator/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-amdcode-economic-calendar-aggregator", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/amdcode~economic-calendar-aggregator/runs": { "post": { "operationId": "runs-sync-amdcode-economic-calendar-aggregator", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/amdcode~economic-calendar-aggregator/run-sync": { "post": { "operationId": "run-sync-amdcode-economic-calendar-aggregator", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "dateFrom", "dateTo" ], "properties": { "countries": { "title": "Countries", "type": "array", "description": "Which countries to include. Leave empty to include all available countries.", "items": { "type": "string", "enum": [ "US", "GB" ], "enumTitles": [ "United States", "United Kingdom" ] }, "default": [] }, "dateFrom": { "title": "From date", "type": "string", "description": "Start of the date range (YYYY-MM-DD)" }, "dateTo": { "title": "To date", "type": "string", "description": "End of the date range (YYYY-MM-DD)" }, "categories": { "title": "Indicators", "type": "array", "description": "Which economic indicators to include. Leave empty to include all available indicators. Some indicators are country-specific (see labels) and are only fetched for the countries they apply to.", "items": { "type": "string", "enum": [ "NFP", "UNEMPLOYMENT_RATE", "CPI", "PPI", "GDP", "FED_FUNDS_RATE", "BOE_BANK_RATE", "RETAIL_SALES", "INDUSTRIAL_PRODUCTION", "HOUSING_STARTS", "DURABLE_GOODS_ORDERS", "TRADE_BALANCE", "CONSUMER_SENTIMENT", "AVERAGE_HOURLY_EARNINGS", "CORE_PCE_PRICE_INDEX", "PERSONAL_SPENDING", "INITIAL_JOBLESS_CLAIMS", "AVERAGE_EARNINGS_GROWTH" ], "enumTitles": [ "Non-Farm Payrolls (US)", "Unemployment Rate", "Consumer Price Index (CPI)", "Producer Price Index (PPI, US)", "Gross Domestic Product (GDP)", "Federal Funds Rate (US)", "Bank of England Bank Rate (UK)", "Retail Sales", "Industrial Production", "Housing Starts (US)", "Durable Goods Orders (US)", "Trade Balance (US)", "Consumer Sentiment (US)", "Average Hourly Earnings (US)", "Core PCE Price Index (US)", "Personal Spending (US)", "Initial Jobless Claims (US)", "Average Earnings Growth (UK)" ] }, "default": [] }, "maxEventsPerCategory": { "title": "Max events per indicator", "minimum": 0, "type": "integer", "description": "Safety cap on the number of data points fetched per indicator (0 = unlimited within the date range).", "default": 0 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```