references/examples.md
Code Examples — U.S. Treasury Fiscal Data
Python queries and transformations below were exercised against the public API on
2026-09-30. First define fetch_all() from parameters.md, then run
the setup. Historic dates are fixed examples, not claims about the current year.
Setup
from datetime import date
from decimal import Decimal
import requests
import pandas as pd
BASE_URL = "https://api.fiscaldata.treasury.gov/services/api/fiscal_service"
def fetch(endpoint, **params):
"""Fetch one page; callers requesting a complete result use fetch_all."""
allowed = {"fields", "filter", "sort", "format", "page[size]", "page[number]"}
if set(params) - allowed:
raise ValueError(f"Unknown query parameters: {set(params) - allowed}")
resp = requests.get(BASE_URL + endpoint, params=params, timeout=30)
resp.raise_for_status()
result = resp.json()
if "error" in result:
raise ValueError(result)
return result
National Debt Tracker
result = fetch("/v2/accounting/od/debt_to_penny",
sort="-record_date", **{"page[size]": 1})
d = result["data"][0]
debt = Decimal(d["tot_pub_debt_out_amt"])
print(f"National debt as of {d['record_date']}: ${debt:,.2f}")
# Complete fixed-period series; cents remain in raw strings if needed.
df = fetch_all("/v2/accounting/od/debt_to_penny", {
"filter": "record_date:gte:2024-01-01,record_date:lte:2024-12-31",
"sort": "record_date", "page[size]": 100,
})
df["date"] = pd.to_datetime(df["record_date"])
df["debt_trillion"] = pd.to_numeric(df["tot_pub_debt_out_amt"]) / 1e12
print(df[["date", "debt_trillion"]].tail())
Treasury Reporting Exchange Rates
endpoint = "/v1/accounting/od/rates_of_exchange"
quarter = fetch(endpoint, sort="-record_date", **{"page[size]": 1})["data"][0]["record_date"]
rates = fetch_all(endpoint, {
"filter": f"record_date:eq:{quarter}",
"sort": "country_currency_desc,effective_date,src_line_nbr",
"page[size]": 100,
})
rates["exchange_rate"] = pd.to_numeric(rates["exchange_rate"])
# Preserve amendments as separate rows; pick the applicable reporting period first.
rates["usd_1000_in_foreign_currency"] = 1000 * rates["exchange_rate"]
print(rates[["country_currency_desc", "record_date", "effective_date",
"exchange_rate", "usd_1000_in_foreign_currency"]].head())
These are foreign-currency units per USD. Divide a foreign amount by its applicable
rate to obtain USD. Amendments have later effective_date values; quarterly PDF
reports omit amendments, so do not collapse rows without the official period rules.
Treasury Securities Auction Analysis
# Nominal fixed-rate 10-year notes. auction_date dates the event.
result = fetch("/v1/accounting/od/auctions_query",
filter="security_type:eq:Note,original_security_term:eq:10-Year,inflation_index_security:eq:No,floating_rate:eq:No",
sort="-auction_date,cusip", **{"page[size]": 20})
auctions = pd.DataFrame(result["data"])
for col in ["high_yield", "bid_to_cover_ratio", "total_accepted", "indirect_bidder_accepted"]:
auctions[col] = pd.to_numeric(auctions[col].replace("null", None), errors="coerce")
auctions["indirect_pct_of_total"] = (
100 * auctions["indirect_bidder_accepted"] / auctions["total_accepted"].where(auctions["total_accepted"] > 0)
)
print(auctions[["auction_date", "cusip", "security_term", "reopening",
"high_yield", "indirect_pct_of_total"]].head())
original_security_term includes reopened securities whose remaining
security_term is shorter. Name the denominator when reporting bidder shares;
total_accepted is not the same as competitive awards. Missing yields can mean an
auction has been announced but results are unavailable. Auction yields observed on
different dates do not form a same-date yield curve; do not inner-join 2-year and
10-year auctions on publication dates and label the difference a market spread.
Daily Treasury Statement
endpoint = "/v1/accounting/dts/operating_cash_balance"
closing = fetch(endpoint,
filter="account_type:eq:Treasury General Account (TGA) Closing Balance",
sort="-record_date", **{"page[size]": 5})
for row in closing["data"]:
print(row["record_date"], Decimal(row["open_today_bal"]), "million USD, closing TGA")
# Named totals avoid adding category detail to summary rows.
cash = fetch_all(endpoint, {
"filter": "record_date:gte:2024-01-01,record_date:lte:2024-01-31",
"sort": "record_date,src_line_nbr",
})
cash = cash[cash["account_type"].isin([
"Total TGA Deposits (Table II)", "Total TGA Withdrawals (Table II) (-)",
])].copy()
cash["million_usd"] = pd.to_numeric(cash["open_today_bal"])
print(cash.pivot(index="record_date", columns="account_type", values="million_usd"))
Since April 18, 2022, close_today_bal is null. The closing-balance account row
stores its value in open_today_bal. Earlier layouts need separate handling.
DTS cash movements include financing and differ from MTS budget receipts/outlays.
Monthly Budget Summary
budget = fetch_all("/v1/accounting/mts/mts_receipts_outlays_deficit_surplus", {
"filter": "record_fiscal_year:eq:2024",
"sort": "record_date,src_line_nbr",
})
budget = budget[budget["amt_category"].isin(["Receipts", "Outlays", "Deficit/Surplus (-)"])].copy()
budget["million_usd"] = pd.to_numeric(budget["mil_amt"])
monthly = budget.pivot(index="record_date", columns="amt_category", values="million_usd")
assert len(monthly) == 12, "Fiscal year is incomplete"
# Published values are rounded to millions; allow rounding differences.
residual = monthly["Outlays"] - monthly["Receipts"] - monthly["Deficit/Surplus (-)"]
if (residual.abs() > 1).any():
print("[WARN] Reconcile source revisions/footnotes before using these months:")
print(residual[residual.abs() > 1])
print(monthly)
The live FY2024 extract on the review date had a March 2024 reconciliation residual of -270 million USD, beyond rounding. This example exposes that source discrepancy; it does not treat the series as reconciled or overwrite the published values. Check the matching report/revisions before drawing budget conclusions.
This summary has explicit million-dollar units. Tables 1 and 9 have different fields and dollar-scale API values; Table 1 repeats prior months and fiscal-year sections in each publication. Never add all Table 1 rows to obtain monthly totals.
Average Treasury and I Bond Rates
rates = fetch_all("/v2/accounting/od/avg_interest_rates", {
"filter": "security_type_desc:eq:Marketable,record_date:gte:2024-01-01,record_date:lte:2024-12-31",
"sort": "record_date,src_line_nbr",
})
rates["rate_pct"] = pd.to_numeric(rates["avg_interest_rate_amt"])
print(rates.pivot(index="record_date", columns="security_desc", values="rate_pct"))
# One issue vintage and a fixed earning-period cutoff, not a universal I Bond rate.
issue_month = "2024-05"
bonds = fetch("/v1/accounting/od/i_bonds_interest_rates",
filter=f"issue_year_month:eq:{issue_month},earning_period_start:lte:2024-11-01",
sort="-earning_period_start", **{"page[size]": 1})
print(pd.DataFrame(bonds["data"])[["issue_year_month", "earning_period_start",
"earning_period_end", "fixed_rate", "combined_rate"]])
Average interest rates describe the outstanding debt portfolio, not current market yields. I Bond fixed rates depend on issue vintage; the earning-period columns and issue month must be retained together.
Completed Fiscal-Year Interest Expense
fy = 2024
expenses = fetch_all("/v2/accounting/od/interest_expense", {
"filter": f"record_fiscal_year:eq:{fy}",
"sort": "record_date,src_line_nbr",
})
assert expenses["record_date"].nunique() == 12, "Fiscal year is incomplete"
assert expenses["record_date"].max() == f"{fy}-09-30"
assert not expenses.duplicated(["record_date", "src_line_nbr"]).any()
monthly_total = sum(Decimal(x) for x in expenses["month_expense_amt"])
september = expenses[expenses["record_date"] == f"{fy}-09-30"]
fytd_total = sum(Decimal(x) for x in september["fytd_expense_amt"])
assert abs(monthly_total - fytd_total) <= Decimal("0.01"), "Reconcile revisions/components"
print(f"FY{fy} public-debt interest expense: ${fytd_total:,.2f}")
This uses the expense dataset's components and accounting basis, not budget net interest. Sum monthly flows once, or take September FYTD once; never sum FYTD values across months. Preserve category/group/type fields to inspect components.
R example (illustrative; R runtime not exercised)
library(httr)
library(jsonlite)
base <- "https://api.fiscaldata.treasury.gov/services/api/fiscal_service"
response <- GET(paste0(base, "/v1/accounting/mts/mts_table_9"),
query = list(filter = "line_code_nbr:eq:120",
sort = "-record_date", `page[size]` = 1),
timeout(30))
stop_for_status(response)
result <- fromJSON(rawToChar(response$content))
stopifnot(nrow(result$data) == 1)
print(result$data[c("record_date", "classification_desc", "current_month_rcpt_outly_amt")])
Discovering fields and datasets
result = fetch("/v2/accounting/od/debt_to_penny", **{"page[size]": 1})
for field, label in result["meta"]["labels"].items():
print(field, result["meta"]["dataTypes"][field], label)
Use the dataset catalog and each API Quick Guide/data dictionary for current paths, table coverage, units and limitations. The API guide documents common filters, pagination and response metadata.