alterlab-usfiscaldata

美国财政部 Fiscal Data API

美国财政部提供的免费开放 REST API，用于获取联邦财政数据。无需 API 密钥或注册。

基础 URL： https://api.fiscaldata.treasury.gov/services/api/fiscal_service

截至 2026-09-23，目录包含 56 个数据集 / 183 张数据表；请访问 https://fiscaldata.treasury.gov/datasets/ 查看当前列表及各表的端点版本（v1 或 v2）。

何时使用此技能

• 联邦债务（Debt to the Penny、历史未偿债务、联邦债务明细表）
• Daily and Monthly Treasury Statements：运营现金余额、存款 / 提款、收入、支出、赤字
• 国债拍卖（结果和即将举行的拍卖）、平均利率、利息支出
• 财政部报告汇率、储蓄债券、I 债券利率

不适用的情况

场景	改用
市场收益率（DGS10）、联邦基金利率，或通过 FRED ID 获取并转换宏观经济序列	alterlab-fred
来自商业数据源的市场报价或每日外汇 / 加密货币价格	alterlab-alpha-vantage
对冲基金杠杆或回购市场汇总数据（Form PF、FICC）	alterlab-hedgefund-monitor
SEC EDGAR 上的公司申报文件和财务报表	alterlab-edgartools

快速入门

import requests
import pandas as pd

BASE_URL = "https://api.fiscaldata.treasury.gov/services/api/fiscal_service"

# Get the current national debt (Debt to the Penny)
resp = requests.get(f"{BASE_URL}/v2/accounting/od/debt_to_penny", params={
    "sort": "-record_date",
    "page[size]": 1
})
data = resp.json()["data"][0]
print(f"Total public debt as of {data['record_date']}: ${float(data['tot_pub_debt_out_amt']):,.0f}")

# Get Treasury exchange rates for recent quarters
resp = requests.get(f"{BASE_URL}/v1/accounting/od/rates_of_exchange", params={
    "fields": "country_currency_desc,exchange_rate,record_date",
    "filter": "record_date:gte:2024-01-01",
    "sort": "-record_date",
    "page[size]": 100
})
df = pd.DataFrame(resp.json()["data"])

身份验证

无需身份验证。此 API 完全开放且免费。

核心参数

参数	示例	说明
fields=	fields=record_date,tot_pub_debt_out_amt	选择特定列
filter=	filter=record_date:gte:2024-01-01	筛选记录
sort=	sort=-record_date	排序（添加前缀 - 表示降序）
format=	format=json	输出格式：json、csv、xml
page[size]=	page[size]=100	每页记录数（默认 100，最多 10000）
page[number]=	page[number]=2	页码（从 1 开始）

筛选运算符： lt、lte、gt、gte、eq、in

# Multiple filters separated by comma
"filter=country_currency_desc:in:(Canada-Dollar,Mexico-Peso),record_date:gte:2024-01-01"

主要数据集和端点

债务

数据集	端点	频率
Debt to the Penny	/v2/accounting/od/debt_to_penny	每日
Historical Debt Outstanding	/v2/accounting/od/debt_outstanding	每年
Schedules of Federal Debt	/v1/accounting/od/schedules_fed_debt	每月

每日和每月报表

数据集	端点	频率
DTS Operating Cash Balance	/v1/accounting/dts/operating_cash_balance	每日
DTS Deposits & Withdrawals	/v1/accounting/dts/deposits_withdrawals_operating_cash	每日
Monthly Treasury Statement (MTS)	/v1/accounting/mts/mts_table_1（共 16 张表）	每月

利率和汇率

数据集	端点	频率
Average Interest Rates on Treasury Securities	/v2/accounting/od/avg_interest_rates	每月
Treasury Reporting Rates of Exchange	/v1/accounting/od/rates_of_exchange	每季度
Interest Expense on Public Debt	/v2/accounting/od/interest_expense	每月

证券和拍卖

数据集	端点	频率
Treasury Securities Auctions Data	/v1/accounting/od/auctions_query	按需
Treasury Securities Upcoming Auctions	/v1/accounting/od/upcoming_auctions	按需
Average Interest Rates	/v2/accounting/od/avg_interest_rates	每月

储蓄债券

数据集	端点	频率
I Bonds Interest Rates	/v1/accounting/od/i_bonds_interest_rates	每半年
U.S. Treasury Savings Bonds: Issues, Redemptions & Maturities	/v1/accounting/od/savings_bonds_report	每月

响应结构

{
  "data": [...],
  "meta": {
    "count": 100,
    "total-count": 3790,
    "total-pages": 38,
    "labels": {"field_name": "Human Readable Label"},
    "dataTypes": {"field_name": "STRING|NUMBER|DATE|CURRENCY"},
    "dataFormats": {"field_name": "String|10.2|YYYY-MM-DD"}
  },
  "links": {"self": "...", "first": "...", "prev": null, "next": "...", "last": "..."}
}

注意： 所有值都以字符串形式返回。请根据需要进行转换（例如，float()、pd.to_datetime()）。空值以字符串 "null" 表示。

常见模式

将所有分页数据载入 DataFrame

def fetch_all_pages(endpoint, params=None):
    params = dict(params or {})
    params["page[size]"] = 10000  # the API maximum; larger values return HTTP 400
    params["page[number]"] = 1
    rows = []
    while True:
        resp = requests.get(f"{BASE_URL}{endpoint}", params=params, timeout=60)
        resp.raise_for_status()
        result = resp.json()
        rows.extend(result["data"])
        if params["page[number]"] >= result["meta"]["total-pages"]:
            break
        params["page[number]"] += 1
    return pd.DataFrame(rows)

聚合（自动求和）

省略分组字段会触发自动聚合：

# Sum all deposits/withdrawals by record_date and transaction type
resp = requests.get(f"{BASE_URL}/v1/accounting/dts/deposits_withdrawals_operating_cash", params={
    "fields": "record_date,transaction_type,transaction_today_amt"
})

参考文件

• api-basics.md — URL 结构、HTTP 方法、版本控制、数据类型
• parameters.md — 所有参数的详细示例和边界情况
• datasets-debt.md — 债务数据集：Debt to the Penny、Historical Debt、Schedules of Federal Debt、TROR
• datasets-fiscal.md — Daily Treasury Statement、Monthly Treasury Statement、收入、支出
• datasets-interest-rates.md — 平均利率、汇率、TIPS/CPI、认证利率
• datasets-securities.md — 国债拍卖、储蓄债券、SLGS、回购
• response-format.md — 响应对象、错误处理、分页、响应代码
• examples.md — 常见用例的 Python、R 和 pandas 代码示例

引用数据集名称、表格和检索日期（Fiscal Data 的值可能会修订；请保留你所用的 record_date）。

属于 AlterLab Academic Skills 套件。