Skip to main content

Economic data revisions

This recipe reads the first print of each month's nonfarm payrolls and compares it with the current value. A model or backtest that uses macro data reads the first print, since a revised value was not yet known. It uses series observations with known_at.

python
import datetime
import os

import httpx

api = httpx.Client(base_url="https://api.tauric.ai",
                   headers={"Authorization": f"Bearer {os.environ['TAURIC_API_KEY']}"}, timeout=30)
SERIES = "us.employment.nonfarm_payrolls.sa"


def observations(**params):
    return api.get(f"/v1/series/{SERIES}/observations", params=params).raise_for_status().json()["observations"]


def next_month(date):
    return (date.replace(day=28) + datetime.timedelta(days=4)).replace(day=1)


def first_print(period_start):
    known_at = next_month(datetime.datetime.fromisoformat(period_start).replace(tzinfo=datetime.UTC))
    while True:
        known_at = next_month(known_at)
        earlier, first = observations(limit=2, end=period_start, known_at=known_at.isoformat())
        if first["period"]["start"] == period_start:
            return earlier, first


current = observations(limit=13, end="2026-08-01")
for previous, observation in zip(current, current[1:]):
    earlier, first = first_print(observation["period"]["start"])
    print(f"{observation['period']['label']}  first print {first['value']:>9,.0f}  "
          f"current {observation['value']:>9,.0f}  revision {observation['value'] - first['value']:+7,.0f}  "
          f"change: first print {first['value'] - earlier['value']:+6,.0f}  "
          f"current {observation['value'] - previous['value']:+6,.0f}  {first['evidence']}")

Observations are listed oldest first, each with its period and value. end is compared with each period's start, so end="2026-08-01" makes August 2026 the latest month read. Values are in thousands (the series' unit.multiplier is 1000).

A month's first print is normally released in the next month and first revised in the month after. A known_at at the start of that second month reads the first print. When a release comes late, the month is not there yet, so the script reads a month later.

evidence is source_vintage when the value is the vintage released at that instant. It is recorded when it is the value as recorded then, which can already include a revision. The revision column holds every later revision, including the annual benchmark revision. The first-print monthly change subtracts the prior month's value from the same vintage, not its current value.