pull_fred.py

"""Pull the validated FRED series backing the external-indicator sections.

Usage: uv run python pull_fred.py [out_dir]

Every ID below was validated against the live API on 2026-08-02 (title, frequency, units,
observation window confirmed). Do not add a series without a metadata validation first.
PGOLDUSDM and USDA farm real estate values were checked and do not exist in FRED.
"""
import sys

import fred_client

SERIES = [
    "CPIAUCSL",          # M  Index SA 1947+      deflator for every real series
    "ATNHPIUS32007A",    # A  Index 2000=100      FHFA HPI, Elko County NV, 1979-2025
    "NVSTHPI",           # Q  Index 1980Q1=100    FHFA HPI, Nevada, recent-edge cross-check
    "USSTHPI",           # Q  Index 1980Q1=100    FHFA HPI, US, context only
    "MORTGAGE30US",      # W  percent 1971+       financing regime vs land volume
    "USREC",             # M  0/1 1854+           NBER recession shading
    "PCPI32007",         # A  dollars 1969-2024   per capita personal income, Elko County
    "NVELKO7URN",        # M  percent 1990+       unemployment rate, Elko County
    "NVUR",              # M  percent 1976+       unemployment rate, Nevada
    "NVELKO7POP",        # A  thousands 1970-2025 resident population, Elko County
    "ACTLISCOU32007",    # M  count 2016-07+      Realtor.com active listings, Elko County
    "NEWLISCOU32007",    # M  count 2016-07+      Realtor.com new listings
    "TOTLISCOU32007",    # M  count 2016-07+      Realtor.com total listings
    "MEDDAYONMAR32007",  # M  days 2016-07+       Realtor.com median days on market
    "MEDLISPRI32007",    # M  dollars 2016-07+    Realtor.com median listing price
    "PRIREDCOU32007",    # M  count 2016-07+      Realtor.com price-reduced count
]

if __name__ == "__main__":
    out = sys.argv[1] if len(sys.argv) > 1 else "data/fred"
    wide = fred_client.snapshot(SERIES, out, fred_client.load_key())
    print(f"\nwrote {out}: {len(SERIES)} series, wide table {wide.shape[0]:,} rows "
          f"x {wide.shape[1]} cols")