How we count
Good numbers need clear rules. This page explains what The Ledger measures, where the figures come from, and what they don't mean, including why we never blend fiscal years, and why a state's "balance" isn't the same thing as welfare.
The Ledger follows federal money along one path: taxes raised, a budget written into law, dollars spent by agencies, and money returned across the states. Each stage uses its own archived source system. Rankings for states come from a balance-of-payments ledger; Revenue, Congress, and Agencies come from Treasury, IRS, CBO, and USAspending releases. We do not stitch those systems into a single blended total.
Figures are archived locally from .gov releases. Pages do not call live APIs at runtime for the core datasets.
State rankings use New York State Comptroller federal budget balance-of-payments tables, a rare public accounting of what each state pays in and gets back. Available years: 2016 through 2023. FFY 2019–2020 Excel files are posted under OSC’s /budget/2020/excel/ path rather than the usual flat Excel folder. 2024–2025 ledgers aren't out yet.
Each year is built only from that year’s OSC workbook (taxes paid, expenditures, population, and category sheets). Derived ranks and returns are computed inside the selected year, never across years. Archived Excel files are hashed against the live osc.ny.gov downloads via npm run data:check-osc; results appear on Data integrity. A match means the site still reflects the current published workbook for that year. Drift is reviewed before any rebuild. We do not auto-swap archives.
Primary “federal revenue paid” follows OSC’s taxes-paid allocation: individual income taxes, social insurance (payroll) taxes, corporate income taxes, excise taxes, estate and gift taxes, and other federal receipts attributed to the state. Exact allocation rules live in the OSC workbook and accompanying report.
Primary “federal spending received” follows OSC expenditures: direct payments (including Social Security and Medicare), grants (including the federal share of Medicaid), procurement and contracts, federal wages and salaries, and other identified outlays attributed to the state. Spending is not limited to means-tested welfare.
Additional series appear on state pages so you can compare apples-to-oranges sources without confusing the primary ranking:
None of these overlays drive rank, net balance, or return per dollar. Missing same-year supporting files mean the field is omitted for that FFY rather than filled from another year.
National receipt composition comes from the U.S. Treasury Monthly Treasury Statement (MTS Table 9), archived at each fiscal-year end. State-level gross collections for the Revenue “by state” view come from IRS SOI Data Book tables (collection location).
Explore composition, by state, and trends. IRS collection geography is not the same thing as OSC’s taxes-paid allocation used in state rankings.
Budget history and the ten-year baseline come from Congressional Budget Office machine-readable releases (historical budget data and current-law baseline), archived locally. Amounts are typically billions of dollars.
Year drilldowns show CBO’s published categories: revenue sources, discretionary and mandatory outlays, and interest, not program-by-program line items. The budget-flow Sankey can expand Mandatory or Discretionary using those same year tables (mandatory expand omits the overlapping major-health rollup). Each federal fiscal year stays on its own row or page; do not blend FFYs into one unlabeled total. The baseline is current-law projection, not enacted appropriations. See historical, baseline, and breakdown. Refresh when new CBO releases land in the archive pipeline.
The Floor archives a Congress.gov bill inventory for the current and previous Congress (list-level rows in data/issues-inventory.json) plus a Featured Start-here overlay with full detail (summaries, sponsors, committees, CBO estimate links, amendments, pipeline stages, and House/Senate roll calls). Featured is editorial teaching, not an official ranking. Bill data comes from the Congress.gov API (and House Clerk EVS XML when linked). Senate member-level votes are archived from Senate.gov roll-call XML when fetch succeeds; otherwise we link out. Floor-vote visuals color seats by yea / nay / other, with party shown by shape, plus party splits, member lists, and Vice President tie-breaks. A Members index aggregates those votes across Featured bills and joins birthdays and term windows from unitedstates/congress-legislators. Ages and years in office are computed from that file. “Not voting %” is only the share of Featured Ledger roll calls marked not voting; it is not a medical fitness score or an official leave record.
Pipeline positions (introduced → committee → floors → enrolled → President → law/veto) for Featured bills are derived from Congress.gov bill actions. Inventory sync: npm run data:issues:inventory. Featured detail refresh: npm run data:issues (skips complete archives) or npm run data:issues:force. See docs/coverage-contracts.md.
The Gavel tracks argued SCOTUS merits cases across an expanding October Term window (OT 2015 onward in discovery; captions, status, citations, opinion clusters, oral-argument audio links, and justice credits). It is not every filing at the Court, and emergency applications / cert denials are out of v1 scope. Case metadata and opinion text are archived from CourtListener quarterly bulk data (Free Law Project), filtered to the editorial watchlist, with outbound links to official SCOTUS docket pages and opinion/audio files. Search-layer metadata may still come from the CourtListener API. Full concurrence / dissent join lists can still be partial when a cluster has no bulk opinion text. Some dockets have no oral-argument audio.
Rebuild product JSON with npm run data:build-gavel after a bulk ingest (python3 scripts/ingest-gavel-bulk.py). npm run data:gavel still runs discovery plus API search. Optional COURTLISTENER_API_TOKEN raises API rate limits; it is not required for bulk ingest. See docs/gavel-pipeline.md.
The Desk archives presidential administrations as the historical shelf, a Featured Start-here overlay of executive orders, proclamations, and memoranda, and a Federal Register PRESDOCU inventory for modern digital-era admins (Clinton+). It is distinct from The Floor's pipeline stage for bills awaiting a presidential signature. Product JSON merges a static presidency catalog with the unitedstates executive file, NARA library links, FR browse links, Featured watchlist entries, and data/desk-actions-inventory.json.
Action inventory counts target FR PRESDOCU for covered admins; Featured counts are the editorial overlay. Floor signed and vetoed counts credit Featured Floor bills matched by outcome date inside each term window. Age on a sitting presidency is computed from the unitedstates birthday field.
Document titles, numbers, FR/White House links, and term chronology are facts from publishers or the catalog. "Why tracked" on Featured actions is a Ledger editorial note. Inventory rows link out to FR HTML/PDF without scraping full text into the repo.
Pre-Clinton admins keep thinner action lists and NARA links until backfill. Nominations remain deferred; see docs/desk-pipeline.md. Rebuild Featured with npm run data:desk; FR inventory with npm run data:desk-inventory. Optional python3 scripts/build-desk-data.py --with-fr-counts attaches FR counts. Refresh when new official catalogs or FR releases matter; do not invent document totals.
The Race archives federal elections only: President, Senate, and House (including non-voting House delegates when the FEC lists them). It stops before governor, state legislature, and local offices. Product JSON comes from FEC bulk files for even cycles from 1996 through the live cycle: seats by cycle, candidate finance totals (weball for House/Senate; FEC Presidential Table 1/2 summary workbooks preferred for major presidential campaigns when weball undercounts), and top committee/PAC donors (pas2 + committee master) for cycles 2022 and later whenever a campaign has committee credits. Older cycles keep finance totals without that pas2 top-donor layer. Committees that appear in those top lists get donor pages with recipient credits across archived cycles. General-election popular votes come from FEC Federal Elections books (Senate and House, 2004–2022), FEC official 2024 presidential results, MEDSL 2024 Senate state returns, and MEDSL U.S. House constituency returns (Clerk Statistics) for archived House cycles. Senate results before 2004 are not attached yet. Primary popular votes come from FEC 2022 PRIMARY columns and state SOS adapters (Michigan MVIC first). Optional OpenFEC Schedule A hydration can add individual contributors when an API key is set.
The map has two modes. Live shows nationwide Senate and House tallies from civicAPI (attribution required) for the current cycle, for browsing on the map only, not as a public redistribution API for third-party tools. Prefer calling civicAPI directly when you need programmatic live data. Election Night Desk ranks uncalled races by reporting. Archive shows FEC presidential electoral-vote maps (1992–2024) and FEC / Clerk Senate/House winners by cycle; House drill-in uses 118th-Congress district outlines. Live votes are not written into data/race.json. Prefer state secretaries of state for certification; civicAPI race calls are unofficial.
Election cycles stay on separate tabs and rows; do not treat a multi-cycle donor headline as a single-cycle total. Candidate receipts, disbursements, and cash on hand follow the labeled FEC source on the row (PresCand summary tables when present, else weball). Field receipts on explorers sum those candidate receipt figures for the filtered list; committee transfers can double-count, so the sum is not certified cycle fundraising. General-election share uses November votes when a source matched. Primary share is within that party primary field. Top donors are a capped pas2 committee/PAC list, not every itemized Schedule A contributor. Donor "to archive" sums credits across archived cycles on purpose and says so on the page.
Stub or sparse FEC rows appear for some candidates. Not every general-election or primary race has matched votes. Top committee donors are omitted for cycles before 2022 by default. Individual Schedule A hydration is optional and incomplete without an API key. Historical House map drill-in uses 118th-Congress district geometry, which can disagree with older district lines. Rebuild with npm run data:race (no API key). Optional python3 scripts/build-race-data.py --with-donors and FEC_API_KEY from api.data.gov. See docs/race-pipeline.md. Floor members and Desk presidencies link into The Race when a shared FEC candidate id is present. Prefer new FEC / Clerk / MEDSL releases over one-off JSON edits.
Two related views sit under Agencies. Awards use USAspending award obligations by awarding agency (contracts, grants, loans, and related awards). Outlays use Treasury MTS Table 5 net outlays by agency and major account, a broader cash picture that includes benefits and other non-award spending.
Each awarding agency also has a detail page under /agencies/[slug], built from archived USAspending agency overviews (mission, website), latest-FY award categories and sub-agencies, multi-year obligation rollups, and matched MTS outlay lines when names align. Editorial glossary blurbs override mission copy when present; otherwise the USAspending mission text is shown.
Obligations are promises to pay; outlays are cash (or cash-equivalent) payments. They are related, but they are not the same thing in the same year.
Absolute dollars answer how much money moved. Per-capita figures answer how large that flow is relative to population. Return per dollar paid answers how much spending a state received for each dollar of federal revenue attributed to it. The site exposes all three; none alone tells a complete story.
When the federal government runs a deficit, aggregate spending nationally exceeds aggregate revenue. OSC’s FFY 2023 tables therefore show more recipient dollars than contributor dollars in total. Deficit financing is included implicitly whenever spending totals exceed revenue totals for the same year.
FFY 2023 still reflects some pandemic-related grants and other temporary flows in OSC’s expenditure categories. Treat a single year as a snapshot.
Federal spending received includes Social Security, Medicare, Medicaid, military bases and contracts, federal salaries, disaster relief, infrastructure grants, agriculture supports, and many other categories. A high return per dollar often reflects demographics, federal facilities, or procurement, not a moral judgment about residents or parties.
Income levels affect tax payments. Age structure affects Social Security and Medicare. Military bases, contractors, and federal employment concentrate spending. Disaster declarations, farm supports, and healthcare program enrollment also matter. Party affiliation alone does not explain results.
Each state is classified by which presidential candidate won its electoral votes in the most recent presidential election (currently 2024). Labels use non-color text ("Republican presidential vote" and "Democratic presidential vote") alongside any color cues. Classification is stored separately from financial data so either file can be updated independently.
Published state balance-of-payments analyses differ in year covered, treatment of interest on the debt, allocation of defense spending, treatment of territories, and whether figures adjust for taxpayer residency. Compare definitions before comparing headline rankings, and do not equate IRS collection geography or USAspending awards with OSC’s compiled ledger.
Section hubs may show recent headlines on federal spending, taxes, and money returning to states, gathered from Google News RSS and publisher feeds and tagged to Ledger topics. Headlines are not used in rankings.
Official datasets use shorthand most readers should not have to decode. The Ledger maps those labels to readable titles and short explanations in the definitions library, including discretionary vs mandatory spending, obligations vs outlays, and IRS collections vs OSC ranking totals.
For live pass/fail output on the shipped archives across The Books, The Floor, and The Gavel, including formulas, golden pins, the OSC remote source watch, and watchlist sync checks, see Data integrity. To download those archives, use the data cache. That integrity page runs the same validators used when the site loads its archives, so you can confirm what still holds before treating a figure as settled.