ZipLime/us-economic-events

US Economic Events

What the US government published, when the embargo lifted, and what the number was at that moment — not what it has since been revised to.

2 994 official releases · 34 251 observations · 13 323 events · 12 release families · 2010-01-07 to 2026-09-10

The pipeline lives in `recipe/` at the same revision as the data. See PIPELINE.md for the method.

The number you remember is not the number that was published

Total nonfarm payrolls for May 2026, as the Bureau of Labor Statistics told it:

Every macro API will tell you May 2026 was +63 000. On 5 June the market saw +172 000 and traded on it. A backtest that reads today's series into June is trading on information that did not exist, and the error is not small: the median absolute revision between a payroll month's first and latest published value in this dataset is 35 000, and March 2020 went from −701 000 to −1 683 000.

This dataset keeps every vintage. Nothing is ever overwritten.

The timestamp is read out of the release

Transmission of material in this release is embargoed until
8:30 a.m. (ET) Friday, September 11, 2026            USDL-26-1496

That line, in the release itself, is where release_at comes from — not from a calendar, and not from a rule. Every one of the 2 994 releases lands at 08:30 or 10:00 Eastern, which is the check that the times are right: if an offset had been assumed rather than read, some would sit at four in the morning.

The offset is never computed. 08:30 in Washington is 12:30 UTC in September and 13:30 UTC in December, and which one applies is a question for the timezone database.

Rules about release dates are wrong often enough to matter

Weekly jobless claims come out on Thursday — except 28 times since 2010, when the release moved to the Wednesday for Thanksgiving, Christmas or New Year. The Employment Situation is not always the first Friday. Releases are discovered from the agencies' own archives and schedules, never generated from a rule, and the schedule is published here as its own table.

What is in it

55 indicators, each declared in `config/indicators.yaml` with its unit, frequency and seasonal adjustment. Coverage is not the same for all of them — see `metadata/coverage.csv` — and that is deliberate rather than hidden:

• —The PPI headline changed in January 2014, from finished goods to final demand. Those are different populations and different numbers, so they are different series here (PPI_FINISHED_GOODS_MOM, PPI_FINAL_DEMAND_MOM) and neither is spliced onto the other.
• —*`PPI_CORE_` starts in 2016**, when "less foods, energy, and trade services" was added to the release.
• —`PCE_PRICE_YOY` and `CORE_PCE_PRICE_YOY` have a hole from 2018 to 2022, because BEA's summary stated only the monthly change in those years.
• —October 2025 has no CPI monthly change, because the lapse in appropriations stopped collection. The November release printed a two-month change instead. The gap is real and is left as a gap.

previous and revised_previous are different columns

This is what separates the dataset from a macro calendar. In events:

26% of events revise their own previous period. For payrolls it is 190 of 197 releases. The revision regularly moves rates more than the headline does, and a table with a single "previous" column cannot show it.

US_NONFARM_PAYROLLS_CHANGE_2026-06, released 2 July 2026 08:30 ET
  actual               57000    June, as published that morning
  previous            172000    May, as the market knew it the evening before
  revised_previous    129000    May, as this same release restates it
  previous_revision   -43000    the revision, which was the news

forecast is present and always null. Consensus estimates are licensed data and none are included, so actual - previous is called change_from_previous_period and never surprise.

GDP is published three times and stays three rows

estimate_stage names which, and the event id carries it. The advance estimate is what the market traded at the end of April; the third estimate did not exist then. Collapsing them into one row for the quarter is the same mistake as overwriting a revision.

Configs

All five carry knowledge_date, so all five mount rather than only pit.

events — what most people want

import polars as pl

events = pl.read_parquet("data/events/*.parquet")
cpi = events.filter(pl.col("indicator") == "CPI_ALL_YOY").select(
    "release_at", "reference_period", "actual", "previous", "revised_previous"
)

observations — what a point-in-time question needs

observations = pl.read_parquet("data/observations/*.parquet")

def value_as_of(series: str, period: str, as_of: str) -> float | None:
    """The value that was public at `as_of`, and nothing later."""
    known = observations.filter(
        (pl.col("series_id") == series)
        & (pl.col("reference_period") == period)
        & (pl.col("vintage_at") <= pl.lit(as_of).str.to_datetime(time_zone="UTC"))
    ).sort("vintage_at")
    return known["value"].last() if known.height else None

value_as_of("NONFARM_PAYROLLS_CHANGE", "2026-05", "2026-06-20T00:00:00Z")  # 172000.0
value_as_of("NONFARM_PAYROLLS_CHANGE", "2026-05", "2026-08-20T00:00:00Z")  #  63000.0

5 964 (series, period) pairs have more than one vintage, and 6 435 observations are revisions of a value this dataset already held. One period has been restated 13 times.

The weekly claims release states its own revisions in words — "The previous week's level was revised up by 1,000 from 206,000 to 207,000" — so both halves are recorded, and the value it replaced is already here from the week before. The last week of March 2020 was first published at 6 648 000 and restated a week later at 6 867 000.

calendar

The agencies' own schedules, matched to the releases that answered them:

cancelled means the scheduled date passed with no release — which is how the autumn of 2025 appears. A calendar entry's knowledge_date is when the schedule was collected, never the date it points at.

Known gaps

• —No consensus forecasts, and therefore no surprise. Consensus is licensed data. forecast is there and empty.
• —38 releases are quarantined, listed with their reason in `metadata/quarantine.csv`. A release that cannot be read completely is not published half-read.
• —Some Tier-1 series are declared and empty. RETAIL_SALES_EX_AUTOS_MOM and the core capital goods series are in the registry because they belong in it, but Census prints them only in the tables of a PDF, not in its prose, and nothing here reads a PDF table. metadata/coverage.csv is the record of which indicators actually have values.
• —Average hourly earnings changes are `derived` in about half the releases. The release always prints the level; it states the percentage in wording that varies from year to year. Where the wording is unambiguous the stated figure is used and value_method says reported; otherwise the change is computed from the levels in that same release, to two decimals rather than the one decimal the agency prints.
• —Backfill starts in 2010. BLS archives reach 1994 and ETA 2004, in layouts that are not read yet.
• —Not a low-latency feed. The dataset is rebuilt twice on weekday mornings. For a backtest the information timestamp is release_at, which is exact; for live trading this is not the tool.

Provenance

Every release row carries its source URL, the sha256 of the bytes that were parsed, and the parser version, so any figure can be traced back to the agency's own archived document and checked.

Sources: the news release archives and release schedules of the Bureau of Labor Statistics, the Employment and Training Administration, the Census Bureau and the Bureau of Economic Analysis. US Government works, public domain. Rebuilt on Hugging Face Jobs on weekday mornings, after the 08:30 and 10:00 Eastern releases.