usfiscaldata

美国财政部财政数据 API

美国财政部提供的免费开放 REST API，可查询联邦财政数据。无需 API 密钥或注册。

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

通过数据集搜索浏览 54 个数据集和 179 张数据表。请在每个数据集的 API 快速指南中确认端点路径，因为路径会随时间变化。

安装

uv pip install requests pandas

快速开始

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）
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"

重要数据集和端点

债务

数据集	端点	频率
精确到美分的债务数据	/v2/accounting/od/debt_to_penny	每日
历史未偿债务	/v2/accounting/od/debt_outstanding	每年
联邦债务明细表	/v1/accounting/od/schedules_fed_debt	每月

每日和每月报表

数据集	端点	频率
DTS 运营现金余额	/v1/accounting/dts/operating_cash_balance	每日
DTS 存款和取款	/v1/accounting/dts/deposits_withdrawals_operating_cash	每日
月度财政部报表（MTS）	/v1/accounting/mts/mts_table_1（18 张表 — 参见 datasets-fiscal.md）	每月

利率和汇率

数据集	端点	频率
国债平均利率	/v2/accounting/od/avg_interest_rates	每月
财政部报告汇率	/v1/accounting/od/rates_of_exchange	每季度
公共债务利息支出	/v2/accounting/od/interest_expense	每月

证券和拍卖

数据集	端点	频率
国债拍卖数据	/v1/accounting/od/auctions_query	按需
国债即将举行的拍卖	/v1/accounting/od/upcoming_auctions	按需
国债回购	/v1/accounting/od/buybacks_operations	按需

储蓄债券

数据集	端点	频率
I 债券利率	/v1/accounting/od/i_bonds_interest_rates	每半年
储蓄债券发行、赎回和到期	/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

使用 parameters.md 中有边界限制的 fetch_all() 辅助函数。对于较小的结果集，如果 meta.total-pages 为 1，使用 page[size]=10000 进行单次请求可能就足够了。

# Single-page fetch when total-pages == 1
params = {"sort": "-record_date", "page[size]": 10000}
resp = requests.get(f"{BASE_URL}/v2/accounting/od/debt_outstanding", params=params)
result = resp.json()
if result["meta"]["total-pages"] > 1:
    raise ValueError("Use fetch_all() from parameters.md for multi-page results")
df = pd.DataFrame(result["data"])

聚合（自动求和）

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

# 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 代码示例

Agent 操作流程

1. 检查环境。 确认网络访问、API 密钥（如有需要）以及数据库当前的 API 文档和速率限制。
2. 明确输入。 根据数据或用户提供的信息确认格式、标识符和参数。对于任何会影响结果的值，宁可询问，也不要猜测。
3. 先运行小规模测试。 获取一条已知记录，并在批量查询前检查响应格式。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 确认标识符可解析、报告记录数，并记录数据库版本或访问日期。
6. 报告结果。 说明运行了什么（版本、命令、参数）、检查了什么，以及哪些内容仍不确定。

如果发生这种情况	请这样做
出现 HTTP 429 或 5xx 错误	遵守速率限制，采用退避机制、批量请求，并如实报告部分结果。
这些说明中提到的函数、标志或端点在已安装版本中不存在	查阅已安装版本自己的文档（help()、--help、官方文档），调整做法并告知用户。切勿编造 API。
必需的输入、标识符或参数含义不明确	询问用户，或在运行前明确说明所作的假设。

完整性规则

• 切勿伪造结果、参数、标识符、引用或统计数据。若无法运行或验证某项内容，请明确说明。
• 切勿编造 accession 编号、ID 或记录；如果未找到，请报告“未找到”。
• 此处与版本相关的详细信息可能已过时：请根据已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，必须先征得同意。