用途
usfiscaldata 用于查询美国财政部 Fiscal Data REST API，获取联邦财政数据。该 API 由美国财政部提供，免费、开放，无需 API 密钥或注册。
基础 URL：https://api.fiscaldata.treasury.gov/services/api/fiscal_service
可通过数据集搜索浏览 54 个数据集和 179 张数据表。建议在每个数据集的 API Quick Guide 中核实端点路径，因为路径可能随时间变化。
主要能力
技能覆盖以下数据集类别：
- 债务：Debt to the Penny（每日）、Historical Debt Outstanding（年度）、Schedules of Federal Debt（月度）。
- 每日与每月报表：DTS Operating Cash Balance（每日）、DTS Deposits & Withdrawals（每日）、Monthly Treasury Statement（月度，含 18 张表）。
- 利率与汇率：Average Interest Rates on Treasury Securities（月度）、Treasury Reporting Rates of Exchange（季度）、Interest Expense on Public Debt（月度）。
- 证券与拍卖：Treasury Securities Auctions Data、Treasury Securities Upcoming Auctions、Treasury Securities Buybacks。
- 储蓄债券：I Bonds Interest Rates（半年度）、Savings Bonds Issues, Redemptions & Maturities（月度）。
使用方式
安装依赖：
uv pip install requests pandas
快速开始示例（获取当前国债）：
import requests import pandas as pd
BASE_URL = "https://api.fiscaldata.treasury.gov/services/api/fiscal_service"
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}")
获取近期季度汇率示例：
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=：输出格式，json、csv、xml
- page[size]=：每页记录数，默认 100
- page[number]=：页码，从 1 开始
过滤运算符：lt、lte、gt、gte、eq、in。多个过滤器用逗号分隔，例如：
filter=country_currency_desc:in:(Canada-Dollar,Mexico-Peso),record_date:gte:2024-01-01
响应结构包含 data、meta、links。meta 中包含 count、total-count、total-pages、labels、dataTypes、dataFormats。注意：所有值均以字符串返回，需要时自行转换（如 float()、pd.to_datetime()）；空值表现为字符串 "null"。
常用模式：
- 将全部分页加载到 DataFrame：使用 parameters.md 中有界的 fetch_all() 辅助函数。对于小结果集，当 meta.total-pages 为 1 时，单次请求 page[size]=10000 可能足够。
- 聚合（自动求和）：省略分组字段会触发自动聚合。
参考文件包括：api-basics.md、parameters.md、datasets-debt.md、datasets-fiscal.md、datasets-interest-rates.md、datasets-securities.md、response-format.md、examples.md。
适用场景
适用于需要获取和分析美国联邦财政公开数据的任务，例如查询国债规模、财政收支、利率汇率、国债拍卖与储蓄债券信息等。
限制
- 所有值以字符串返回，需自行转换类型。
- 空值表现为字符串 "null"。
- 端点路径可能随时间变化，需核实各数据集 API Quick Guide。
- 遇到 HTTP 429 或 5xx 错误时，应遵守速率限制并退避重试，如实报告部分结果。
- 若指令中的函数、标志或端点在已安装版本中缺失，应查阅已安装版本的文档并告知用户，不得虚构 API。
- 不得编造结果、参数、标识符、引用或统计数据；无法运行或验证时应明确说明。
- 涉及费用、共享 GPU 或云配额、个人或患者数据、不可撤销操作时，应先询问。