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	1 ページあたりのレコード数（デフォルトは 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 値は文字列 "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 のコード例

エージェントの作業手順

1. 環境を確認します。 ネットワーク接続、API キー（必要な場合）、データベースの最新の API ドキュメントとレート制限を確認します。
2. 入力を明確にします。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果を左右する値は推測せず、質問してください。
3. まず小規模に実行します。 既知のレコードを1件取得し、一括クエリの前にレスポンス形式を確認します。
4. 上記の手順と参照資料を使用して、タスク全体を実行します。
5. 結果を検証します。 識別子が解決され、レコード数が報告され、データベースのバージョンまたはアクセス日が記録されていることを確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の事項を明記します。

発生した場合	対応
HTTP 429 または 5xx エラー	バックオフを適用し、リクエストをバッチ処理して、部分的な結果は正直に報告します。
これらの手順にある関数、フラグ、エンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して対応し、ユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧	ユーザーに質問するか、実行前に仮定を明示します。

完全性に関する規則

• 結果、パラメーター、識別子、引用、統計を捏造してはいけません。実行または検証できないことは、明確に伝えてください。
• アクセッション番号、ID、レコードを捏造してはいけません。見つからない場合は「見つかりません」と報告します。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があるものとして扱い、インストール済みバージョンの公式ドキュメントで確認してください。
• 金銭が発生する操作、共有 GPU やクラウドクォータを消費する操作、個人データや患者データを扱う操作、取り消せない操作を行う前に、ユーザーに確認してください。