# US Economic Calendar – BLS, BEA & Fed Official Release Dates (`polychrome_haymow/us-econ-calendar`) Actor

US economic release calendar from official public-domain schedules only: BLS (CPI, jobs, PPI), BEA (GDP, PCE) and the Fed (FOMC, G.17, H.4.1). ET times, links, actual/prior values.

- **URL**: https://apify.com/polychrome_haymow/us-econ-calendar.md
- **Developed by:** [Levani Zurabiani](https://apify.com/polychrome_haymow) (community)
- **Categories:** Business, News, Integrations
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $9.00 / 1,000 release rows

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

## US Economic Calendar – BLS, BEA & Fed Official Release Dates

Get the US macro release calendar straight from the agencies that publish the data: the **Bureau of Labor Statistics** (CPI, Employment Situation/NFP, PPI, JOLTS, import prices…), the **Bureau of Economic Analysis** (GDP, Personal Income & Outlays/PCE, trade…) and the **Federal Reserve Board** (FOMC meetings and statistical releases such as G.17, G.19, H.4.1, H.6, H.8). Every row has the date and time in **Eastern Time**, the agency, the release name, the reference period, a link to the official release page and, for headline releases, the **actual and prior values** from official data.

No ForexFactory, Investing.com or other commercial calendar is used. All schedules are US federal government works and in the public domain.

### How it works

1. Downloads the official schedules: the BLS release calendar (`bls.gov/schedule/news_release/bls.ics`), the BEA release calendar (`bea.gov` ICS feed), the Federal Reserve statistical release calendar (`federalreserve.gov/data/releaseschedule.htm`) and the FOMC meeting calendar (`federalreserve.gov/monetarypolicy/fomccalendars.htm`).
2. Converts every time to ET with the correct daylight-saving offset (BEA publishes UTC; the Fed publishes "8:30 a.m." text).
3. Filters to your date range and keywords, removes duplicates and sorts the rows chronologically.
4. Optionally adds actual and prior values:
   - **BLS public API (no key needed):** nonfarm payrolls change, unemployment rate, CPI and core CPI m/m, PPI final demand m/m, JOLTS openings and import prices m/m.
   - **FRED (optional, off by default):** BEA GDP, PCE and core PCE, the trade balance, Fed industrial production (G.17) and consumer credit (G.19). This runs only when a FRED key is supplied in the `fredApiKey` input (stored as a secret) or, as a fallback, the `FRED_API_KEY` environment variable. Only an allow-list of series whose original source is a US federal agency is requested, and any series whose FRED notes carry a copyright notice is refused. Third-party copyrighted series (for example S\&P, ICE BofA, Moody's or Wilshire) are never fetched.

Requests declare a User-Agent (`us-econ-calendar/0.1 (Apify actor; +https://apify.com; contact: <your email>)`) and retry 429 and 5xx responses with backoff. Each run makes only about 5–15 HTTP requests.

### Input example

```json
{ "startDate": "today", "endDate": "+30d", "sources": ["BLS", "BEA", "FED_STAT", "FOMC"], "keywords": [], "includeValues": true, "maxItems": 500 }
```

Use `keywords` (for example `["cpi", "employment situation", "fomc", "gdp"]`) to get only market-moving releases. The daily Fed releases (H.15, H.10, Commercial Paper) are excluded unless you turn on `includeDailyFedReleases`.

### Output example

```json
{
  "dateEt": "2026-10-02", "timeEt": "08:30", "dateTimeEt": "2026-10-02T08:30:00-04:00", "dateTimeUtc": "2026-10-02T12:30:00.000Z",
  "agency": "BLS", "source": "BLS", "releaseName": "Employment Situation", "period": "2026-09",
  "link": "https://www.bls.gov/news.release/empsit.toc.htm", "isPast": true, "isApproximateDate": false,
  "actual": 29, "prior": 133, "unit": "thousands",
  "values": [
    { "seriesId": "CES0000000001", "label": "Nonfarm payrolls, change", "unit": "thousands", "provider": "BLS", "period": "2026-09", "actual": 29, "prior": 133 },
    { "seriesId": "LNS14000000", "label": "Unemployment rate", "unit": "%", "provider": "BLS", "period": "2026-09", "actual": 4.4, "prior": 4.3 }
  ],
  "scheduleUrl": "https://www.bls.gov/schedule/news_release/", "attribution": "U.S. Bureau of Labor Statistics (public domain)"
}
```

Values above are illustrative. `prior` is the latest official (revised) value for the previous period. It is not the first print.

### Pricing

Pay per event: **$0.009 per release row** (`release-row`) plus the standard Apify actor-start fee. A typical month of releases (about 35 rows without the daily Fed series) costs about $0.32. The run stops cleanly when it reaches the **max cost per run** you set.

### Integrations (Zapier / Make)

Schedule the actor in Apify Console (for example every Monday at 06:00 ET with `endDate: "+7d"`). Then use Apify's **Zapier** or **Make** integration, or a webhook on "run succeeded", to push the week's releases to Google Calendar, Slack, Notion or Google Sheets. The dataset is also available as CSV, XLSX or JSON from the API.

### FAQ

**Where does the data come from?** Only from official US government sources: BLS, BEA and the Federal Reserve Board websites and the BLS public API. FRED is used only if you supply your own key.

**Does it use ForexFactory, Investing.com or other commercial calendars?** No. That also means there are no consensus forecasts, because forecasts are proprietary.

**Why are some `actual`/`prior` values null?** Values are mapped for headline series only. **`actual` is always `null` for future releases** (rows with `isPast: false`): the number does not exist until the agency publishes it at the scheduled time, so only `prior` (the latest published value) is filled in. Re-run after the release time to get `actual`. BEA and Fed values need a FRED key (`fredApiKey` input or `FRED_API_KEY`).

**Which time zone is used?** US Eastern (America/New_York), with the correct EST/EDT offset in `dateTimeEt`. The UTC time is in `dateTimeUtc`.

**How far ahead can I see?** As far as the agencies publish. BLS and the Fed usually publish through the end of the next year, BEA a few months ahead, and the FOMC through the next year.

**Do I need an API key?** No. The BLS API key (free) only raises the daily limits. The FRED key is optional; pass it in the secret `fredApiKey` input (or set the `FRED_API_KEY` environment variable).

**Are dates ever approximate?** Yes. When the Fed marks a date as approximate (for example G.20), `isApproximateDate` is true. Agencies also reschedule releases, for example during government shutdowns, so run the actor again before you rely on a date.

**What permissions does it need?** It runs with **limited permissions** and only writes to its own default dataset and key-value store.

### Licence & attribution

BLS, BEA and Federal Reserve Board schedules and data are US government works in the public domain. Cite the agency. When FRED values are included: "Source: FRED, Federal Reserve Bank of St. Louis". This product uses the FRED® API but is not endorsed or certified by the Federal Reserve Bank of St. Louis. Your use of FRED is subject to the FRED API Terms of Use (https://fred.stlouisfed.org/docs/api/terms_of_use.html).

### Disclaimer

This actor is not affiliated with BLS, BEA, the Federal Reserve or the Federal Reserve Bank of St. Louis. Schedules can change, so always check critical dates on the linked official page. This is not investment advice.

### Running locally

```bash
npm ci
npm test            # unit tests (mocked HTTP)
npm run test:live   # live checks against bls.gov, bea.gov, federalreserve.gov, api.bls.gov
npm start           # uses storage/key_value_stores/default/INPUT.json
FRED_API_KEY=... npm start   # optional FRED enrichment
```

# Actor input Schema

## `startDate` (type: `string`):

First day (ET) to include: YYYY-MM-DD, "today" or a relative offset like "-7d".

## `endDate` (type: `string`):

Last day (ET) to include: YYYY-MM-DD or offset like "+30d" (relative to today). Default: start + 30 days. Max range ~2 years.

## `sources` (type: `array`):

BLS = Bureau of Labor Statistics release schedule; BEA = Bureau of Economic Analysis schedule; FED_STAT = Federal Reserve Board statistical release calendar; FOMC = FOMC meeting calendar.

## `includeDailyFedReleases` (type: `boolean`):

Include H.15, H.10 and Commercial Paper, which publish almost every business day (adds ~60 rows/month).

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

Only keep releases whose name/agency/period contains any of these (case-insensitive), e.g. "cpi", "employment situation", "fomc", "gdp". Empty = all.

## `includeValues` (type: `boolean`):

Add official actual and prior values for headline series: BLS public API (payrolls, unemployment, CPI, PPI, JOLTS, import prices) and, only if a FRED API key is supplied (fredApiKey input or FRED_API_KEY env var), BEA/Fed series via FRED.

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

Stop after this many rows (hard cap 5,000). Runs also stop when your max cost per run is reached.

## `contactEmail` (type: `string`):

Added to the declared User-Agent so agencies can contact the operator (BLS asks automated clients to identify themselves).

## `blsApiKey` (type: `string`):

Free key from https://data.bls.gov/registrationEngine/ for higher daily limits on the BLS public API. Not needed for normal use.

## `fredApiKey` (type: `string`):

Free key from https://fred.stlouisfed.org/docs/api/api_key.html. Enables BEA (GDP, PCE, trade) and Fed (G.17, G.19) actual/prior values via FRED. Falls back to the FRED_API_KEY environment variable.

## Actor input object example

```json
{
  "startDate": "today",
  "endDate": "+30d",
  "sources": [
    "BLS",
    "BEA",
    "FED_STAT",
    "FOMC"
  ],
  "includeDailyFedReleases": false,
  "keywords": [],
  "includeValues": true,
  "maxItems": 1000
}
```

# Actor output Schema

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

All rows (JSON; append ?format=csv|xlsx).

## `overview` (type: `string`):

Calendar view.

## `stats` (type: `string`):

Rows per source, errors, values, budget stop.

# 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 = {
    "startDate": "today",
    "endDate": "+30d",
    "sources": [
        "BLS",
        "BEA",
        "FED_STAT",
        "FOMC"
    ],
    "keywords": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("polychrome_haymow/us-econ-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 = {
    "startDate": "today",
    "endDate": "+30d",
    "sources": [
        "BLS",
        "BEA",
        "FED_STAT",
        "FOMC",
    ],
    "keywords": [],
}

# Run the Actor and wait for it to finish
run = client.actor("polychrome_haymow/us-econ-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 '{
  "startDate": "today",
  "endDate": "+30d",
  "sources": [
    "BLS",
    "BEA",
    "FED_STAT",
    "FOMC"
  ],
  "keywords": []
}' |
apify call polychrome_haymow/us-econ-calendar --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,polychrome_haymow/us-econ-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/jm0fIdSWVvJ7aYIUz/builds/PqZOYeyH6ffe5Z0S6/openapi.json