Macro & Fed Calendar from Official Sources API (v0.2.0)

Economic release dates, FOMC meetings/minutes, Fed speeches and testimony, and Treasury auctions, normalized from official US sources only: Federal Reserve Board, BLS, BEA, Treasury Fiscal Data, U.S. Census Bureau (economic-indicator calendar), FHFA (house price index release dates), plus optional FRED/ALFRED. All times are America/New_York (ET).

This product uses the FRED® API but is not endorsed or certified by the Federal Reserve Bank of St. Louis. By using the FRED features you agree to the FRED API Terms of Use. Not affiliated with or endorsed by the Federal Reserve, BLS, BEA, U.S. Treasury, U.S. Census Bureau or FHFA. Importance levels are our own classification. Not investment advice. See TERMS.md.

Event schema

field	type	notes
id	str	stable sha1(source,date,time,event)[:16]
sources	list[str]	every source reporting this event, e.g. ["bls","fred"] after a merge; the source filter matches any entry
date	YYYY-MM-DD	ET
time_et	HH:MM or null	null when the source gives only a date (Treasury, FRED)
datetime_et	ISO 8601 with offset, or null
source	fed, bls, bea, treasury, census, fhfa, fred
event, category	str	category: economic_release, monetary_policy, fed_speech, fed_testimony, fed_statistical_release, treasury_auction
importance	high, medium, low	editorial rules in macro_calendar/importance.py
previous, actual, unit	float/str or null	FRED safe series only (CPI, NFP, real GDP, PCE price, PPI)
details	object	source-specific (cusip, offering_amt, description, release_id...)
source_url, attribution	str	always populated

Run locally

python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements-dev.txt   # required before pytest: test deps (pytest) are not in requirements.txt
cp .env.example .env   # set MACRO_USER_AGENT (contact email); FRED_API_KEY optional
set -a; . ./.env; set +a
pytest -q                                   # offline, fixtures only (network is blocked in tests)
uvicorn macro_calendar.api:app --port 8000  # HTTP API, docs at /docs
python main.py                              # one-shot JSON (reads ./input.json if present)

HTTP API

• FRED source: curated US releases by default (set FRED_ALL_RELEASES=1 for all). On Apify the key comes only from the buyer's own fredApiKey input (secret field; no env or file fallback); without it FRED is skipped with a warning. Local CLI/API dev may use FRED_API_KEY or .fred_key. The key is redacted (api_key=REDACTED) from all errors and logs and never appears in dataset rows. Value enrichment checks each series' FRED notes and skips any series marked third-party copyrighted.
• GET /events?from=YYYY-MM-DD&to=YYYY-MM-DD&source=bls,bea&importance=medium&q=CPI&limit=500. importance is a minimum: medium returns high and medium.
• GET /next?n=5&importance=high&source=fed: the next upcoming events after now (ET).
• GET /sources: endpoints and attribution. GET /health: status, cache size, per-source errors.
• If one source fails, the other sources still return results. The failure is reported in errors/source_errors. Stale cache is served when a fetch fails.

Caching and politeness

On-disk cache in MACRO_CACHE_DIR (TTL 1h for Fed/Treasury, 6h for BLS/BEA/FRED). The in-process API refreshes every 15 min, with ≥1s between requests to the same host.

Apify actor

main.py, .actor/actor.json, .actor/input_schema.json, Dockerfile. Input: contactEmail (needed for BLS: it goes in the HTTP User-Agent macro-calendar/0.1 (contact: <email>), is never written to output, and without it BLS returns 403), sources, daysBack/daysAhead or from/to, minImportance, query, fredApiKey (secret, the user's own key). Default memory is 256 MB. Output: one dataset item per event, and a SOURCE_ERRORS key-value record.

Layout

macro_calendar/sources/{fed,bls,bea,treasury,census,fhfa,fred}.py hold the fetchers and parsers. ics.py is the iCal parser, http.py handles cache and rate limiting, aggregator.py does filtering and sorting, api.py is the FastAPI app. tests/ holds offline tests and fixtures. The FRED fixtures are synthetic. The others are trimmed real responses captured 2026-10-11 (Census/FHFA pages captured 2026-10-12).

Known gaps / roadmap

Census and FHFA give dates only (no values; the Census Data API is not used, so no Census key is needed). FHFA gives no release time. NAR existing-home sales: not built, pending a terms-of-use review. S&P CoreLogic Case-Shiller: deliberately excluded (proprietary, licensed S&P data); the actor does not fetch it from any source, including FRED. No consensus forecasts. Treasury and FRED have no release times. FRED values attach to the release event: actual is the latest published observation, so for a future release date it is really the latest known value. A value-history endpoint (ALFRED first prints) is planned for later.

Cross-source de-duplication

When FRED and an official agency (BLS, BEA, Census, Fed) list the same release on the same date, one row is kept (macro_calendar/dedupe.py). Matching is an explicit table FRED_TO_AGENCY (normalized FRED release name -> agency + normalized agency-name prefix), never fuzzy. The agency row wins for date, time, name, id and source_url; FRED's previous/actual/unit are copied in when the agency row has none; FRED release/series ids and URL go into details; sources lists both; both attributions are kept. FRED rows with no mapped match (e.g. weekly jobless claims, or a different date) stay as source=fred. The number merged is logged on every run.

Sources

source id	Publisher	What	Endpoint	Times	Key
fed	Federal Reserve Board	FOMC, minutes, speeches, testimony	federalreserve.gov/json/calendar.json	yes	none
bls	BLS	CPI, jobs, PPI, JOLTS, ...	bls.gov/schedule/news_release/bls.ics	yes	none (contactEmail)
bea	BEA	GDP, PCE/income, trade	bea.gov iCal	yes	none
treasury	U.S. Treasury Fiscal Data	auctions	api.fiscaldata.treasury.gov	no	none
census	U.S. Census Bureau	housing starts & permits, new home sales, retail sales, durable goods, construction spending, advance economic indicators (goods trade)	https://www.census.gov/economic-indicators/calendar-listview.html + calendar-listview-{year}.html (HTML)	yes	none
fhfa	Federal Housing Finance Agency	FHFA house price index release dates (monthly/quarterly)	https://www.fhfa.gov/data/hpi#ReleaseDates (HTML)	no	none
fred	St. Louis Fed (FRED)	release dates + values for public-domain series	api.stlouisfed.org	no	buyer's own fredApiKey

"FHFA HPI" is FHFA's mark; we use it only to describe the data, not as product branding.

FRED attribution

This product uses the FRED® API but is not endorsed or certified by the Federal Reserve Bank of St. Louis. FRED® API Terms of Use.

Curated value series (all U.S.-government public-domain; FRED notes carry no copyright text, verified 2026-10-12):

Series	Release	Original source
CPIAUCSL	Consumer Price Index	BLS — https://www.bls.gov/cpi/
PAYEMS	Employment Situation	BLS — https://www.bls.gov/ces/
PPIFIS	Producer Price Index	BLS — https://www.bls.gov/ppi/
GDPC1	Gross Domestic Product	BEA — https://www.bea.gov/data/gdp
PCEPI	Personal Income and Outlays	BEA — https://www.bea.gov/data/personal-consumption-expenditures-price-index

Copyrighted series (e.g. S&P/Case-Shiller CSUSHPINSA, SP500) are never fetched for values.