data-analyst-mcp 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +286 -262
- package/dist/adapters/bjs.d.ts +13 -0
- package/dist/adapters/bjs.js +28 -0
- package/dist/adapters/bjs.js.map +1 -0
- package/dist/adapters/cbp.d.ts +5 -0
- package/dist/adapters/cbp.js +64 -0
- package/dist/adapters/cbp.js.map +1 -0
- package/dist/adapters/cdc-wonder.d.ts +5 -0
- package/dist/adapters/cdc-wonder.js +68 -0
- package/dist/adapters/cdc-wonder.js.map +1 -0
- package/dist/adapters/cpsc.d.ts +4 -0
- package/dist/adapters/cpsc.js +125 -0
- package/dist/adapters/cpsc.js.map +1 -0
- package/dist/adapters/fhwa.d.ts +9 -0
- package/dist/adapters/fhwa.js +16 -0
- package/dist/adapters/fhwa.js.map +1 -0
- package/dist/adapters/foreign-assistance.d.ts +9 -0
- package/dist/adapters/foreign-assistance.js +42 -0
- package/dist/adapters/foreign-assistance.js.map +1 -0
- package/dist/adapters/hud-ahar.d.ts +3 -0
- package/dist/adapters/hud-ahar.js +80 -0
- package/dist/adapters/hud-ahar.js.map +1 -0
- package/dist/adapters/nces.d.ts +10 -0
- package/dist/adapters/nces.js +32 -0
- package/dist/adapters/nces.js.map +1 -0
- package/dist/adapters/nsf.d.ts +11 -0
- package/dist/adapters/nsf.js +25 -0
- package/dist/adapters/nsf.js.map +1 -0
- package/dist/adapters/onrr.d.ts +9 -0
- package/dist/adapters/onrr.js +35 -0
- package/dist/adapters/onrr.js.map +1 -0
- package/dist/adapters/sba.d.ts +10 -0
- package/dist/adapters/sba.js +134 -0
- package/dist/adapters/sba.js.map +1 -0
- package/dist/adapters/treasury-tic.d.ts +30 -0
- package/dist/adapters/treasury-tic.js +149 -0
- package/dist/adapters/treasury-tic.js.map +1 -0
- package/dist/adapters/uscourts.d.ts +8 -0
- package/dist/adapters/uscourts.js +8 -0
- package/dist/adapters/uscourts.js.map +1 -0
- package/dist/analysis/cite.d.ts +9 -1
- package/dist/analysis/cite.js +9 -2
- package/dist/analysis/cite.js.map +1 -1
- package/dist/bin/cli.d.ts +2 -0
- package/dist/bin/cli.js +17 -0
- package/dist/bin/cli.js.map +1 -1
- package/dist/core/generic-rest.js +42 -17
- package/dist/core/generic-rest.js.map +1 -1
- package/dist/core/guard.d.ts +32 -0
- package/dist/core/guard.js +176 -0
- package/dist/core/guard.js.map +1 -0
- package/dist/core/http.d.ts +10 -0
- package/dist/core/http.js +36 -7
- package/dist/core/http.js.map +1 -1
- package/dist/core/keys.d.ts +13 -3
- package/dist/core/keys.js +67 -7
- package/dist/core/keys.js.map +1 -1
- package/dist/core/package.d.ts +12 -3
- package/dist/core/package.js +56 -12
- package/dist/core/package.js.map +1 -1
- package/dist/core/secret_patterns.d.ts +6 -0
- package/dist/core/secret_patterns.js +20 -0
- package/dist/core/secret_patterns.js.map +1 -0
- package/dist/core/tabular.d.ts +43 -1
- package/dist/core/tabular.js +149 -6
- package/dist/core/tabular.js.map +1 -1
- package/dist/envelope.js +3 -1
- package/dist/envelope.js.map +1 -1
- package/dist/index.d.ts +29 -22
- package/dist/index.js +45 -46
- package/dist/index.js.map +1 -1
- package/dist/remote/app.js +87 -31
- package/dist/remote/app.js.map +1 -1
- package/dist/remote/oauth.js +8 -1
- package/dist/remote/oauth.js.map +1 -1
- package/dist/remote/pages.d.ts +3 -7
- package/dist/remote/pages.js +49 -19
- package/dist/remote/pages.js.map +1 -1
- package/dist/remote/sign.d.ts +7 -1
- package/dist/remote/sign.js +33 -7
- package/dist/remote/sign.js.map +1 -1
- package/dist/remote/store.js +14 -5
- package/dist/remote/store.js.map +1 -1
- package/dist/report/audit_report.js +29 -7
- package/dist/report/audit_report.js.map +1 -1
- package/dist/report/build_report.js +34 -4
- package/dist/report/build_report.js.map +1 -1
- package/dist/report/method_audit.js +10 -1
- package/dist/report/method_audit.js.map +1 -1
- package/dist/report/scan_secrets.d.ts +4 -1
- package/dist/report/scan_secrets.js +38 -18
- package/dist/report/scan_secrets.js.map +1 -1
- package/dist/server.d.ts +3 -1
- package/dist/server.js +46 -13
- package/dist/server.js.map +1 -1
- package/dist/tools.js +27 -6
- package/dist/tools.js.map +1 -1
- package/guide/WORKFLOW.md +134 -134
- package/guide/assets/disclaimer.txt +1 -1
- package/guide/assets/download_data.ps1 +164 -162
- package/guide/assets/download_data.sh +8 -2
- package/guide/assets/report_template.html +597 -597
- package/guide/references/routing.md +198 -171
- package/guide/references/style_guide.md +398 -398
- package/package.json +56 -56
- package/packs/acf/endpoints.json +114 -114
- package/packs/acf/policy.json +104 -104
- package/packs/actuaries/endpoints.json +82 -82
- package/packs/actuaries/policy.json +109 -109
- package/packs/bea/assets/download_bea.ps1 +182 -182
- package/packs/bea/docs/bea_api.md +461 -461
- package/packs/bea/docs/datasets.md +157 -157
- package/packs/bea/docs/report_patterns.md +112 -112
- package/packs/bea/policy.json +170 -170
- package/packs/bea/source.md +152 -152
- package/packs/bjs/endpoints.json +150 -0
- package/packs/bjs/policy.json +114 -0
- package/packs/bjs/source.md +98 -0
- package/packs/bls/assets/download_bls.ps1 +152 -152
- package/packs/bls/docs/analysis_patterns.md +108 -108
- package/packs/bls/docs/bls_api.md +73 -73
- package/packs/bls/docs/series_ids.md +149 -149
- package/packs/bls/policy.json +238 -238
- package/packs/bts/endpoints.json +346 -346
- package/packs/bts/policy.json +94 -94
- package/packs/cbp/endpoints.json +31 -0
- package/packs/cbp/policy.json +85 -0
- package/packs/cbp/source.md +57 -0
- package/packs/cdc/endpoints.json +197 -197
- package/packs/cdc/policy.json +83 -83
- package/packs/cdc/source.md +1 -1
- package/packs/cdc-wonder/endpoints.json +26 -0
- package/packs/cdc-wonder/policy.json +84 -0
- package/packs/cdc-wonder/source.md +53 -0
- package/packs/census/endpoints.json +99 -99
- package/packs/cfpb/endpoints.json +326 -326
- package/packs/cfpb/policy.json +119 -119
- package/packs/clinical-trials/endpoints.json +166 -166
- package/packs/clinical-trials/policy.json +84 -84
- package/packs/cms/endpoints.json +69 -69
- package/packs/cms/policy.json +96 -96
- package/packs/college-scorecard/endpoints.json +252 -252
- package/packs/college-scorecard/policy.json +106 -106
- package/packs/college-scorecard/source.md +1 -1
- package/packs/congress/endpoints.json +1701 -1701
- package/packs/congress/policy.json +117 -117
- package/packs/cpsc/endpoints.json +91 -0
- package/packs/cpsc/policy.json +91 -0
- package/packs/cpsc/source.md +76 -0
- package/packs/dhs-ohss/endpoints.json +66 -66
- package/packs/dhs-ohss/policy.json +107 -107
- package/packs/dhs-ohss/source.md +1 -1
- package/packs/doj-news/endpoints.json +59 -59
- package/packs/doj-news/policy.json +96 -96
- package/packs/doj-news/source.md +1 -1
- package/packs/dol/endpoints.json +817 -817
- package/packs/dol/policy.json +135 -135
- package/packs/eia/endpoints.json +717 -717
- package/packs/eia/policy.json +112 -112
- package/packs/epa/endpoints.json +291 -291
- package/packs/epa/policy.json +99 -99
- package/packs/epa-aqs/endpoints.json +173 -173
- package/packs/epa-aqs/policy.json +96 -96
- package/packs/fbi/endpoints.json +1841 -1841
- package/packs/fbi/policy.json +118 -118
- package/packs/fbi/source.md +3 -3
- package/packs/fda/endpoints.json +237 -237
- package/packs/fda/policy.json +121 -121
- package/packs/fdic/endpoints.json +416 -416
- package/packs/fdic/policy.json +83 -83
- package/packs/fec/endpoints.json +707 -707
- package/packs/fec/policy.json +93 -93
- package/packs/fed-board/endpoints.json +89 -89
- package/packs/fed-board/policy.json +136 -136
- package/packs/federal-register/endpoints.json +143 -143
- package/packs/federal-register/policy.json +86 -86
- package/packs/fema/endpoints.json +645 -645
- package/packs/fema/policy.json +103 -103
- package/packs/fhfa/endpoints.json +105 -105
- package/packs/fhfa/policy.json +109 -109
- package/packs/fhwa/endpoints.json +48 -0
- package/packs/fhwa/policy.json +91 -0
- package/packs/fhwa/source.md +59 -0
- package/packs/foreign-assistance/endpoints.json +166 -0
- package/packs/foreign-assistance/policy.json +80 -0
- package/packs/foreign-assistance/source.md +76 -0
- package/packs/fred/assets/download_fred.ps1 +122 -122
- package/packs/fred/docs/analysis_patterns.md +124 -124
- package/packs/fred/docs/fred_api.md +94 -94
- package/packs/fred/docs/series.md +188 -188
- package/packs/fred/policy.json +253 -253
- package/packs/fsa/endpoints.json +150 -150
- package/packs/fsa/policy.json +99 -99
- package/packs/fsa/source.md +1 -1
- package/packs/govinfo/endpoints.json +519 -519
- package/packs/gsa-calc/endpoints.json +93 -93
- package/packs/gsa-calc/policy.json +97 -97
- package/packs/hud/endpoints.json +146 -146
- package/packs/hud/policy.json +84 -84
- package/packs/hud/source.md +1 -1
- package/packs/hud-ahar/endpoints.json +92 -0
- package/packs/hud-ahar/policy.json +88 -0
- package/packs/hud-ahar/source.md +72 -0
- package/packs/ipums/docs/report_patterns.md +117 -117
- package/packs/irs-soi/endpoints.json +114 -114
- package/packs/irs-soi/policy.json +107 -107
- package/packs/medicaid/endpoints.json +412 -412
- package/packs/medicaid/policy.json +108 -108
- package/packs/naep/endpoints.json +217 -217
- package/packs/naep/policy.json +100 -100
- package/packs/naep/source.md +1 -1
- package/packs/nces/endpoints.json +101 -0
- package/packs/nces/policy.json +99 -0
- package/packs/nces/source.md +75 -0
- package/packs/nhtsa/endpoints.json +132 -132
- package/packs/nhtsa/policy.json +93 -93
- package/packs/nhtsa/source.md +1 -1
- package/packs/nih/endpoints.json +452 -452
- package/packs/nih/policy.json +86 -86
- package/packs/noaa/endpoints.json +431 -431
- package/packs/noaa/policy.json +95 -95
- package/packs/nrel/endpoints.json +327 -327
- package/packs/nrel/policy.json +96 -96
- package/packs/nsf/endpoints.json +33 -0
- package/packs/nsf/policy.json +83 -0
- package/packs/nsf/source.md +59 -0
- package/packs/nws/endpoints.json +271 -271
- package/packs/nws/policy.json +82 -82
- package/packs/nyfed/endpoints.json +80 -80
- package/packs/nyfed/policy.json +92 -92
- package/packs/omb/endpoints.json +460 -460
- package/packs/omb/policy.json +106 -106
- package/packs/onrr/endpoints.json +198 -0
- package/packs/onrr/policy.json +91 -0
- package/packs/onrr/source.md +55 -0
- package/packs/open-payments/endpoints.json +297 -297
- package/packs/open-payments/policy.json +101 -101
- package/packs/opm/assets/download_opm.ps1 +125 -125
- package/packs/opm/docs/fields.md +184 -184
- package/packs/opm/docs/opm_api.md +71 -71
- package/packs/opm/docs/report_patterns.md +83 -83
- package/packs/opm/lib/data_dictionary.csv +73 -73
- package/packs/pbgc/endpoints.json +483 -483
- package/packs/pbgc/policy.json +94 -94
- package/packs/philfed/endpoints.json +85 -85
- package/packs/philfed/policy.json +94 -94
- package/packs/port.json +65 -0
- package/packs/regulations/endpoints.json +287 -287
- package/packs/regulations/policy.json +86 -86
- package/packs/sba/endpoints.json +34 -0
- package/packs/sba/policy.json +86 -0
- package/packs/sba/source.md +60 -0
- package/packs/sec/endpoints.json +236 -236
- package/packs/sec/policy.json +86 -86
- package/packs/senate-lobbying/endpoints.json +553 -553
- package/packs/senate-lobbying/policy.json +99 -99
- package/packs/snapqc/endpoints.json +1426 -1426
- package/packs/snapqc/policy.json +92 -92
- package/packs/treasury/catalog.json +2267 -2267
- package/packs/treasury/docs/api_guide.md +245 -245
- package/packs/treasury/docs/datasets.md +56 -56
- package/packs/treasury/docs/report_patterns.md +126 -126
- package/packs/treasury/policy.json +159 -159
- package/packs/treasury/source.md +170 -165
- package/packs/treasury-tic/endpoints.json +77 -0
- package/packs/treasury-tic/policy.json +89 -0
- package/packs/treasury-tic/source.md +80 -0
- package/packs/treasury-yields/endpoints.json +226 -226
- package/packs/treasury-yields/policy.json +86 -86
- package/packs/usaspending/endpoints.json +1315 -1315
- package/packs/usaspending/policy.json +109 -109
- package/packs/uscourts/endpoints.json +22 -0
- package/packs/uscourts/policy.json +87 -0
- package/packs/uscourts/source.md +56 -0
- package/packs/usda-fna/policy.json +133 -133
- package/packs/usda-fooddata/endpoints.json +180 -180
- package/packs/usda-fooddata/policy.json +94 -94
- package/packs/usda-nass/endpoints.json +323 -323
- package/packs/usda-nass/policy.json +95 -95
- package/packs/usda-outlook/endpoints.json +86 -86
- package/packs/usda-outlook/policy.json +109 -109
- package/packs/usgs/endpoints.json +313 -313
- package/packs/usgs/policy.json +95 -95
- package/packs/usitc/endpoints.json +74 -74
- package/packs/usitc/policy.json +111 -111
- package/packs/uspto/endpoints.json +141 -141
- package/packs/uspto/policy.json +95 -95
- package/packs/uspto/source.md +1 -1
- package/packs/va/endpoints.json +414 -414
- package/packs/va/policy.json +101 -101
- package/packs/world-bank/endpoints.json +122 -122
- package/packs/world-bank/policy.json +101 -101
package/packs/treasury/source.md
CHANGED
|
@@ -1,165 +1,170 @@
|
|
|
1
|
-
# U.S. Treasury Fiscal Data (fiscaldata.treasury.gov)
|
|
2
|
-
Depth: deep. Key: none. Official federal finance statistics from the Bureau of the Fiscal Service: debt,
|
|
3
|
-
deficits, receipts and outlays (Monthly Treasury Statement), Treasury cash (Daily Treasury Statement),
|
|
4
|
-
interest expense and average rates on the debt, the debt limit, auctions, exchange rates; 185 endpoints.
|
|
5
|
-
|
|
6
|
-
## When to use
|
|
7
|
-
- National debt (total, held by the public, intragovernmental; daily since 1993, yearly since 1790), debt by
|
|
8
|
-
security type, debt subject to the limit; monthly and fiscal-year receipts, outlays and deficits; receipts
|
|
9
|
-
by source, outlays by function and by agency; gross interest expense, net interest, average interest rates
|
|
10
|
-
on outstanding debt; the TGA cash balance and daily deposits and withdrawals; auction results; exchange
|
|
11
|
-
rates for federal reporting; gifts to reduce the debt; savings bonds; buybacks.
|
|
12
|
-
- Not here: market yields and the daily par yield curve (treasury-yields); GDP and CPI (bea, bls, fred; or
|
|
13
|
-
the spec's `context` field here, for real dollars and "% of GDP"); budget projections (CBO); historical tables in
|
|
14
|
-
% of GDP and the President's budget (OMB); who holds the debt by country (
|
|
15
|
-
state and local finances (Census).
|
|
16
|
-
- Deliver data plus a short answer by default; a report only when asked (see `guide`).
|
|
17
|
-
|
|
18
|
-
## Endpoints and datasets
|
|
19
|
-
Base `https://api.fiscaldata.treasury.gov/services/api/fiscal_service/` + a path with a fixed version (v1 or
|
|
20
|
-
v2: the other returns 404). `request_schema` with `search: "interest expense"` searches the live catalog
|
|
21
|
-
(falls back to the bundled `catalog.json`: a snapshot of the live catalog plus this guidance); `search:
|
|
22
|
-
"<endpoint>"` gives fields, types, units, row count, first and last row; `search: "<endpoint> {"record_date":
|
|
23
|
-
"2026-09-30"} values"` shows which values each code and description column holds; `request_schema` with
|
|
24
|
-
`names: ["dataset"]` lists the curated rows below. Full question-to-endpoint table: `docs/datasets.md`; API rules,
|
|
25
|
-
field meanings and the numbered gotchas: `docs/api_guide.md`; framing and conventions: `docs/report_patterns.md`.
|
|
26
|
-
|
|
27
|
-
| Question | Endpoint | Rows to use | Stock/flow | Units |
|
|
28
|
-
|---|---|---|---|---|
|
|
29
|
-
| Total debt, held by the public, intragovernmental (daily) | `v2/accounting/od/debt_to_penny` | one row per business day | stock | $ |
|
|
30
|
-
| Debt at fiscal year end since 1790 | `v2/accounting/od/debt_outstanding` | one row per year | stock | $ |
|
|
31
|
-
| Debt by security type (monthly) | `v1/debt/mspd/mspd_table_1` | `security_type_desc`, `security_class_desc`; skip "Total" rows | stock | $M |
|
|
32
|
-
| Debt subject to the limit | `v1/debt/mspd/mspd_table_2`, `v1/accounting/dts/debt_subject_to_limit` | `debt_catg_desc` | stock | $M |
|
|
33
|
-
| Monthly receipts, outlays, deficit since FY1981 | `v1/accounting/mts/mts_receipts_outlays_deficit_surplus` | `amt_category` | flow | $M |
|
|
34
|
-
| Receipts, outlays, deficit since FY2015 | `v1/accounting/mts/mts_table_1` | months: latest `record_date`, `record_type_cd` MTH; full FY: the September release's "Year-to-Date" row (`record_type_cd` SL, `data_type_cd` T) in the current-year block (`sequence_number_cd` 2.13; 1.13 is the prior year) | flow | $ |
|
|
35
|
-
| Receipts by source, outlays by function | `v1/accounting/mts/mts_table_9` | September `record_date`; `data_type_cd` D components, T "Total" | flow | $ |
|
|
36
|
-
| Outlays by agency, bureau, program | `v1/accounting/mts/mts_table_5` | `record_type_cd` A agency totals; D rows sum to "Total Outlays". A program account is a `classification_desc` line under its agency (Medicaid: "Grants to States for Medicaid" under HHS, `record_type_cd` P; FY2019 $409.4 billion = OMB Table 8.5): fetch the agency's rows and match the line by name (`--values` lists up to 200 lines per column under a narrow filter) | flow | $ |
|
|
37
|
-
| Gross interest expense | `v2/accounting/od/interest_expense` | all rows (detail only) sum to the total; MTS leaves out the GAS "Restoration of Interest" line (FY2025 on); TIPS lines include inflation compensation, a separate GAS "Inflation Compensation" line is not TIPS (docs/datasets.md) | flow | $ |
|
|
38
|
-
| Outlays by budget function (Social Security 650, Medicare 570, defense 050, net interest 900 ...) | MTS Table 9 (`v1/accounting/mts/mts_table_9`) | function rows add to total outlays; a function is not CBO's program measure (Social Security 650 includes administration; CBO reports benefits; Medicare 570 is
|
|
39
|
-
| Individual income tax refunds | DTS Table V `v1/accounting/dts/income_tax_refunds_issued` (cash, checks + EFT, refundable credits included, Treasury Offset Program offsets excluded); MTS Table 4 refunds (budget basis: refundable credits above liability are outlays) | the two differ by tens of billions a year and peak in different months (DTS February, MTS April): name the basis | flow | $M |
|
|
40
|
-
| Savings bond (Series I) rates | `v1/accounting/od/i_bonds_interest_rates` | one row per earning period and issue month back to 1998: the rate announced for new bonds is the row whose issue month falls in its own earning period; the composite rate has a 0% floor (May 2009, May 2015), so the published formula does not reproduce those rows; dates are `earning_period_start` (no `record_date`) | stock (a rate) | % |
|
|
41
|
-
| Average interest rate on the debt | `v2/accounting/od/avg_interest_rates` | `security_desc` "Total Interest-bearing Debt", "Total Marketable" (these totals leave out TIPS and FRNs: weighting the component rates by MSPD amounts reproduces them only without those two [derived 2026-10-21]); the TIPS rate is the real coupon, without inflation compensation: not comparable with nominal rates | stock | % |
|
|
42
|
-
| Treasury cash (TGA) | `v1/accounting/dts/operating_cash_balance` | see trap on 2022-04-18 | stock | $M |
|
|
43
|
-
| Daily deposits and withdrawals | `v1/accounting/dts/deposits_withdrawals_operating_cash` | `transaction_type`, `transaction_catg` | flow | $M |
|
|
44
|
-
| Auction results | `v1/accounting/od/auctions_query` | completed auctions (non-null `high_yield`); `original_security_term` to include reopenings; `inflation_index_security` No for nominal notes and bonds (TIPS are `security_type` Note too); use `bid_to_cover_ratio` as published (excludes SOMA) | event | mixed |
|
|
45
|
-
| Exchange rates | `v1/accounting/od/rates_of_exchange` | latest `effective_date` per quarter | stock | foreign units per USD |
|
|
46
|
-
|
|
47
|
-
## Spec examples
|
|
48
|
-
```json
|
|
49
|
-
{"description": "Net interest and average rates, FY2015-FY2025",
|
|
50
|
-
"as_of": "2025-09-30",
|
|
51
|
-
"datasets": [
|
|
52
|
-
{"name": "mts9", "endpoint": "v1/accounting/mts/mts_table_9",
|
|
53
|
-
"filter": {"record_date": {"gte": "2014-09-30"}, "record_calendar_month": "09"}},
|
|
54
|
-
{"name": "rates", "endpoint": "v2/accounting/od/avg_interest_rates",
|
|
55
|
-
"filter": {"record_date": {"gte": "2014-10-01"}, "security_desc": ["Total Interest-bearing Debt", "Total Marketable"]}}]}
|
|
56
|
-
```
|
|
57
|
-
```json
|
|
58
|
-
{"description": "Debt to the penny, fiscal year ends 2015-2025", "as_of": "2025-09-30",
|
|
59
|
-
"datasets": [{"name": "debt", "endpoint": "v2/accounting/od/debt_to_penny",
|
|
60
|
-
"filter": {"record_date": {"gte": "2014-09-01"}}}]}
|
|
61
|
-
```
|
|
62
|
-
Per dataset: `name` (file `<name>.csv`), `endpoint`, `filter` (bare value = eq, list = in, or
|
|
63
|
-
`{"gte": ...}`; a string is raw API syntax), optional `fields`, `date_field` (some endpoints use
|
|
64
|
-
`operation_date`, `effective_date` ...), `sort`, `allow_empty`. `as_of` adds `<date_field> <= as_of` to
|
|
65
|
-
every dataset so reruns are reproducible; leave it out only for "latest" lookups.
|
|
66
|
-
|
|
67
|
-
## Data format and traps
|
|
68
|
-
`fetch` writes `data/treasury/`: `<name>.csv` (API field names, values exactly as published, "null" ->
|
|
69
|
-
empty), `fetch_spec.json` (query URLs, row counts, first and last date, labels, types, unit hints, SHA-256,
|
|
70
|
-
route) and `README.md` (data dictionary with every code column's values). Codes stay text in the CSV, but a
|
|
71
|
-
reader may turn them into numbers: `compute` keeps codes with a leading zero ("09") as text, but reads a
|
|
72
|
-
column whose codes all look like numbers ("1.10", "2.13") as numbers (1.1, 2.13): check such a column before
|
|
73
|
-
filtering. The API's own CSV downloads put an apostrophe before negative amounts; `fetch` and `ingest` write
|
|
74
|
-
them without it.
|
|
75
|
-
- **Units differ:** MTS tables 1-9, Debt to the Penny, interest expense are dollars; DTS, MSPD (`*_mil_amt`)
|
|
76
|
-
and the long MTS series (`mts_receipts_outlays_deficit_surplus.mil_amt`) millions: read the field name;
|
|
77
|
-
percentage fields are already percent. **Signs:** MTS Table 1 shows a deficit as positive, Table 5 negative.
|
|
78
|
-
- **Stocks vs flows:** debt, cash, rates take the end-of-period value or the average (`compute` `to_fiscal`
|
|
79
|
-
with `how` "last" or "mean"); receipts, outlays, deficits, interest sum months (`how` "sum", check
|
|
80
|
-
`complete`) or read the September fiscal-year-to-date value. Never sum year-to-date values or stock levels.
|
|
81
|
-
- **Hierarchies double count:** MTS mixes headers (S), details (D) and totals (T); choose one level and prove
|
|
82
|
-
it: one row per key, and the rows add to the published total. Table 4's D rows do not sum to the
|
|
83
|
-
total (use Table 9). The same letter can be a value of two code columns: filter on the column it is in.
|
|
84
|
-
- **One release, several periods:** MTS Table 1 holds the prior and current fiscal year blocks
|
|
85
|
-
(`sequence_number_cd` 1.x and 2.x), each with its months and a "Year-to-Date" row; its only amount columns
|
|
86
|
-
are `current_month_gross_rcpt_amt`, `_gross_outly_amt`, `_dfct_sur_amt` (positive = deficit). Tables 9
|
|
87
|
-
and others carry `current_fytd_*` / `prior_fytd_*` columns instead.
|
|
88
|
-
- **Dates without a record:** Debt to the Penny and DTS have rows only on business days. For a requested
|
|
89
|
-
weekend or holiday (January 20, 2025 was both Inauguration Day and a federal holiday), use the last record
|
|
90
|
-
before it (its close equals the next statement's opening balance) and say so; count calendar days from
|
|
91
|
-
the requested date and business days from the records, and name which one a per-day figure uses.
|
|
92
|
-
- **Net vs gross receipts:** MTS receipts are net of refunds. When refunds are large the two can move in
|
|
93
|
-
opposite directions (FY2026 customs: gross up 57 percent, net down 11 percent after $145 billion of tariff
|
|
94
|
-
refunds): show gross, refunds and net (Table 4) and say which one the headline uses.
|
|
95
|
-
- **
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
- **
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
a
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
`
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
`
|
|
154
|
-
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
1
|
+
# U.S. Treasury Fiscal Data (fiscaldata.treasury.gov)
|
|
2
|
+
Depth: deep. Key: none. Official federal finance statistics from the Bureau of the Fiscal Service: debt,
|
|
3
|
+
deficits, receipts and outlays (Monthly Treasury Statement), Treasury cash (Daily Treasury Statement),
|
|
4
|
+
interest expense and average rates on the debt, the debt limit, auctions, exchange rates; 185 endpoints.
|
|
5
|
+
|
|
6
|
+
## When to use
|
|
7
|
+
- National debt (total, held by the public, intragovernmental; daily since 1993, yearly since 1790), debt by
|
|
8
|
+
security type, debt subject to the limit; monthly and fiscal-year receipts, outlays and deficits; receipts
|
|
9
|
+
by source, outlays by function and by agency; gross interest expense, net interest, average interest rates
|
|
10
|
+
on outstanding debt; the TGA cash balance and daily deposits and withdrawals; auction results; exchange
|
|
11
|
+
rates for federal reporting; gifts to reduce the debt; savings bonds; buybacks.
|
|
12
|
+
- Not here: market yields and the daily par yield curve (treasury-yields); GDP and CPI (bea, bls, fred; or
|
|
13
|
+
the spec's `context` field here, for real dollars and "% of GDP"); budget projections (CBO); historical tables in
|
|
14
|
+
% of GDP and the President's budget (OMB); who holds the debt by country (treasury-tic, not Fiscal Data);
|
|
15
|
+
state and local finances (Census).
|
|
16
|
+
- Deliver data plus a short answer by default; a report only when asked (see `guide`).
|
|
17
|
+
|
|
18
|
+
## Endpoints and datasets
|
|
19
|
+
Base `https://api.fiscaldata.treasury.gov/services/api/fiscal_service/` + a path with a fixed version (v1 or
|
|
20
|
+
v2: the other returns 404). `request_schema` with `search: "interest expense"` searches the live catalog
|
|
21
|
+
(falls back to the bundled `catalog.json`: a snapshot of the live catalog plus this guidance); `search:
|
|
22
|
+
"<endpoint>"` gives fields, types, units, row count, first and last row; `search: "<endpoint> {"record_date":
|
|
23
|
+
"2026-09-30"} values"` shows which values each code and description column holds; `request_schema` with
|
|
24
|
+
`names: ["dataset"]` lists the curated rows below. Full question-to-endpoint table: `docs/datasets.md`; API rules,
|
|
25
|
+
field meanings and the numbered gotchas: `docs/api_guide.md`; framing and conventions: `docs/report_patterns.md`.
|
|
26
|
+
|
|
27
|
+
| Question | Endpoint | Rows to use | Stock/flow | Units |
|
|
28
|
+
|---|---|---|---|---|
|
|
29
|
+
| Total debt, held by the public, intragovernmental (daily) | `v2/accounting/od/debt_to_penny` | one row per business day | stock | $ |
|
|
30
|
+
| Debt at fiscal year end since 1790 | `v2/accounting/od/debt_outstanding` | one row per year | stock | $ |
|
|
31
|
+
| Debt by security type (monthly) | `v1/debt/mspd/mspd_table_1` | `security_type_desc`, `security_class_desc`; skip "Total" rows | stock | $M |
|
|
32
|
+
| Debt subject to the limit | `v1/debt/mspd/mspd_table_2`, `v1/accounting/dts/debt_subject_to_limit` | `debt_catg_desc` | stock | $M |
|
|
33
|
+
| Monthly receipts, outlays, deficit since FY1981 | `v1/accounting/mts/mts_receipts_outlays_deficit_surplus` | `amt_category` | flow | $M |
|
|
34
|
+
| Receipts, outlays, deficit since FY2015 | `v1/accounting/mts/mts_table_1` | months: latest `record_date`, `record_type_cd` MTH; full FY: the September release's "Year-to-Date" row (`record_type_cd` SL, `data_type_cd` T) in the current-year block (`sequence_number_cd` 2.13; 1.13 is the prior year) | flow | $ |
|
|
35
|
+
| Receipts by source, outlays by function | `v1/accounting/mts/mts_table_9` | September `record_date`; `data_type_cd` D components, T "Total" | flow | $ |
|
|
36
|
+
| Outlays by agency, bureau, program | `v1/accounting/mts/mts_table_5` | `record_type_cd` A agency totals; D rows sum to "Total Outlays". A program account is a `classification_desc` line under its agency (Medicaid: "Grants to States for Medicaid" under HHS, `record_type_cd` P; FY2019 $409.4 billion = OMB Table 8.5): fetch the agency's rows and match the line by name (`--values` lists up to 200 lines per column under a narrow filter) | flow | $ |
|
|
37
|
+
| Gross interest expense | `v2/accounting/od/interest_expense` | all rows (detail only) sum to the total; MTS leaves out the GAS "Restoration of Interest" line (FY2025 on); TIPS lines include inflation compensation, a separate GAS "Inflation Compensation" line is not TIPS (docs/datasets.md) | flow | $ |
|
|
38
|
+
| Outlays by budget function (Social Security 650, Medicare 570, defense 050, net interest 900 ...) | MTS Table 9 (`v1/accounting/mts/mts_table_9`) | function rows add to total outlays; a function is not CBO's program measure (Social Security 650 includes administration; CBO reports benefits; Medicare 570 is already net of the premiums and other offsetting receipts credited to it, and CBO's "net Medicare" also nets a few receipts outside the function) | flow | $M |
|
|
39
|
+
| Individual income tax refunds | DTS Table V `v1/accounting/dts/income_tax_refunds_issued` (cash, checks + EFT, refundable credits included, Treasury Offset Program offsets excluded); MTS Table 4 refunds (budget basis: refundable credits above liability are outlays) | the two differ by tens of billions a year and peak in different months (DTS February, MTS April): name the basis | flow | $M |
|
|
40
|
+
| Savings bond (Series I) rates | `v1/accounting/od/i_bonds_interest_rates` | one row per earning period and issue month back to 1998: the rate announced for new bonds is the row whose issue month falls in its own earning period; the composite rate has a 0% floor (May 2009, May 2015), so the published formula does not reproduce those rows; dates are `earning_period_start` (no `record_date`) | stock (a rate) | % |
|
|
41
|
+
| Average interest rate on the debt | `v2/accounting/od/avg_interest_rates` | `security_desc` "Total Interest-bearing Debt", "Total Marketable" (these totals leave out TIPS and FRNs: weighting the component rates by MSPD amounts reproduces them only without those two [derived 2026-10-21]); the TIPS rate is the real coupon, without inflation compensation: not comparable with nominal rates | stock | % |
|
|
42
|
+
| Treasury cash (TGA) | `v1/accounting/dts/operating_cash_balance` | see trap on 2022-04-18 | stock | $M |
|
|
43
|
+
| Daily deposits and withdrawals | `v1/accounting/dts/deposits_withdrawals_operating_cash` | `transaction_type`, `transaction_catg` | flow | $M |
|
|
44
|
+
| Auction results | `v1/accounting/od/auctions_query` | completed auctions (non-null `high_yield`); `original_security_term` to include reopenings; `inflation_index_security` No for nominal notes and bonds (TIPS are `security_type` Note too); use `bid_to_cover_ratio` as published (excludes SOMA) | event | mixed |
|
|
45
|
+
| Exchange rates | `v1/accounting/od/rates_of_exchange` | latest `effective_date` per quarter | stock | foreign units per USD |
|
|
46
|
+
|
|
47
|
+
## Spec examples
|
|
48
|
+
```json
|
|
49
|
+
{"description": "Net interest and average rates, FY2015-FY2025",
|
|
50
|
+
"as_of": "2025-09-30",
|
|
51
|
+
"datasets": [
|
|
52
|
+
{"name": "mts9", "endpoint": "v1/accounting/mts/mts_table_9",
|
|
53
|
+
"filter": {"record_date": {"gte": "2014-09-30"}, "record_calendar_month": "09"}},
|
|
54
|
+
{"name": "rates", "endpoint": "v2/accounting/od/avg_interest_rates",
|
|
55
|
+
"filter": {"record_date": {"gte": "2014-10-01"}, "security_desc": ["Total Interest-bearing Debt", "Total Marketable"]}}]}
|
|
56
|
+
```
|
|
57
|
+
```json
|
|
58
|
+
{"description": "Debt to the penny, fiscal year ends 2015-2025", "as_of": "2025-09-30",
|
|
59
|
+
"datasets": [{"name": "debt", "endpoint": "v2/accounting/od/debt_to_penny",
|
|
60
|
+
"filter": {"record_date": {"gte": "2014-09-01"}}}]}
|
|
61
|
+
```
|
|
62
|
+
Per dataset: `name` (file `<name>.csv`), `endpoint`, `filter` (bare value = eq, list = in, or
|
|
63
|
+
`{"gte": ...}`; a string is raw API syntax), optional `fields`, `date_field` (some endpoints use
|
|
64
|
+
`operation_date`, `effective_date` ...), `sort`, `allow_empty`. `as_of` adds `<date_field> <= as_of` to
|
|
65
|
+
every dataset so reruns are reproducible; leave it out only for "latest" lookups.
|
|
66
|
+
|
|
67
|
+
## Data format and traps
|
|
68
|
+
`fetch` writes `data/treasury/`: `<name>.csv` (API field names, values exactly as published, "null" ->
|
|
69
|
+
empty), `fetch_spec.json` (query URLs, row counts, first and last date, labels, types, unit hints, SHA-256,
|
|
70
|
+
route) and `README.md` (data dictionary with every code column's values). Codes stay text in the CSV, but a
|
|
71
|
+
reader may turn them into numbers: `compute` keeps codes with a leading zero ("09") as text, but reads a
|
|
72
|
+
column whose codes all look like numbers ("1.10", "2.13") as numbers (1.1, 2.13): check such a column before
|
|
73
|
+
filtering. The API's own CSV downloads put an apostrophe before negative amounts; `fetch` and `ingest` write
|
|
74
|
+
them without it.
|
|
75
|
+
- **Units differ:** MTS tables 1-9, Debt to the Penny, interest expense are dollars; DTS, MSPD (`*_mil_amt`)
|
|
76
|
+
and the long MTS series (`mts_receipts_outlays_deficit_surplus.mil_amt`) millions: read the field name;
|
|
77
|
+
percentage fields are already percent. **Signs:** MTS Table 1 shows a deficit as positive, Table 5 negative.
|
|
78
|
+
- **Stocks vs flows:** debt, cash, rates take the end-of-period value or the average (`compute` `to_fiscal`
|
|
79
|
+
with `how` "last" or "mean"); receipts, outlays, deficits, interest sum months (`how` "sum", check
|
|
80
|
+
`complete`) or read the September fiscal-year-to-date value. Never sum year-to-date values or stock levels.
|
|
81
|
+
- **Hierarchies double count:** MTS mixes headers (S), details (D) and totals (T); choose one level and prove
|
|
82
|
+
it: one row per key, and the rows add to the published total. Table 4's D rows do not sum to the
|
|
83
|
+
total (use Table 9). The same letter can be a value of two code columns: filter on the column it is in.
|
|
84
|
+
- **One release, several periods:** MTS Table 1 holds the prior and current fiscal year blocks
|
|
85
|
+
(`sequence_number_cd` 1.x and 2.x), each with its months and a "Year-to-Date" row; its only amount columns
|
|
86
|
+
are `current_month_gross_rcpt_amt`, `_gross_outly_amt`, `_dfct_sur_amt` (positive = deficit). Tables 9
|
|
87
|
+
and others carry `current_fytd_*` / `prior_fytd_*` columns instead.
|
|
88
|
+
- **Dates without a record:** Debt to the Penny and DTS have rows only on business days. For a requested
|
|
89
|
+
weekend or holiday (January 20, 2025 was both Inauguration Day and a federal holiday), use the last record
|
|
90
|
+
before it (its close equals the next statement's opening balance) and say so; count calendar days from
|
|
91
|
+
the requested date and business days from the records, and name which one a per-day figure uses.
|
|
92
|
+
- **Net vs gross receipts:** MTS receipts are net of refunds. When refunds are large the two can move in
|
|
93
|
+
opposite directions (FY2026 customs: gross up 57 percent, net down 11 percent after $145 billion of tariff
|
|
94
|
+
refunds): show gross, refunds and net (Table 4) and say which one the headline uses.
|
|
95
|
+
- **Payment timing shifts:** when the first day of a month falls on a weekend or holiday, payments due that day
|
|
96
|
+
(Medicare Advantage and Part D plans, SSI, veterans' benefits, military pay) are made in the prior month. When
|
|
97
|
+
that day is October 1 they move into the prior fiscal year, by tens of billions of dollars.
|
|
98
|
+
Check October 1 at both ends of a year-over-year or multi-year comparison; if either year gained or lost
|
|
99
|
+
payments, adjust with the monthly rows (or say so) and name the shift in the answer, as CBO does.
|
|
100
|
+
- **Latest release wins:** MTS releases repeat and revise earlier months: build monthly series from the latest
|
|
101
|
+
`record_date`, full years from September releases; the next September restates the year (FY2024's deficit
|
|
102
|
+
moved by $16 billion).
|
|
103
|
+
- **`fields=` that drops row-identity columns makes the API group and sum rows**; `fetch` compares row
|
|
104
|
+
counts with and without it and stops.
|
|
105
|
+
- **Filter values:** exact text, case-sensitive; a malformed date returns no rows, not an error; values with
|
|
106
|
+
`&` or `,` (and parentheses inside an `in` list; `eq` with parentheses works, verified 2026-10) are
|
|
107
|
+
mishandled by the API, so `fetch` applies those conditions locally (recorded as
|
|
108
|
+
`local_filter`). A filter matching nothing is an `invalid_request` error unless `allow_empty`.
|
|
109
|
+
- **Format changes:** DTS operating cash changed on 2022-04-18 (before: the TGA/FRA row's `close_today_bal`;
|
|
110
|
+
after: the "Closing Balance" row's `open_today_bal`); DTS categories are renamed over time. Debt to the
|
|
111
|
+
Penny's held-by-public and intragovernmental fields are null before 2005-03-31.
|
|
112
|
+
- **Fiscal years** run October 1 to September 30, named for the year they end (`compute` `fiscal_year`); the
|
|
113
|
+
September MTS comes out mid-October. Find the latest complete period from the data (`request_schema` search
|
|
114
|
+
on the endpoint gives its last row), not from memory;
|
|
115
|
+
label partial years and compare them with the same months a year earlier.
|
|
116
|
+
- **Real dollars and GDP:** the spec field `"context": [{"kind": "cpi", "start": 2016}]` (or `"gdp"`; `start`
|
|
117
|
+
is the first fiscal year) writes `context_cpi.csv` / `context_gdp.csv` and `context_sources.json` (FRED, then
|
|
118
|
+
BLS or World Bank). Make a fiscal-year CPI with `compute` `to_fiscal` (`how` "mean") and apply it with
|
|
119
|
+
`deflate`; fiscal-year GDP is the average of four quarterly SAARs, Oct-Sep (`to_fiscal`, `freq` "Q", `how`
|
|
120
|
+
"mean"); the World Bank fallback is calendar years only and cannot give fiscal-year GDP. Incomplete periods
|
|
121
|
+
are flagged: say provisional.
|
|
122
|
+
- **Volume vs rate questions** ("more debt or higher rates?"): split the change exactly with the midpoint
|
|
123
|
+
method: debt effect = (debt1 - debt0) x (rate0 + rate1) / 2, rate effect = (rate1 - rate0) x (debt0 + debt1)
|
|
124
|
+
/ 2; the two add up to the change (`compute` `derive`).
|
|
125
|
+
- Analysis: build fiscal-year sums, growth and decompositions with `compute` on the CSVs in `data/treasury/`.
|
|
126
|
+
- **Benchmark** each headline against the official statement for the same date (MTS, MSPD, DTS, Treasury's
|
|
127
|
+
press release, CBO's Monthly Budget Review; for auctions, TreasuryDirect's results files
|
|
128
|
+
`https://www.treasurydirect.gov/xml/R_YYYYMMDD_n.xml`, keyless, a separate system from Fiscal Data); when the table is the statement itself, check its identities
|
|
129
|
+
(components add to the total; receipts - outlays = -deficit). Statement PDFs:
|
|
130
|
+
`https://fiscaldata.treasury.gov/static-data/published-reports/mts/MonthlyTreasuryStatement_YYYYMM.pdf` and
|
|
131
|
+
`.../dts/DailyTreasuryStatement_YYYYMMDD.pdf`; MSPD: `.../mspd-entire/MonthlyStatementPublicDebt_Entire_YYYYMM.pdf`. The fiscaldata.treasury.gov dataset pages draw their tables
|
|
132
|
+
with JavaScript: a fetch tool sees no values there (use the API or the PDFs). The PDFs are compressed:
|
|
133
|
+
a web fetch tool cannot read them; save the file and extract its text locally (pypdf). The API rows are
|
|
134
|
+
the statement's own figures, so an API value equal to the PDF's is a transcription check, not an
|
|
135
|
+
independent one. cbo.gov refuses scripted downloads (HTTP 403), and a browser pane may only download its
|
|
136
|
+
PDF: when no one can open it, record CBO's Monthly Budget Review as "not checked" in benchmark.csv (with a
|
|
137
|
+
data_needs entry), or ask the user to upload the PDF.
|
|
138
|
+
- **Identity gaps:** in `mts_receipts_outlays_deficit_surplus`, receipts minus outlays misses the deficit line by
|
|
139
|
+
a few million in some months (Sep 2022 by $10 million, Mar 2024 by $270 million, as published): use the
|
|
140
|
+
deficit line for deficits, check an identity with a tolerance of a few hundred million, and tie fiscal-year
|
|
141
|
+
totals to the September MTS.
|
|
142
|
+
- **Coverage:** MTS Tables 1 to 9 start in March 2015, so FY2015 is their first full year; a filter from an
|
|
143
|
+
earlier date returns rows from 2015 on without an error. For earlier years use
|
|
144
|
+
`mts_receipts_outlays_deficit_surplus` (totals from FY1981) or OMB's Historical Tables through FRED
|
|
145
|
+
(`FYOINT` net interest, `FYFSD` deficit, `FYONET` outlays, in millions), and say where the series join.
|
|
146
|
+
FRED carries only those totals: a receipt or outlay line before FY2015 (customs duties, a function) comes from
|
|
147
|
+
OMB's Historical Tables (Table 2.5 receipts by source, 3.2 outlays by function, 10.1 GDP; FY1940 on) through
|
|
148
|
+
the omb pack (`historical_table`, any budget edition); each edition revises history, so name the edition.
|
|
149
|
+
|
|
150
|
+
## Access
|
|
151
|
+
- No key, no registration, GET only, no documented rate limit (the client keeps 4 requests a second and
|
|
152
|
+
backs off on 429/5xx). Pages of up to 10,000 rows; `fetch` pages and checks the row count against
|
|
153
|
+
`total-count`.
|
|
154
|
+
- `fetch` reuses `data/treasury/` when it already holds the same spec (`force: true` refetches). A filter that
|
|
155
|
+
matches no rows or names an unknown field comes back as `invalid_request` (check values with `request_schema`
|
|
156
|
+
search `"<endpoint> <filter> values"`); a bad endpoint or aggregation the API refuses, as `agency_rejected`.
|
|
157
|
+
When the API cannot be reached (`agency_unavailable`: internet, VPN, proxy `HTTPS_PROXY`, a host that blocks
|
|
158
|
+
`api.fiscaldata.treasury.gov`), tell the user, offer `manual_bundle`, and never invent or recall numbers.
|
|
159
|
+
- Manual download: `manual_bundle` writes `manual_download/INSTRUCTIONS.md` with one CSV link per dataset
|
|
160
|
+
(10,000 rows each; more pages with `page%5Bnumber%5D=2` saved as `<name>_2.csv` ...), curl and PowerShell
|
|
161
|
+
scripts, and the dataset page whose Download button gives the whole table. Upload the CSV or ZIP files
|
|
162
|
+
unchanged (not re-saved in Excel); `ingest` with the uploaded files or their folder applies the spec's
|
|
163
|
+
filter locally, strips the apostrophe guard, drops duplicate rows and warns about a missing page.
|
|
164
|
+
|
|
165
|
+
## Citation and terms
|
|
166
|
+
"U.S. Department of the Treasury, Bureau of the Fiscal Service, Fiscal Data (https://fiscaldata.treasury.gov),
|
|
167
|
+
<endpoints>; retrieved <date> through the Fiscal Data API." (exact line in `data/treasury/README.md`). Source
|
|
168
|
+
line: "Analyst calculations using data from the Department of the Treasury, Bureau of the Fiscal Service,
|
|
169
|
+
Monthly Treasury Statement (retrieved <date>)." Public domain: redistribution allowed; cite the retrieval
|
|
170
|
+
date because Treasury revises some series.
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
{
|
|
2
|
+
"base_url": "https://ticdata.treasury.gov/resource-center/data-chart-center/tic/Documents",
|
|
3
|
+
"timeout": 60,
|
|
4
|
+
"endpoints": {
|
|
5
|
+
"major_foreign_holders": {
|
|
6
|
+
"path": "/slt_table5.txt",
|
|
7
|
+
"method": "GET",
|
|
8
|
+
"description": "Major Foreign Holders of Treasury Securities (SLT Table 5): holdings by country, the latest 13 months, billions of dollars, plus All Other, Grand Total and the foreign-official split (bills, bonds and notes). One row per country and month.",
|
|
9
|
+
"params": {
|
|
10
|
+
"country": {
|
|
11
|
+
"in": "spec",
|
|
12
|
+
"desc": "keep only these rows: a country name as published (Japan; China, Mainland; Korea, South), or a list; case-insensitive. Omit for every row."
|
|
13
|
+
}
|
|
14
|
+
},
|
|
15
|
+
"records": "$tsv",
|
|
16
|
+
"header_row": 6,
|
|
17
|
+
"paging": {
|
|
18
|
+
"type": "none"
|
|
19
|
+
},
|
|
20
|
+
"max_rows": 10000
|
|
21
|
+
},
|
|
22
|
+
"major_foreign_holders_history": {
|
|
23
|
+
"path": "/mfhhis01.txt",
|
|
24
|
+
"method": "GET",
|
|
25
|
+
"description": "Major Foreign Holders history (mfhhis01.txt): the same table for every month from March 2000 through the last completed year, billions of dollars, one row per country and month. Series breaks are marked by footnotes in the file.",
|
|
26
|
+
"params": {
|
|
27
|
+
"country": {
|
|
28
|
+
"in": "spec",
|
|
29
|
+
"desc": "keep only these rows (a name as published, or a list; case-insensitive)"
|
|
30
|
+
},
|
|
31
|
+
"from": {
|
|
32
|
+
"in": "spec",
|
|
33
|
+
"desc": "first month to keep, YYYY-MM"
|
|
34
|
+
},
|
|
35
|
+
"to": {
|
|
36
|
+
"in": "spec",
|
|
37
|
+
"desc": "last month to keep, YYYY-MM"
|
|
38
|
+
},
|
|
39
|
+
"include_comparison": {
|
|
40
|
+
"in": "spec",
|
|
41
|
+
"desc": "true keeps the previous-series value of a series-break month (June 2002-2011, March 2000), marked comparison_only; default false"
|
|
42
|
+
}
|
|
43
|
+
},
|
|
44
|
+
"records": "$tsv",
|
|
45
|
+
"header_row": 0,
|
|
46
|
+
"paging": {
|
|
47
|
+
"type": "none"
|
|
48
|
+
},
|
|
49
|
+
"max_rows": 100000
|
|
50
|
+
},
|
|
51
|
+
"holdings_by_country": {
|
|
52
|
+
"path": "/slt_table1.txt",
|
|
53
|
+
"method": "GET",
|
|
54
|
+
"description": "SLT Table 1: U.S. long-term securities held by foreign residents, by country and month (from September 2011), millions of dollars: holdings, net U.S. sales and valuation change for Treasuries, agency bonds, corporate and other bonds, and equities.",
|
|
55
|
+
"params": {
|
|
56
|
+
"country": {
|
|
57
|
+
"in": "spec",
|
|
58
|
+
"desc": "keep only these countries (name as published, or the 5-digit TIC country code; a list works); case-insensitive"
|
|
59
|
+
},
|
|
60
|
+
"from": {
|
|
61
|
+
"in": "spec",
|
|
62
|
+
"desc": "first month to keep, YYYY-MM"
|
|
63
|
+
},
|
|
64
|
+
"to": {
|
|
65
|
+
"in": "spec",
|
|
66
|
+
"desc": "last month to keep, YYYY-MM"
|
|
67
|
+
}
|
|
68
|
+
},
|
|
69
|
+
"records": "$tsv",
|
|
70
|
+
"header_row": 9,
|
|
71
|
+
"paging": {
|
|
72
|
+
"type": "none"
|
|
73
|
+
},
|
|
74
|
+
"max_rows": 200000
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "treasury-tic",
|
|
3
|
+
"title": "Treasury International Capital (TIC): foreign holdings of U.S. Treasury and other securities",
|
|
4
|
+
"agency": "U.S. Department of the Treasury and Federal Reserve Board",
|
|
5
|
+
"depth": "standard",
|
|
6
|
+
"domains": [
|
|
7
|
+
"federal debt",
|
|
8
|
+
"international finance",
|
|
9
|
+
"capital flows"
|
|
10
|
+
],
|
|
11
|
+
"keywords": [
|
|
12
|
+
"tic",
|
|
13
|
+
"treasury international capital",
|
|
14
|
+
"foreign holders",
|
|
15
|
+
"major foreign holders",
|
|
16
|
+
"foreign holdings of treasuries",
|
|
17
|
+
"who owns the debt",
|
|
18
|
+
"who holds the debt",
|
|
19
|
+
"china holdings",
|
|
20
|
+
"japan holdings",
|
|
21
|
+
"foreign official",
|
|
22
|
+
"foreign central banks",
|
|
23
|
+
"slt",
|
|
24
|
+
"cross-border securities",
|
|
25
|
+
"foreign purchases of u.s. securities",
|
|
26
|
+
"net foreign sales",
|
|
27
|
+
"capital flows",
|
|
28
|
+
"foreign-held debt"
|
|
29
|
+
],
|
|
30
|
+
"questions": [
|
|
31
|
+
"how much U.S. Treasury debt does China hold",
|
|
32
|
+
"largest foreign holders of Treasury securities",
|
|
33
|
+
"Japan's Treasury holdings over time",
|
|
34
|
+
"foreign official holdings of Treasury bills and bonds",
|
|
35
|
+
"foreign holdings of U.S. corporate bonds and stocks by country",
|
|
36
|
+
"net foreign purchases of Treasuries by country"
|
|
37
|
+
],
|
|
38
|
+
"homepage": "https://home.treasury.gov/data/treasury-international-capital-tic-system",
|
|
39
|
+
"terms_url": "https://home.treasury.gov/subfooter/site-policies-and-notices",
|
|
40
|
+
"auth": {
|
|
41
|
+
"env": null,
|
|
42
|
+
"required": "none",
|
|
43
|
+
"placement": "none",
|
|
44
|
+
"signup_url": null,
|
|
45
|
+
"echoes_key": false
|
|
46
|
+
},
|
|
47
|
+
"limits": {
|
|
48
|
+
"rps": 2,
|
|
49
|
+
"burst": 4,
|
|
50
|
+
"max_rows": 200000
|
|
51
|
+
},
|
|
52
|
+
"routes": {
|
|
53
|
+
"api": {
|
|
54
|
+
"base": "https://ticdata.treasury.gov/resource-center/data-chart-center/tic/Documents",
|
|
55
|
+
"probe": "https://ticdata.treasury.gov/resource-center/data-chart-center/tic/Documents/slt_table5.txt",
|
|
56
|
+
"hosts": [
|
|
57
|
+
"ticdata.treasury.gov"
|
|
58
|
+
]
|
|
59
|
+
},
|
|
60
|
+
"manual": {
|
|
61
|
+
"how": "Open the text files in a browser and save them: https://ticdata.treasury.gov/resource-center/data-chart-center/tic/Documents/slt_table5.txt (latest 13 months), .../mfhhis01.txt (history from 2000) or .../slt_table1.txt (long-term securities by country). Upload the saved .txt file with ingest."
|
|
62
|
+
}
|
|
63
|
+
},
|
|
64
|
+
"cache": {
|
|
65
|
+
"mode": "run_only",
|
|
66
|
+
"ttl_hours": null,
|
|
67
|
+
"why": "Monthly releases revise the last months; data/ is reused within a run."
|
|
68
|
+
},
|
|
69
|
+
"redistribution": {
|
|
70
|
+
"mode": "allowed",
|
|
71
|
+
"why": "U.S. government work in the public domain (17 U.S.C. 105)."
|
|
72
|
+
},
|
|
73
|
+
"notices": [],
|
|
74
|
+
"retention": null,
|
|
75
|
+
"citation": "U.S. Department of the Treasury, Treasury International Capital (TIC) System, {dataset}, ticdata.treasury.gov, retrieved {retrieved_long}.",
|
|
76
|
+
"audit_hooks": [],
|
|
77
|
+
"clarify": [
|
|
78
|
+
"Which measure? Major Foreign Holders counts all Treasury securities (bills, bonds and notes) in billions; SLT Table 1 counts long-term securities only (no bills), in millions, and also covers agency, corporate bonds and stocks. Default: Major Foreign Holders for 'how much debt does X hold'.",
|
|
79
|
+
"Which months? slt_table5 has the latest 13 months; mfhhis01 has March 2000 through the last full year. Default: the latest month, with the year-earlier month for comparison."
|
|
80
|
+
],
|
|
81
|
+
"formats": [
|
|
82
|
+
"txt"
|
|
83
|
+
],
|
|
84
|
+
"aliases": [
|
|
85
|
+
"TIC",
|
|
86
|
+
"Treasury International Capital",
|
|
87
|
+
"Major Foreign Holders"
|
|
88
|
+
]
|
|
89
|
+
}
|