data-analyst-mcp 0.0.0-stage → 0.3.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 +262 -3
- package/dist/adapters/_acf_tidy.d.ts +18 -0
- package/dist/adapters/_acf_tidy.js +432 -0
- package/dist/adapters/_acf_tidy.js.map +1 -0
- package/dist/adapters/_actuaries_read.d.ts +38 -0
- package/dist/adapters/_actuaries_read.js +728 -0
- package/dist/adapters/_actuaries_read.js.map +1 -0
- package/dist/adapters/_census_micro.d.ts +70 -0
- package/dist/adapters/_census_micro.js +622 -0
- package/dist/adapters/_census_micro.js.map +1 -0
- package/dist/adapters/_census_util.d.ts +40 -0
- package/dist/adapters/_census_util.js +275 -0
- package/dist/adapters/_census_util.js.map +1 -0
- package/dist/adapters/_dol_states.d.ts +6 -0
- package/dist/adapters/_dol_states.js +58 -0
- package/dist/adapters/_dol_states.js.map +1 -0
- package/dist/adapters/_govinfo_entities.d.ts +4 -0
- package/dist/adapters/_govinfo_entities.js +6 -0
- package/dist/adapters/_govinfo_entities.js.map +1 -0
- package/dist/adapters/_govinfo_json.d.ts +13 -0
- package/dist/adapters/_govinfo_json.js +107 -0
- package/dist/adapters/_govinfo_json.js.map +1 -0
- package/dist/adapters/_govinfo_py.d.ts +22 -0
- package/dist/adapters/_govinfo_py.js +272 -0
- package/dist/adapters/_govinfo_py.js.map +1 -0
- package/dist/adapters/_govinfo_xml.d.ts +22 -0
- package/dist/adapters/_govinfo_xml.js +233 -0
- package/dist/adapters/_govinfo_xml.js.map +1 -0
- package/dist/adapters/_hud_excel.d.ts +2 -0
- package/dist/adapters/_hud_excel.js +166 -0
- package/dist/adapters/_hud_excel.js.map +1 -0
- package/dist/adapters/_omb_grid.d.ts +17 -0
- package/dist/adapters/_omb_grid.js +132 -0
- package/dist/adapters/_omb_grid.js.map +1 -0
- package/dist/adapters/_omb_util.d.ts +40 -0
- package/dist/adapters/_omb_util.js +192 -0
- package/dist/adapters/_omb_util.js.map +1 -0
- package/dist/adapters/_usaspending_state.d.ts +6 -0
- package/dist/adapters/_usaspending_state.js +54 -0
- package/dist/adapters/_usaspending_state.js.map +1 -0
- package/dist/adapters/_usda-fna_book.d.ts +59 -0
- package/dist/adapters/_usda-fna_book.js +869 -0
- package/dist/adapters/_usda-fna_book.js.map +1 -0
- package/dist/adapters/_usda-fna_pdf.d.ts +20 -0
- package/dist/adapters/_usda-fna_pdf.js +361 -0
- package/dist/adapters/_usda-fna_pdf.js.map +1 -0
- package/dist/adapters/_usda-outlook_read.d.ts +70 -0
- package/dist/adapters/_usda-outlook_read.js +362 -0
- package/dist/adapters/_usda-outlook_read.js.map +1 -0
- package/dist/adapters/acf.d.ts +3 -0
- package/dist/adapters/acf.js +187 -0
- package/dist/adapters/acf.js.map +1 -0
- package/dist/adapters/actuaries.d.ts +3 -0
- package/dist/adapters/actuaries.js +293 -0
- package/dist/adapters/actuaries.js.map +1 -0
- package/dist/adapters/bts.d.ts +3 -0
- package/dist/adapters/bts.js +26 -0
- package/dist/adapters/bts.js.map +1 -0
- package/dist/adapters/census-geocoder.d.ts +10 -0
- package/dist/adapters/census-geocoder.js +47 -0
- package/dist/adapters/census-geocoder.js.map +1 -0
- package/dist/adapters/census.d.ts +17 -0
- package/dist/adapters/census.js +983 -0
- package/dist/adapters/census.js.map +1 -0
- package/dist/adapters/cfpb.d.ts +7 -0
- package/dist/adapters/cfpb.js +348 -0
- package/dist/adapters/cfpb.js.map +1 -0
- package/dist/adapters/clinical-trials.d.ts +3 -0
- package/dist/adapters/clinical-trials.js +135 -0
- package/dist/adapters/clinical-trials.js.map +1 -0
- package/dist/adapters/cms.d.ts +3 -0
- package/dist/adapters/cms.js +292 -0
- package/dist/adapters/cms.js.map +1 -0
- package/dist/adapters/college-scorecard.d.ts +3 -0
- package/dist/adapters/college-scorecard.js +122 -0
- package/dist/adapters/college-scorecard.js.map +1 -0
- package/dist/adapters/congress.d.ts +33 -0
- package/dist/adapters/congress.js +589 -0
- package/dist/adapters/congress.js.map +1 -0
- package/dist/adapters/dhs-ohss.d.ts +13 -0
- package/dist/adapters/dhs-ohss.js +598 -0
- package/dist/adapters/dhs-ohss.js.map +1 -0
- package/dist/adapters/doj-news.d.ts +7 -0
- package/dist/adapters/doj-news.js +286 -0
- package/dist/adapters/doj-news.js.map +1 -0
- package/dist/adapters/dol.d.ts +4 -0
- package/dist/adapters/dol.js +634 -0
- package/dist/adapters/dol.js.map +1 -0
- package/dist/adapters/eia.d.ts +15 -0
- package/dist/adapters/eia.js +456 -0
- package/dist/adapters/eia.js.map +1 -0
- package/dist/adapters/epa-aqs.d.ts +3 -0
- package/dist/adapters/epa-aqs.js +357 -0
- package/dist/adapters/epa-aqs.js.map +1 -0
- package/dist/adapters/epa.d.ts +3 -0
- package/dist/adapters/epa.js +298 -0
- package/dist/adapters/epa.js.map +1 -0
- package/dist/adapters/fbi.d.ts +3 -0
- package/dist/adapters/fbi.js +192 -0
- package/dist/adapters/fbi.js.map +1 -0
- package/dist/adapters/fda.d.ts +5 -0
- package/dist/adapters/fda.js +184 -0
- package/dist/adapters/fda.js.map +1 -0
- package/dist/adapters/fdic.d.ts +4 -0
- package/dist/adapters/fdic.js +95 -0
- package/dist/adapters/fdic.js.map +1 -0
- package/dist/adapters/fec.d.ts +3 -0
- package/dist/adapters/fec.js +142 -0
- package/dist/adapters/fec.js.map +1 -0
- package/dist/adapters/fed-board.d.ts +12 -0
- package/dist/adapters/fed-board.js +581 -0
- package/dist/adapters/fed-board.js.map +1 -0
- package/dist/adapters/federal-register.d.ts +11 -0
- package/dist/adapters/federal-register.js +43 -0
- package/dist/adapters/federal-register.js.map +1 -0
- package/dist/adapters/fhfa.d.ts +3 -0
- package/dist/adapters/fhfa.js +253 -0
- package/dist/adapters/fhfa.js.map +1 -0
- package/dist/adapters/fsa.d.ts +9 -0
- package/dist/adapters/fsa.js +335 -0
- package/dist/adapters/fsa.js.map +1 -0
- package/dist/adapters/govinfo.d.ts +30 -0
- package/dist/adapters/govinfo.js +636 -0
- package/dist/adapters/govinfo.js.map +1 -0
- package/dist/adapters/gsa-calc.d.ts +10 -0
- package/dist/adapters/gsa-calc.js +318 -0
- package/dist/adapters/gsa-calc.js.map +1 -0
- package/dist/adapters/hud.d.ts +3 -0
- package/dist/adapters/hud.js +200 -0
- package/dist/adapters/hud.js.map +1 -0
- package/dist/adapters/index.d.ts +3 -0
- package/dist/adapters/index.js +25 -0
- package/dist/adapters/index.js.map +1 -0
- package/dist/adapters/irs-soi.d.ts +6 -0
- package/dist/adapters/irs-soi.js +576 -0
- package/dist/adapters/irs-soi.js.map +1 -0
- package/dist/adapters/naep.d.ts +15 -0
- package/dist/adapters/naep.js +341 -0
- package/dist/adapters/naep.js.map +1 -0
- package/dist/adapters/nhtsa.d.ts +10 -0
- package/dist/adapters/nhtsa.js +239 -0
- package/dist/adapters/nhtsa.js.map +1 -0
- package/dist/adapters/nih.d.ts +5 -0
- package/dist/adapters/nih.js +196 -0
- package/dist/adapters/nih.js.map +1 -0
- package/dist/adapters/noaa.d.ts +3 -0
- package/dist/adapters/noaa.js +148 -0
- package/dist/adapters/noaa.js.map +1 -0
- package/dist/adapters/nrel.d.ts +3 -0
- package/dist/adapters/nrel.js +186 -0
- package/dist/adapters/nrel.js.map +1 -0
- package/dist/adapters/nws.d.ts +3 -0
- package/dist/adapters/nws.js +119 -0
- package/dist/adapters/nws.js.map +1 -0
- package/dist/adapters/omb.d.ts +15 -0
- package/dist/adapters/omb.js +517 -0
- package/dist/adapters/omb.js.map +1 -0
- package/dist/adapters/open-payments.d.ts +5 -0
- package/dist/adapters/open-payments.js +149 -0
- package/dist/adapters/open-payments.js.map +1 -0
- package/dist/adapters/pbgc.d.ts +13 -0
- package/dist/adapters/pbgc.js +283 -0
- package/dist/adapters/pbgc.js.map +1 -0
- package/dist/adapters/philfed.d.ts +12 -0
- package/dist/adapters/philfed.js +59 -0
- package/dist/adapters/philfed.js.map +1 -0
- package/dist/adapters/regulations.d.ts +6 -0
- package/dist/adapters/regulations.js +58 -0
- package/dist/adapters/regulations.js.map +1 -0
- package/dist/adapters/sec.d.ts +13 -0
- package/dist/adapters/sec.js +504 -0
- package/dist/adapters/sec.js.map +1 -0
- package/dist/adapters/senate-lobbying.d.ts +3 -0
- package/dist/adapters/senate-lobbying.js +181 -0
- package/dist/adapters/senate-lobbying.js.map +1 -0
- package/dist/adapters/snapqc.d.ts +32 -0
- package/dist/adapters/snapqc.js +701 -0
- package/dist/adapters/snapqc.js.map +1 -0
- package/dist/adapters/treasury-yields.d.ts +3 -0
- package/dist/adapters/treasury-yields.js +170 -0
- package/dist/adapters/treasury-yields.js.map +1 -0
- package/dist/adapters/usaspending.d.ts +3 -0
- package/dist/adapters/usaspending.js +340 -0
- package/dist/adapters/usaspending.js.map +1 -0
- package/dist/adapters/usda-fna.d.ts +7 -0
- package/dist/adapters/usda-fna.js +707 -0
- package/dist/adapters/usda-fna.js.map +1 -0
- package/dist/adapters/usda-fooddata.d.ts +3 -0
- package/dist/adapters/usda-fooddata.js +101 -0
- package/dist/adapters/usda-fooddata.js.map +1 -0
- package/dist/adapters/usda-nass.d.ts +3 -0
- package/dist/adapters/usda-nass.js +108 -0
- package/dist/adapters/usda-nass.js.map +1 -0
- package/dist/adapters/usda-outlook.d.ts +12 -0
- package/dist/adapters/usda-outlook.js +696 -0
- package/dist/adapters/usda-outlook.js.map +1 -0
- package/dist/adapters/usgs.d.ts +9 -0
- package/dist/adapters/usgs.js +265 -0
- package/dist/adapters/usgs.js.map +1 -0
- package/dist/adapters/usitc.d.ts +18 -0
- package/dist/adapters/usitc.js +170 -0
- package/dist/adapters/usitc.js.map +1 -0
- package/dist/adapters/uspto.d.ts +3 -0
- package/dist/adapters/uspto.js +47 -0
- package/dist/adapters/uspto.js.map +1 -0
- package/dist/adapters/world-bank.d.ts +3 -0
- package/dist/adapters/world-bank.js +163 -0
- package/dist/adapters/world-bank.js.map +1 -0
- package/dist/analysis/cite.d.ts +31 -0
- package/dist/analysis/cite.js +229 -0
- package/dist/analysis/cite.js.map +1 -0
- package/dist/analysis/combine.d.ts +27 -0
- package/dist/analysis/combine.js +198 -0
- package/dist/analysis/combine.js.map +1 -0
- package/dist/analysis/compute.d.ts +62 -0
- package/dist/analysis/compute.js +583 -0
- package/dist/analysis/compute.js.map +1 -0
- package/dist/analysis/expr.d.ts +69 -0
- package/dist/analysis/expr.js +780 -0
- package/dist/analysis/expr.js.map +1 -0
- package/dist/analysis/factfmt.d.ts +16 -0
- package/dist/analysis/factfmt.js +187 -0
- package/dist/analysis/factfmt.js.map +1 -0
- package/dist/analysis/facts.d.ts +63 -0
- package/dist/analysis/facts.js +355 -0
- package/dist/analysis/facts.js.map +1 -0
- package/dist/analysis/handoff.d.ts +58 -0
- package/dist/analysis/handoff.js +208 -0
- package/dist/analysis/handoff.js.map +1 -0
- package/dist/analysis/pyfmt.d.ts +16 -0
- package/dist/analysis/pyfmt.js +156 -0
- package/dist/analysis/pyfmt.js.map +1 -0
- package/dist/analysis/rerun.d.ts +13 -0
- package/dist/analysis/rerun.js +125 -0
- package/dist/analysis/rerun.js.map +1 -0
- package/dist/analysis/table.d.ts +18 -0
- package/dist/analysis/table.js +109 -0
- package/dist/analysis/table.js.map +1 -0
- package/dist/analysis/tools.d.ts +67 -0
- package/dist/analysis/tools.js +217 -0
- package/dist/analysis/tools.js.map +1 -0
- package/dist/analysis/write_table.d.ts +13 -0
- package/dist/analysis/write_table.js +59 -0
- package/dist/analysis/write_table.js.map +1 -0
- package/dist/bin/cli.d.ts +10 -0
- package/dist/bin/cli.js +177 -0
- package/dist/bin/cli.js.map +1 -0
- package/dist/core/cache.d.ts +14 -0
- package/dist/core/cache.js +90 -0
- package/dist/core/cache.js.map +1 -0
- package/dist/core/context.d.ts +12 -0
- package/dist/core/context.js +15 -0
- package/dist/core/context.js.map +1 -0
- package/dist/core/env.d.ts +14 -0
- package/dist/core/env.js +52 -0
- package/dist/core/env.js.map +1 -0
- package/dist/core/generic-rest.d.ts +61 -0
- package/dist/core/generic-rest.js +639 -0
- package/dist/core/generic-rest.js.map +1 -0
- package/dist/core/http.d.ts +120 -0
- package/dist/core/http.js +514 -0
- package/dist/core/http.js.map +1 -0
- package/dist/core/keys.d.ts +43 -0
- package/dist/core/keys.js +174 -0
- package/dist/core/keys.js.map +1 -0
- package/dist/core/manual.d.ts +41 -0
- package/dist/core/manual.js +218 -0
- package/dist/core/manual.js.map +1 -0
- package/dist/core/package.d.ts +58 -0
- package/dist/core/package.js +228 -0
- package/dist/core/package.js.map +1 -0
- package/dist/core/packs.d.ts +139 -0
- package/dist/core/packs.js +173 -0
- package/dist/core/packs.js.map +1 -0
- package/dist/core/policy.d.ts +69 -0
- package/dist/core/policy.js +189 -0
- package/dist/core/policy.js.map +1 -0
- package/dist/core/py.d.ts +40 -0
- package/dist/core/py.js +171 -0
- package/dist/core/py.js.map +1 -0
- package/dist/core/routing.d.ts +10 -0
- package/dist/core/routing.js +39 -0
- package/dist/core/routing.js.map +1 -0
- package/dist/core/tabular.d.ts +21 -0
- package/dist/core/tabular.js +229 -0
- package/dist/core/tabular.js.map +1 -0
- package/dist/deep/_bea_api.d.ts +102 -0
- package/dist/deep/_bea_api.js +457 -0
- package/dist/deep/_bea_api.js.map +1 -0
- package/dist/deep/_bea_fetch.d.ts +151 -0
- package/dist/deep/_bea_fetch.js +1274 -0
- package/dist/deep/_bea_fetch.js.map +1 -0
- package/dist/deep/_bea_util.d.ts +14 -0
- package/dist/deep/_bea_util.js +156 -0
- package/dist/deep/_bea_util.js.map +1 -0
- package/dist/deep/_bls_api.d.ts +84 -0
- package/dist/deep/_bls_api.js +231 -0
- package/dist/deep/_bls_api.js.map +1 -0
- package/dist/deep/_bls_ids.d.ts +43 -0
- package/dist/deep/_bls_ids.js +188 -0
- package/dist/deep/_bls_ids.js.map +1 -0
- package/dist/deep/_bls_lib.d.ts +61 -0
- package/dist/deep/_bls_lib.js +442 -0
- package/dist/deep/_bls_lib.js.map +1 -0
- package/dist/deep/_fred_api.d.ts +148 -0
- package/dist/deep/_fred_api.js +545 -0
- package/dist/deep/_fred_api.js.map +1 -0
- package/dist/deep/_fred_pack.d.ts +162 -0
- package/dist/deep/_fred_pack.js +1027 -0
- package/dist/deep/_fred_pack.js.map +1 -0
- package/dist/deep/_fred_py.d.ts +40 -0
- package/dist/deep/_fred_py.js +199 -0
- package/dist/deep/_fred_py.js.map +1 -0
- package/dist/deep/_ipums_bundle.d.ts +29 -0
- package/dist/deep/_ipums_bundle.js +194 -0
- package/dist/deep/_ipums_bundle.js.map +1 -0
- package/dist/deep/_ipums_ddi.d.ts +23 -0
- package/dist/deep/_ipums_ddi.js +162 -0
- package/dist/deep/_ipums_ddi.js.map +1 -0
- package/dist/deep/_opm_io.d.ts +26 -0
- package/dist/deep/_opm_io.js +383 -0
- package/dist/deep/_opm_io.js.map +1 -0
- package/dist/deep/_opm_parquet.d.ts +31 -0
- package/dist/deep/_opm_parquet.js +744 -0
- package/dist/deep/_opm_parquet.js.map +1 -0
- package/dist/deep/_opm_py.d.ts +6 -0
- package/dist/deep/_opm_py.js +74 -0
- package/dist/deep/_opm_py.js.map +1 -0
- package/dist/deep/_treasury_api.d.ts +48 -0
- package/dist/deep/_treasury_api.js +221 -0
- package/dist/deep/_treasury_api.js.map +1 -0
- package/dist/deep/_treasury_context.d.ts +34 -0
- package/dist/deep/_treasury_context.js +142 -0
- package/dist/deep/_treasury_context.js.map +1 -0
- package/dist/deep/_treasury_lib.d.ts +109 -0
- package/dist/deep/_treasury_lib.js +686 -0
- package/dist/deep/_treasury_lib.js.map +1 -0
- package/dist/deep/bea.d.ts +3 -0
- package/dist/deep/bea.js +248 -0
- package/dist/deep/bea.js.map +1 -0
- package/dist/deep/bls.d.ts +3 -0
- package/dist/deep/bls.js +220 -0
- package/dist/deep/bls.js.map +1 -0
- package/dist/deep/fred.d.ts +3 -0
- package/dist/deep/fred.js +325 -0
- package/dist/deep/fred.js.map +1 -0
- package/dist/deep/ipums.d.ts +59 -0
- package/dist/deep/ipums.js +744 -0
- package/dist/deep/ipums.js.map +1 -0
- package/dist/deep/opm.d.ts +56 -0
- package/dist/deep/opm.js +1033 -0
- package/dist/deep/opm.js.map +1 -0
- package/dist/deep/treasury.d.ts +3 -0
- package/dist/deep/treasury.js +218 -0
- package/dist/deep/treasury.js.map +1 -0
- package/dist/envelope.d.ts +47 -0
- package/dist/envelope.js +88 -0
- package/dist/envelope.js.map +1 -0
- package/dist/index.d.ts +277 -0
- package/dist/index.js +106 -0
- package/dist/index.js.map +1 -0
- package/dist/remote/app.d.ts +21 -0
- package/dist/remote/app.js +218 -0
- package/dist/remote/app.js.map +1 -0
- package/dist/remote/oauth.d.ts +14 -0
- package/dist/remote/oauth.js +90 -0
- package/dist/remote/oauth.js.map +1 -0
- package/dist/remote/pages.d.ts +8 -0
- package/dist/remote/pages.js +56 -0
- package/dist/remote/pages.js.map +1 -0
- package/dist/remote/sign.d.ts +4 -0
- package/dist/remote/sign.js +40 -0
- package/dist/remote/sign.js.map +1 -0
- package/dist/remote/store.d.ts +31 -0
- package/dist/remote/store.js +129 -0
- package/dist/remote/store.js.map +1 -0
- package/dist/report/audit_answer.d.ts +94 -0
- package/dist/report/audit_answer.js +1349 -0
- package/dist/report/audit_answer.js.map +1 -0
- package/dist/report/audit_report.d.ts +23 -0
- package/dist/report/audit_report.js +637 -0
- package/dist/report/audit_report.js.map +1 -0
- package/dist/report/build_report.d.ts +27 -0
- package/dist/report/build_report.js +1168 -0
- package/dist/report/build_report.js.map +1 -0
- package/dist/report/method_audit.d.ts +47 -0
- package/dist/report/method_audit.js +710 -0
- package/dist/report/method_audit.js.map +1 -0
- package/dist/report/policyset.d.ts +50 -0
- package/dist/report/policyset.js +421 -0
- package/dist/report/policyset.js.map +1 -0
- package/dist/report/py.d.ts +58 -0
- package/dist/report/py.js +311 -0
- package/dist/report/py.js.map +1 -0
- package/dist/report/scan_secrets.d.ts +21 -0
- package/dist/report/scan_secrets.js +234 -0
- package/dist/report/scan_secrets.js.map +1 -0
- package/dist/report/style_check.d.ts +29 -0
- package/dist/report/style_check.js +173 -0
- package/dist/report/style_check.js.map +1 -0
- package/dist/report/tools.d.ts +87 -0
- package/dist/report/tools.js +167 -0
- package/dist/report/tools.js.map +1 -0
- package/dist/server.d.ts +5 -0
- package/dist/server.js +246 -0
- package/dist/server.js.map +1 -0
- package/dist/session.d.ts +47 -0
- package/dist/session.js +107 -0
- package/dist/session.js.map +1 -0
- package/dist/toolkit.d.ts +21 -0
- package/dist/toolkit.js +2 -0
- package/dist/toolkit.js.map +1 -0
- package/dist/tools.d.ts +299 -0
- package/dist/tools.js +491 -0
- package/dist/tools.js.map +1 -0
- package/guide/WORKFLOW.md +134 -0
- package/guide/assets/disclaimer.txt +1 -0
- package/guide/assets/download_data.ps1 +162 -0
- package/guide/assets/download_data.sh +143 -0
- package/guide/assets/report_template.html +597 -0
- package/guide/references/report_patterns.md +199 -0
- package/guide/references/routing.md +171 -0
- package/guide/references/style_guide.md +398 -0
- package/package.json +56 -6
- package/packs/acf/endpoints.json +114 -0
- package/packs/acf/policy.json +104 -0
- package/packs/acf/source.md +138 -0
- package/packs/actuaries/endpoints.json +82 -0
- package/packs/actuaries/policy.json +109 -0
- package/packs/actuaries/source.md +137 -0
- package/packs/bea/assets/download_bea.ps1 +182 -0
- package/packs/bea/assets/download_bea.sh +144 -0
- package/packs/bea/docs/bea_api.md +461 -0
- package/packs/bea/docs/datasets.md +157 -0
- package/packs/bea/docs/report_patterns.md +112 -0
- package/packs/bea/policy.json +170 -0
- package/packs/bea/source.md +152 -0
- package/packs/bls/assets/download_bls.ps1 +152 -0
- package/packs/bls/assets/download_bls.sh +167 -0
- package/packs/bls/docs/analysis_patterns.md +108 -0
- package/packs/bls/docs/bls_api.md +73 -0
- package/packs/bls/docs/series_ids.md +149 -0
- package/packs/bls/policy.json +238 -0
- package/packs/bls/series_ids.json +1375 -0
- package/packs/bls/source.md +156 -0
- package/packs/bts/endpoints.json +347 -0
- package/packs/bts/policy.json +94 -0
- package/packs/bts/source.md +97 -0
- package/packs/cdc/endpoints.json +197 -0
- package/packs/cdc/policy.json +83 -0
- package/packs/cdc/source.md +74 -0
- package/packs/census/endpoints.json +99 -0
- package/packs/census/policy.json +238 -0
- package/packs/census/source.md +304 -0
- package/packs/census-geocoder/endpoints.json +70 -0
- package/packs/census-geocoder/policy.json +80 -0
- package/packs/census-geocoder/source.md +53 -0
- package/packs/cfpb/endpoints.json +327 -0
- package/packs/cfpb/policy.json +119 -0
- package/packs/cfpb/source.md +96 -0
- package/packs/clinical-trials/endpoints.json +167 -0
- package/packs/clinical-trials/policy.json +84 -0
- package/packs/clinical-trials/source.md +82 -0
- package/packs/cms/endpoints.json +69 -0
- package/packs/cms/policy.json +96 -0
- package/packs/cms/source.md +112 -0
- package/packs/college-scorecard/endpoints.json +253 -0
- package/packs/college-scorecard/policy.json +106 -0
- package/packs/college-scorecard/source.md +92 -0
- package/packs/congress/endpoints.json +1701 -0
- package/packs/congress/policy.json +117 -0
- package/packs/congress/source.md +190 -0
- package/packs/dhs-ohss/endpoints.json +66 -0
- package/packs/dhs-ohss/policy.json +107 -0
- package/packs/dhs-ohss/source.md +120 -0
- package/packs/doj-news/endpoints.json +59 -0
- package/packs/doj-news/policy.json +96 -0
- package/packs/doj-news/source.md +99 -0
- package/packs/dol/endpoints.json +818 -0
- package/packs/dol/policy.json +135 -0
- package/packs/dol/source.md +181 -0
- package/packs/eia/endpoints.json +718 -0
- package/packs/eia/policy.json +112 -0
- package/packs/eia/source.md +112 -0
- package/packs/epa/endpoints.json +292 -0
- package/packs/epa/policy.json +99 -0
- package/packs/epa/source.md +99 -0
- package/packs/epa-aqs/endpoints.json +174 -0
- package/packs/epa-aqs/policy.json +96 -0
- package/packs/epa-aqs/source.md +97 -0
- package/packs/fbi/endpoints.json +1842 -0
- package/packs/fbi/policy.json +118 -0
- package/packs/fbi/source.md +108 -0
- package/packs/fda/endpoints.json +238 -0
- package/packs/fda/policy.json +121 -0
- package/packs/fda/source.md +117 -0
- package/packs/fdic/endpoints.json +417 -0
- package/packs/fdic/policy.json +83 -0
- package/packs/fdic/source.md +92 -0
- package/packs/fec/endpoints.json +708 -0
- package/packs/fec/policy.json +93 -0
- package/packs/fec/source.md +90 -0
- package/packs/fed-board/endpoints.json +89 -0
- package/packs/fed-board/policy.json +136 -0
- package/packs/fed-board/source.md +118 -0
- package/packs/federal-register/endpoints.json +143 -0
- package/packs/federal-register/policy.json +86 -0
- package/packs/federal-register/source.md +98 -0
- package/packs/fema/endpoints.json +646 -0
- package/packs/fema/policy.json +103 -0
- package/packs/fema/source.md +103 -0
- package/packs/fhfa/endpoints.json +105 -0
- package/packs/fhfa/policy.json +109 -0
- package/packs/fhfa/source.md +108 -0
- package/packs/fred/assets/download_fred.ps1 +122 -0
- package/packs/fred/assets/download_fred.sh +123 -0
- package/packs/fred/docs/analysis_patterns.md +124 -0
- package/packs/fred/docs/fred_api.md +94 -0
- package/packs/fred/docs/series.md +188 -0
- package/packs/fred/policy.json +253 -0
- package/packs/fred/source.md +142 -0
- package/packs/fsa/endpoints.json +150 -0
- package/packs/fsa/policy.json +99 -0
- package/packs/fsa/source.md +102 -0
- package/packs/govinfo/endpoints.json +520 -0
- package/packs/govinfo/policy.json +116 -0
- package/packs/govinfo/source.md +241 -0
- package/packs/gsa-calc/endpoints.json +93 -0
- package/packs/gsa-calc/policy.json +97 -0
- package/packs/gsa-calc/source.md +108 -0
- package/packs/hud/endpoints.json +147 -0
- package/packs/hud/policy.json +84 -0
- package/packs/hud/source.md +97 -0
- package/packs/ipums/assets/download_ipums.ps1 +215 -0
- package/packs/ipums/assets/download_ipums.sh +192 -0
- package/packs/ipums/docs/ipums_api.md +67 -0
- package/packs/ipums/docs/report_patterns.md +117 -0
- package/packs/ipums/docs/variables.md +284 -0
- package/packs/ipums/lib/fetch_text.json +112 -0
- package/packs/ipums/policy.json +215 -0
- package/packs/ipums/source.md +169 -0
- package/packs/irs-soi/endpoints.json +114 -0
- package/packs/irs-soi/policy.json +107 -0
- package/packs/irs-soi/source.md +124 -0
- package/packs/medicaid/endpoints.json +412 -0
- package/packs/medicaid/policy.json +108 -0
- package/packs/medicaid/source.md +136 -0
- package/packs/naep/endpoints.json +217 -0
- package/packs/naep/policy.json +100 -0
- package/packs/naep/source.md +120 -0
- package/packs/nhtsa/endpoints.json +132 -0
- package/packs/nhtsa/policy.json +93 -0
- package/packs/nhtsa/source.md +109 -0
- package/packs/nih/endpoints.json +453 -0
- package/packs/nih/policy.json +86 -0
- package/packs/nih/source.md +108 -0
- package/packs/noaa/endpoints.json +432 -0
- package/packs/noaa/policy.json +95 -0
- package/packs/noaa/source.md +88 -0
- package/packs/nrel/endpoints.json +328 -0
- package/packs/nrel/policy.json +96 -0
- package/packs/nrel/source.md +91 -0
- package/packs/nws/endpoints.json +272 -0
- package/packs/nws/policy.json +82 -0
- package/packs/nws/source.md +81 -0
- package/packs/nyfed/endpoints.json +80 -0
- package/packs/nyfed/policy.json +92 -0
- package/packs/nyfed/source.md +89 -0
- package/packs/omb/endpoints.json +460 -0
- package/packs/omb/policy.json +106 -0
- package/packs/omb/source.md +130 -0
- package/packs/open-payments/endpoints.json +298 -0
- package/packs/open-payments/policy.json +101 -0
- package/packs/open-payments/source.md +99 -0
- package/packs/opm/assets/download_opm.ps1 +125 -0
- package/packs/opm/assets/download_opm.sh +85 -0
- package/packs/opm/docs/fields.md +184 -0
- package/packs/opm/docs/opm_api.md +71 -0
- package/packs/opm/docs/report_patterns.md +83 -0
- package/packs/opm/lib/data_dictionary.csv +73 -0
- package/packs/opm/policy.json +142 -0
- package/packs/opm/source.md +137 -0
- package/packs/pbgc/endpoints.json +483 -0
- package/packs/pbgc/policy.json +94 -0
- package/packs/pbgc/source.md +95 -0
- package/packs/philfed/endpoints.json +85 -0
- package/packs/philfed/policy.json +94 -0
- package/packs/philfed/source.md +125 -0
- package/packs/port.json +287 -0
- package/packs/regulations/endpoints.json +288 -0
- package/packs/regulations/policy.json +86 -0
- package/packs/regulations/source.md +84 -0
- package/packs/sec/endpoints.json +237 -0
- package/packs/sec/policy.json +86 -0
- package/packs/sec/source.md +101 -0
- package/packs/senate-lobbying/endpoints.json +554 -0
- package/packs/senate-lobbying/policy.json +99 -0
- package/packs/senate-lobbying/source.md +100 -0
- package/packs/snapqc/endpoints.json +1426 -0
- package/packs/snapqc/policy.json +92 -0
- package/packs/snapqc/source.md +96 -0
- package/packs/treasury/catalog.json +2267 -0
- package/packs/treasury/docs/api_guide.md +245 -0
- package/packs/treasury/docs/datasets.md +56 -0
- package/packs/treasury/docs/report_patterns.md +126 -0
- package/packs/treasury/policy.json +159 -0
- package/packs/treasury/source.md +165 -0
- package/packs/treasury-yields/endpoints.json +226 -0
- package/packs/treasury-yields/policy.json +86 -0
- package/packs/treasury-yields/source.md +80 -0
- package/packs/usaspending/endpoints.json +1316 -0
- package/packs/usaspending/policy.json +109 -0
- package/packs/usaspending/source.md +103 -0
- package/packs/usda-fna/endpoints.json +427 -0
- package/packs/usda-fna/policy.json +133 -0
- package/packs/usda-fna/source.md +217 -0
- package/packs/usda-fooddata/endpoints.json +181 -0
- package/packs/usda-fooddata/policy.json +94 -0
- package/packs/usda-fooddata/source.md +105 -0
- package/packs/usda-nass/endpoints.json +324 -0
- package/packs/usda-nass/policy.json +95 -0
- package/packs/usda-nass/source.md +85 -0
- package/packs/usda-outlook/endpoints.json +86 -0
- package/packs/usda-outlook/policy.json +109 -0
- package/packs/usda-outlook/source.md +144 -0
- package/packs/usgs/endpoints.json +313 -0
- package/packs/usgs/policy.json +95 -0
- package/packs/usgs/source.md +96 -0
- package/packs/usitc/endpoints.json +74 -0
- package/packs/usitc/policy.json +111 -0
- package/packs/usitc/source.md +90 -0
- package/packs/uspto/endpoints.json +141 -0
- package/packs/uspto/policy.json +95 -0
- package/packs/uspto/source.md +101 -0
- package/packs/va/endpoints.json +414 -0
- package/packs/va/policy.json +101 -0
- package/packs/va/source.md +129 -0
- package/packs/world-bank/endpoints.json +122 -0
- package/packs/world-bank/policy.json +101 -0
- package/packs/world-bank/source.md +93 -0
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
# U.S. Treasury Fiscal Data API guide
|
|
2
|
+
|
|
3
|
+
This server's `fetch` already implements paging, filters, retries, the
|
|
4
|
+
row-count check and the `fields=` aggregation guard. Read this file to choose endpoints and rows, to
|
|
5
|
+
interpret fields, and when debugging. Contents: 1 API basics · 2 Catalog · 3 Key endpoints · 4 Gotchas ·
|
|
6
|
+
5 Manual download · 6 Recipes.
|
|
7
|
+
|
|
8
|
+
Researched 2026-10-19. Facts marked **[live]** were checked with real HTTP calls on that date. Facts marked **[docs]** come from https://fiscaldata.treasury.gov/api-documentation/. Facts marked **[unverified]** could not be confirmed. The data values below are as served on 2026-10-19.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## 1. API basics
|
|
13
|
+
|
|
14
|
+
| Item | Value |
|
|
15
|
+
|---|---|
|
|
16
|
+
| Base URL | `https://api.fiscaldata.treasury.gov/services/api/fiscal_service/` **[live]** |
|
|
17
|
+
| Full URL | base + endpoint, e.g. `.../fiscal_service/v2/accounting/od/debt_to_penny` |
|
|
18
|
+
| Versions | Each endpoint has one fixed version, `v1` or `v2`. You cannot swap them: `v1/accounting/od/debt_to_penny` returns 404, and `v3/...` returns 404. Of the 180 endpoints, 159 are v1 and 21 are v2. **[live]** Take the version from the catalog (`endpoint_txt`). |
|
|
19
|
+
| Auth | None. No key, no registration. **[docs+live]** The docs list `403 "API Key is not valid"` but no key exists. |
|
|
20
|
+
| Methods | GET only. CORS is `Access-Control-Allow-Origin: *`. **[live]** |
|
|
21
|
+
| Rate limits | None documented. 60 requests at 10 concurrent all returned 200 in 4 s, with no rate-limit or Retry-After headers. **[live]** Still keep concurrency at about 4 or less and back off on 429/5xx; whether there is a hidden limit is **[unverified]**. |
|
|
22
|
+
| Default page | `page[number]=1`, `page[size]=100` **[live]** |
|
|
23
|
+
| Max page size | **10000**. `page[size]=10001` returns 400: `"Limit '10001' is invalid. Expected an integer between 1 and 10000."` **[live]** 10,000 DTS rows came back as about 5.4 MB of JSON in about 3.5 s. |
|
|
24
|
+
| Default sort | The first column ascending, usually `record_date`, so oldest rows come first. **[docs+live]** Use `sort=-record_date` to get the latest. |
|
|
25
|
+
|
|
26
|
+
### Query parameters
|
|
27
|
+
- **`fields=`**: a comma-separated list of columns, e.g. `fields=record_date,tot_pub_debt_out_amt`. See the aggregation gotcha in section 4. Unknown field: 400 `Field 'foo' does not exist`.
|
|
28
|
+
- **`filter=`**: `field:op:value`. Combine conditions with commas, which act as AND:
|
|
29
|
+
`filter=record_date:gte:2024-01-01,record_date:lte:2024-12-31,security_type_desc:eq:Marketable`
|
|
30
|
+
- Operators: `eq`, `lt`, `lte`, `gt`, `gte`, `in`. **[docs+live]** There is no `neq`, `like` or `contains` (each returns 400 `Operator ':neq:' is not supported.`). There is no OR across fields.
|
|
31
|
+
- `in` takes a parenthesised list: `filter=record_date:in:(2024-01-02,2024-01-03)` or `classification_desc:in:(National Defense,Medicare)`. **[live]**
|
|
32
|
+
- Dates use `YYYY-MM-DD`. A bad date value such as `eq:notadate` returns **200 with empty data**, not an error. **[live]**
|
|
33
|
+
- Numeric comparisons on currency/number strings compare numerically. `tot_pub_debt_out_amt:gte:30000000000000` correctly returns 2022-01-31 first. **[live]**
|
|
34
|
+
- Values that contain commas or parentheses still work with `eq` when URL-encoded (e.g. `classification_desc:eq:Education, Training, Employment, and Social Services` and `account_type:eq:Treasury General Account (TGA) Closing Balance`). **[live]** Always URL-encode the value.
|
|
35
|
+
- Null matching: `filter=debt_held_public_amt:eq:null` matches the literal string "null". **[live]**
|
|
36
|
+
- **Repeating `filter=` does not combine.** Only the last one is applied, silently. **[live]** Put every condition in one `filter=` with commas.
|
|
37
|
+
- **`sort=`**: `sort=-record_date,src_line_nbr` sorts by several keys; `-` means descending. **[docs+live]** Unknown field: 400.
|
|
38
|
+
- **`format=`**: `json` (default), `csv`, `xml`. **[live]** An unsupported value such as `format=xlsx` silently returns JSON. CSV comes back as `text/csv` with `content-disposition: attachment; filename=<timestamp>.csv`. CSV has **no meta or links block**, so you lose total-count and must page blindly. It respects `page[size]`, and nulls appear as `"null"`. XML uses `<root-element><data><data-element>...`.
|
|
39
|
+
- **`page[number]=`, `page[size]=`**: page numbers start at 1. A page number past the end returns 400 `Page #99999 is out of range.` **[live]** URL-encoding the brackets (`page%5Bsize%5D`) also works.
|
|
40
|
+
|
|
41
|
+
### JSON response shape [live]
|
|
42
|
+
```json
|
|
43
|
+
{"data":[{"record_date":"2026-10-15","tot_pub_debt_out_amt":"40388317675071.91", ...}],
|
|
44
|
+
"meta":{"count":1, // rows on this page
|
|
45
|
+
"labels":{"record_date":"Record Date", ...}, // pretty names
|
|
46
|
+
"dataTypes":{"record_date":"DATE","tot_pub_debt_out_amt":"CURRENCY", ...},
|
|
47
|
+
"dataFormats":{"record_date":"YYYY-MM-DD","tot_pub_debt_out_amt":"$10.20", ...},
|
|
48
|
+
"total-count":8414, "total-pages":8414},
|
|
49
|
+
"links":{"self":"&page%5Bnumber%5D=1&page%5Bsize%5D=1","first":"...","prev":null,
|
|
50
|
+
"next":"&page%5Bnumber%5D=2&page%5Bsize%5D=1","last":"&page%5Bnumber%5D=8414&page%5Bsize%5D=1"}}
|
|
51
|
+
```
|
|
52
|
+
- `links.*` are **query-string fragments that start with `&`**, not full URLs, and they hold only the page parameters, not your filter, sort or fields. **[live]** Do not follow them blindly; build the next URL yourself.
|
|
53
|
+
- No `Link` HTTP header was observed, although the docs mention one. **[live]**
|
|
54
|
+
|
|
55
|
+
### Getting all rows
|
|
56
|
+
`fetch` pages with `page[size]=10000`, sorts by the date column plus `src_line_nbr` (a tiebreaker keeps
|
|
57
|
+
pages stable), and checks the row count against `meta.total-count`. Some tables are huge:
|
|
58
|
+
`treasury_offset_program` has 3.5M rows, `utf_*` 2.4M and `fip_statement_of_account_table3` 2.2M. Always
|
|
59
|
+
filter by date, and check the catalog `row_count` (`request_schema` with `search`) first.
|
|
60
|
+
|
|
61
|
+
### Data types (`meta.dataTypes`) and formats [live]
|
|
62
|
+
Every value is a **JSON string**, including numbers, and nulls are the string `"null"`. **[docs+live]**
|
|
63
|
+
|
|
64
|
+
| dataType | dataFormat hint | Meaning / parse |
|
|
65
|
+
|---|---|---|
|
|
66
|
+
| `DATE` | `YYYY-MM-DD` | date |
|
|
67
|
+
| `CURRENCY` | `$10.20` | dollars with cents → Decimal/float |
|
|
68
|
+
| `CURRENCY0` | `$1,000,000` | whole units. **In DTS this means millions of dollars**; MSPD `*_mil_amt` is millions with decimals |
|
|
69
|
+
| `CURRENCY1`, `CURRENCY3`, `CURRENCY9` | n/a | currency with 1, 3 or 9 decimals (rare) |
|
|
70
|
+
| `NUMBER` | `10.2` | float |
|
|
71
|
+
| `INTEGER` | `10` | int |
|
|
72
|
+
| `PERCENTAGE`, `PERCENTAGE_PRECISE` | `10.2%` | **already in percent units** (`"3.870"` means 3.87%) |
|
|
73
|
+
| `YEAR`/`QUARTER`/`MONTH`/`DAY` | `YYYY`/`Q`/`MM`/`DD` | strings; MONTH/DAY are zero-padded (`"09"`) |
|
|
74
|
+
| `STRING` | `String` | text; some carry trailing spaces (TOP `agency_id: "7 "`) |
|
|
75
|
+
|
|
76
|
+
Counts across the whole catalog: STRING 765, CURRENCY 451, YEAR 354, QUARTER 298, DATE 242, NUMBER 233, INTEGER 176, MONTH 151, DAY 149, CURRENCY0 129, PERCENTAGE 24, CURRENCY3 7, CURRENCY1 5, CURRENCY9 2, PERCENTAGE_PRECISE 2, and null 222 (no type in the catalog).
|
|
77
|
+
|
|
78
|
+
### Errors [live]
|
|
79
|
+
| Case | HTTP | Body |
|
|
80
|
+
|---|---|---|
|
|
81
|
+
| Unknown field in fields, filter or sort | 400 | `{"error":"Invalid Query Param","message":"Invalid query parameter: Field 'foo' does not exist. For more information, please see the documentation."}` |
|
|
82
|
+
| Unsupported operator | 400 | `... Operator ':like:' is not supported. ...` |
|
|
83
|
+
| page[size] > 10000 | 400 | `... Limit '10001' is invalid. Expected an integer between 1 and 10000. ...` |
|
|
84
|
+
| Page out of range | 400 | `... Page #99999 is out of range. ...` |
|
|
85
|
+
| Wrong endpoint or version | 404 | **HTML page** ("404 Error: The requested page could not be found"), not JSON. Do not call `json.loads` before checking the status. |
|
|
86
|
+
| Bad filter value (e.g. a malformed date) | 200 | empty `data`, `total-count: 0` |
|
|
87
|
+
| Documented but not seen | 403 "API Key is not valid", 500 | **[docs]** |
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## 2. Machine-readable catalog: YES
|
|
92
|
+
|
|
93
|
+
**`GET https://api.fiscaldata.treasury.gov/services/dtg/metadata/`** **[live]** returns a JSON array of **56 datasets** (about 1.3 MB) covering **180 endpoints with a non-null endpoint_txt, all of which returned 200 to `page[size]=1` [live]**. The site's own JS also uses it. The `?dataset_id=` parameter is ignored and the full list is always returned.
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
[ { dataset_id: "015-BFS-2014Q1-13", # MTS; DTS="015-BFS-2014Q1-03"; Debt to Penny="015-BFS-2014Q3-065"
|
|
97
|
+
title, short_description, long_description, notes_and_known_limitations, # markdown text
|
|
98
|
+
publisher, update_frequency ("Daily"|"Monthly"|"Quarterly"|"Semi-Annually"|"Annually"|"As Needed"|"... (Discontinued)"),
|
|
99
|
+
metadata_complete, dataset_path ("monthly-treasury-statement" -> website slug),
|
|
100
|
+
pdf_path, master_static_filename ("MTS_all_tables" or null), popularity_rank (1 = most popular),
|
|
101
|
+
apis: [ { api_id, table_name, table_description, row_definition, update_frequency,
|
|
102
|
+
last_updated "YYYY-MM-DD", earliest_date, latest_date, row_count,
|
|
103
|
+
api_sort_order_nbr, endpoint_txt "/services/api/fiscal_service/v1/accounting/mts/mts_table_1",
|
|
104
|
+
static_filename, api_notes_and_limitations,
|
|
105
|
+
fields: [ { column_name, definition, table_name, pretty_name,
|
|
106
|
+
data_type ("DATE","CURRENCY",...), is_required, sort_order_nbr } ] } ] } ]
|
|
107
|
+
```
|
|
108
|
+
- It has per-table fields with definitions, frequency, earliest and latest date, row count and last-updated date. That is enough to drive endpoint discovery, field validation and staleness checks.
|
|
109
|
+
- A few `apis` entries have `endpoint_txt: null`: "(Updated)" variants, Monthly Treasury Disbursements, Combined Statement, and Account of Receipts and Expenditures. These are website-only or file-only. Skip them.
|
|
110
|
+
- **`/services/dtg/metadata/summary`** **[live]**: a lighter array of 56 entries `{dataset_id, short_description, long_description, apis:[{api_id,last_updated,earliest_date,latest_date}]}`. Use it as a cheap freshness check.
|
|
111
|
+
- **`/services/dtg/publishedfiles?dataset_id=<id>`** **[live]**: a list of published report files `[{report_date, path:"/static-data/published-reports/mts/MonthlyTreasuryStatement_202609.pdf", report_group_desc, report_group_id, ...}]`. Prefix the path with `https://fiscaldata.treasury.gov`. For MTS this goes back to 1954-02-28 as PDFs, so it is useful for citing the official PDF.
|
|
112
|
+
- The docs page also has a "List of Endpoints" table ("179 rows" per the docs). It is rendered from the same data, so use the metadata endpoint instead.
|
|
113
|
+
- Separately, the Fiscal Service Data Registry (fiscal.treasury.gov/data-registry) holds element definitions. It is not needed.
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## 3. Key endpoints (all verified live with `page[size]=1`)
|
|
118
|
+
|
|
119
|
+
Paths are relative to the base URL. "Start" is the catalog `earliest_date`. Units: $ = dollars and cents; $M = millions.
|
|
120
|
+
|
|
121
|
+
| Dataset (slug) | Endpoint | Freq | Start | Holds / key fields |
|
|
122
|
+
|---|---|---|---|---|
|
|
123
|
+
| Debt to the Penny (`debt-to-the-penny`) | `v2/accounting/od/debt_to_penny` | Daily (business days) | 1993-04-01 | `record_date, debt_held_public_amt, intragov_hold_amt, tot_pub_debt_out_amt` ($). DHP and intragov are "null" through 2005-03-30. |
|
|
124
|
+
| Historical Debt Outstanding (`historical-debt-outstanding`) | `v2/accounting/od/debt_outstanding` | Annual | 1790-01-01 | `record_date, debt_outstanding_amt` ($). Early years are dated Jan 1; recent ones are dated Sep 30 (fiscal year end). |
|
|
125
|
+
| MTS (`monthly-treasury-statement`) Table 1 | `v1/accounting/mts/mts_table_1` | Monthly | 2015-03-31 | Summary of receipts, outlays and deficit by month: `current_month_gross_rcpt_amt, current_month_gross_outly_amt, current_month_dfct_sur_amt` ($) + hierarchy cols |
|
|
126
|
+
| MTS Table 2 | `v1/accounting/mts/mts_table_2` | Monthly | 2015-03-31 | Budget and off-budget results, financing |
|
|
127
|
+
| MTS Table 3 | `v1/accounting/mts/mts_table_3` | Monthly | 2015-03-31 | Summary receipts and outlays |
|
|
128
|
+
| MTS Table 4 | `v1/accounting/mts/mts_table_4` | Monthly | 2015-03-31 | Receipts: `current_month_{gross_rcpt,refund,net_rcpt}_amt`, `current_fytd_*`, `prior_fytd_*` ($) |
|
|
129
|
+
| MTS Table 5 | `v1/accounting/mts/mts_table_5` | Monthly | 2015-03-31 | Outlays by agency, bureau and program: `current_month_{gross_outly,app_rcpt,net_outly}_amt`, `current_fytd_*`, `prior_fytd_*` ($). About 810 rows per month. |
|
|
130
|
+
| MTS Table 5m | `v1/accounting/mts/mts_table_5m` | Monthly | 2015-03-31 | Receipts offset against outlays |
|
|
131
|
+
| MTS Table 6, 6a–6e | `v1/accounting/mts/mts_table_6` … `mts_table_6e` | Monthly | 2015-03-31 | Means of financing, agency borrowing, investments, loan financing |
|
|
132
|
+
| MTS Table 7 | `v1/accounting/mts/mts_table_7` | Monthly | 2015-03-31 | Receipts and outlays by month, Oct to Sep across the FY |
|
|
133
|
+
| MTS Table 8 | `v1/accounting/mts/mts_table_8` | Monthly | 2015-03-31 | Trust fund impact |
|
|
134
|
+
| MTS Table 9 | `v1/accounting/mts/mts_table_9` | Monthly | 2015-03-31 | Receipts by source and outlays by function: `current_month_rcpt_outly_amt, current_fytd_rcpt_outly_amt, prior_fytd_rcpt_outly_amt` ($). 33 rows per month. |
|
|
135
|
+
| MTS Table 9 subfunctions | `v1/accounting/mts/mts_table_9_outlays_functions_subfunctions` | Monthly | 2015-03-31 | Outlays by function and subfunction |
|
|
136
|
+
| MTS long history | `v1/accounting/mts/mts_receipts_outlays_deficit_surplus` | Monthly | **1980-10-31** | `record_date, amt_category` (Receipts / Outlays / Deficit/Surplus (-) / Borrowing from the Public / Reduction of Operating Cash / By Other Means), `mil_amt` (**$M**). The simplest monthly deficit series. |
|
|
137
|
+
| MTS distributed offsetting receipts | `v1/accounting/mts/mts_distributed_offsetting_receipts` | Monthly | 2024-10-31 | |
|
|
138
|
+
| DTS (`daily-treasury-statement`) Operating Cash Balance | `v1/accounting/dts/operating_cash_balance` | Daily | 2005-10-03 | `account_type, close_today_bal, open_today_bal, open_month_bal, open_fiscal_year_bal` (**$M**), `table_nbr, table_nm, sub_table_name`. See the 2022 change in section 4. |
|
|
139
|
+
| DTS Deposits and Withdrawals | `v1/accounting/dts/deposits_withdrawals_operating_cash` | Daily | 2005-10-03 | `account_type, transaction_type` (Deposits/Withdrawals), `transaction_catg, transaction_catg_desc, transaction_today_amt, transaction_mtd_amt, transaction_fytd_amt` (**$M**) |
|
|
140
|
+
| DTS Public Debt Transactions | `v1/accounting/dts/public_debt_transactions` | Daily | 2005-10-03 | `transaction_type` (Issues/Redemptions), `security_market, security_type, security_type_desc, transaction_{today,mtd,fytd}_amt` ($M) |
|
|
141
|
+
| DTS Adjustment to cash basis | `v1/accounting/dts/adjustment_public_debt_transactions_cash_basis` | Daily | 2005-10-03 | |
|
|
142
|
+
| DTS Debt Subject to Limit | `v1/accounting/dts/debt_subject_to_limit` | Daily | 2005-10-03 | `debt_catg, debt_catg_desc, close_today_bal, open_today_bal, open_month_bal, open_fiscal_year_bal` ($M) |
|
|
143
|
+
| DTS Income Tax Refunds | `v1/accounting/dts/income_tax_refunds_issued` | Daily | 2005-10-03 | |
|
|
144
|
+
| DTS Federal Tax Deposits | `v1/accounting/dts/federal_tax_deposits` | Daily | 2005-10-03 | **Ends 2023-02-13** |
|
|
145
|
+
| DTS Short-Term Cash Investments | `v1/accounting/dts/short_term_cash_investments` | Daily | 2005-10-03 | **Ends 2023-02-13** |
|
|
146
|
+
| DTS Inter-Agency Tax Transfers | `v1/accounting/dts/inter_agency_tax_transfers` | Daily | **2023-02-14** | |
|
|
147
|
+
| Average Interest Rates (`average-interest-rates-treasury-securities`) | `v2/accounting/od/avg_interest_rates` | Monthly | 2001-01-31 | `security_type_desc` (Marketable / Non-marketable / Interest-bearing Debt), `security_desc`, `avg_interest_rate_amt` (PERCENTAGE, in %). Includes "Total Marketable", "Total Non-marketable" and "Total Interest-bearing Debt" rows; "Total Marketable" leaves out TIPS and FRNs. |
|
|
148
|
+
| Interest Expense (`interest-expense-debt-outstanding`) | `v2/accounting/od/interest_expense` | Monthly | 2010-05-31 | `expense_catg_desc, expense_group_desc, expense_type_desc, month_expense_amt, fytd_expense_amt` ($). Detail rows only, with no total rows seen. |
|
|
149
|
+
| Rates of Exchange (`treasury-reporting-rates-exchange`) | `v1/accounting/od/rates_of_exchange` | Quarterly | 2001-03-31 | `country, currency, country_currency_desc` (e.g. `Euro Zone-Euro`), `exchange_rate` (**foreign units per 1 USD**), `effective_date`. About 170 rows per quarter. Also `rates_of_exchange_source`. |
|
|
150
|
+
| MSPD (`monthly-statement-public-debt`) | `v1/debt/mspd/mspd_table_1` (summary), `_2` (statutory limit), `_3`, `_3_market`, `_3_nonmarket` (CUSIP detail), `_4`, `_5` (STRIPS) | Monthly | 2001-01-31 | Table 1: `security_type_desc, security_class_desc, debt_held_public_mil_amt, intragov_hold_mil_amt, total_mil_amt` (**$M**). 3_market: `security_class2_desc` (CUSIP), `interest_rate_pct, yield_pct, issue_date, maturity_date, issued_amt, outstanding_amt` ($M). |
|
|
151
|
+
| Auctions (`treasury-securities-auctions-data`) | `v1/accounting/od/auctions_query` | As needed | 1979-11-15 | About 120 cols: `record_date` (= issue date), `cusip, security_type, security_term, auction_date, issue_date, maturity_date, offering_amt, high_yield, high_discnt_rate, high_investment_rate, int_rate, bid_to_cover_ratio, total_tendered, total_accepted, primary_dealer_accepted, direct_bidder_accepted, indirect_bidder_accepted, soma_accepted, reopening, ...` |
|
|
152
|
+
| Upcoming Auctions | `v1/accounting/od/upcoming_auctions` | As needed | 2024-03-08 | |
|
|
153
|
+
| Record-Setting Auction (`record-setting-auction-data`) | `v2/accounting/od/record_setting_auction` | As needed | snapshot (20 rows) | `security_type, security_term, low_rate_pct, first_auc_date_low_rate, high_rate_pct, high_offer_amt, high_bid_cover_ratio, ...`. A snapshot: record_date = today. |
|
|
154
|
+
| Gift Contributions (`gift-contributions-reduce-debt-held-by-public`) | `v2/accounting/od/gift_contributions` | Monthly | 1996-09-30 | `record_date, contribution_amt` ($) |
|
|
155
|
+
| Schedules of Federal Debt | `v1/accounting/od/schedules_fed_debt`, `..._fytd`; daily: `schedules_fed_debt_daily_activity`, `..._daily_summary` | Monthly/Daily | 2005-10-31 | $M; lags about 1 month |
|
|
156
|
+
| Revenue Collections (`revenue-collections-management`) | `v2/revenue/rcm` | Daily | 2004-10-01 | `electronic_category_desc, channel_type_desc, tax_category_desc, net_collections_amt` ($) |
|
|
157
|
+
| TROR (`treasury-report-on-receivables`) | `v2/debt/tror` | Quarterly | 2016-12-31 | Per agency × receivable type, about 230 `*_amt` / `*_cnt` columns. Also `v2/debt/tror/data_act_compliance` (120-day referral compliance). |
|
|
158
|
+
| Treasury Offset Program (`top-treasury-offset-program`) | `v1/debt/treasury_offset_program` | Monthly | 2010-10-01 | 3.5M rows: `record_date, net_offset_cnt, net_offset_amt, agency, payment_type, debt_category, state_cd, fiscal_year, ...`. Filter it. |
|
|
159
|
+
| Judgment Fund (`judgment-fund-report-to-congress`) | `v2/payments/jfics/jfics_congress_report` | Annual | 2009-09-30 | Per payment: `defendant_agency_nm, judgment_type_cd, payment_sent_dt, confirmed_payment_amt, principal_amt, attorneys_fee_amt, interest_amt, ...` |
|
|
160
|
+
| Federal Credit Similar Maturity Rates (`fed-credit-similar-maturity-rates`) | `v1/accounting/od/federal_maturity_rates` | Annual | 1992-09-30 | `one_year_or_less, between_1_and_5_years, between_5_and_10_years, between_10_and_20_years, twenty_years_or_greater` (NUMBER, %) |
|
|
161
|
+
| Savings Bonds Value Files | `v2/accounting/od/sb_value` | Semi-annual | 1992-05-31 | **No `record_date`.** Columns: `redemp_period, redemption_year, redemption_month, series_cd, issue_year, issue_jan_amt ...` |
|
|
162
|
+
| I Bonds Interest Rates | `v1/accounting/od/i_bonds_interest_rates` | Semi-annual | 1998-09-01 | **No `record_date`.** Columns: `earning_period, earning_period_start, ..., fixed_rate, semi_annual_inflation_rate, combined_rate` |
|
|
163
|
+
| Savings Bonds Issues/Redemptions | `v1/accounting/od/savings_bonds_report`, `savings_bonds_pcs`, `savings_bonds_mud` | Monthly | 1998–2019 | report: `series_cd, bonds_issued_cnt, bonds_redeemed_cnt, bonds_out_cnt, ...` |
|
|
164
|
+
| Accrual Savings Bonds Redemption Tables | `v2/accounting/od/redemption_tables` | discontinued 2023-05 | 1999-03-31 | no record_date |
|
|
165
|
+
| U.S. Treasury-Owned Gold | `v2/accounting/od/gold_reserve` | Monthly | 2012-01-31 | `facility_desc, form_desc, location_desc, fine_troy_ounce_qty, book_value_amt` |
|
|
166
|
+
| TIPS and CPI | `v1/accounting/od/tips_cpi_data_detail`, `..._summary` | Monthly | 1998/2008 | no record_date (`index_date`, `cusip`) |
|
|
167
|
+
| Financial Report of the U.S. Government | `v2/accounting/od/statement_net_cost`, `v2/accounting/od/balance_sheets`, `v1/accounting/od/{net_position,social_insurance,long_term_projections,...}` | Annual | 1995+ | |
|
|
168
|
+
| Treasury Bulletin | `v1/accounting/tb/{pdo1_...,ofs1_...,ofs2_estimated_ownership_treasury_securities,ffo5_internal_revenue_by_state,...}` | Quarterly | 2021 | ownership of Treasuries (OFS-2), receipts by state (FFO-5) |
|
|
169
|
+
| Buybacks | `v1/accounting/od/buybacks_operations`, `buybacks_security_details` | As needed | 2000-03-09 | date column is `operation_date` (no record_date) |
|
|
170
|
+
| Others in the catalog | Treasury Certified Interest Rates (`tcir_*`), SLGS (`slgs_*`), FRN daily indexes, Federal Investments/Borrowings Program (`fip_*`, `fbp_*`), UTF (`utf_*`, which use `eff_date`), Treasury Managed Accounts (`tma_*`), Title XII advances, Receipts by Department, Electronic Securities Transactions (`securities_*`), Trust-fund reports | | | Use the catalog |
|
|
171
|
+
|
|
172
|
+
Endpoints without `record_date` (sorting or filtering on it gives 400): `buybacks_*` (`operation_date`), `i_bonds_interest_rates`, `sb_value`, `redemption_tables`, `tips_cpi_data_*`, `utf_*` (`eff_date`). **[live/catalog]** Read the catalog `fields` to find the date column.
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
## 4. Gotchas (all verified live unless marked)
|
|
177
|
+
|
|
178
|
+
**Values and units**
|
|
179
|
+
1. **Every value is a string**, and nulls are the literal string `"null"` in JSON, CSV and XML. `fetch` writes them as empty cells; in hand-made reads, treat "null" as missing before converting to numbers. D rows (data_type_cd "D") can also have "null" amounts, e.g. MTS Table 4 "Individual Income Taxes" header-like detail rows.
|
|
180
|
+
2. **Units differ by dataset.** Debt to the Penny, Historical Debt, MTS tables 1–9, interest expense, gift contributions and RCM are in **dollars and cents** (e.g. `"404371348973.70"` = $404.4B). **DTS (all tables) is in millions** (CURRENCY0, "rounded to the nearest million"). MSPD `*_mil_amt` and `mts_receipts_outlays_deficit_surplus.mil_amt` are **millions**. Check `meta.dataTypes` and the field name (`mil_`). Percentages are already in percent.
|
|
181
|
+
3. **Deficit sign conventions conflict.** MTS Table 1 `current_month_dfct_sur_amt` is **positive for a deficit and negative for a surplus** (per the field definition and data: April shows a negative value). `mts_receipts_outlays_deficit_surplus` "Deficit/Surplus (-)" is also positive for a deficit. MTS Table 5's "Total Surplus (+) or Deficit (-)" row is **negative for a deficit** (-1,992,473,224,352.42 for FY2026).
|
|
182
|
+
|
|
183
|
+
**Fiscal year and dates**
|
|
184
|
+
4. The fiscal year runs Oct 1 to Sep 30. `record_fiscal_year` is the FY of `record_date` (e.g. 2026-10-15 is FY 2027, Q1). `record_date` = "the date that data was published", which for MTS is the month-end the statement covers.
|
|
185
|
+
5. **MTS Table 1 repeats history at every record_date.** Each monthly release has a "FY prior" block and a "FY current" block with every month so far (28 rows in the Sept 2026 release). So `filter=classification_desc:eq:October,record_fiscal_year:eq:2026` returns 24 rows: 12 releases × 2 FYs. To get the FY a month belongs to, follow `parent_id` to the `S` row whose `classification_desc` is "FY 2026". To build a monthly series, take **only the latest record_date** (it carries revised values), or take the current-FY block from each release.
|
|
186
|
+
6. **Revisions happen.** October 2025 outlays were 688,721,399,756.50 in the Oct–Dec 2025 releases and 688,704,092,972.07 from the Jan 2026 release onward. The latest release wins. `classification_id` changes in every publication (per its definition), so do not join across record_dates on it; join on `src_line_nbr`, `classification_desc` or `line_code_nbr` instead (those are stable **[unverified]** across years).
|
|
187
|
+
7. Several MTS tables carry `current_month_*`, `current_fytd_*` and `prior_fytd_*`. Do not sum fytd values across months.
|
|
188
|
+
|
|
189
|
+
**MTS hierarchy and double counting**
|
|
190
|
+
8. Hierarchy columns: `parent_id` (the parent's classification_id, or "null" at the top), `classification_id`, `classification_desc`, `table_nbr`, **`src_line_nbr`** (the row number on the printed MTS table, i.e. the print line; integer, 1..N within a table and release), `print_order_nbr`, `line_code_nbr` (10, 20, 30… sequence), `sequence_level_nbr` (depth 1–5), `sequence_number_cd` (an outline number such as `1.3.2`).
|
|
191
|
+
- `data_type_cd`: **D** = detail, **S** = sub-header (amounts "null"), **T** = total.
|
|
192
|
+
- `record_type_cd`: Table 1 MTH = month, SL = special line. Table 4 RSG = receipt source group, SRS = source sub-row. Table 5 A = Agency, B = Bureau, BG = Bureau Group, C = Chapter, P = Program, SL = Special Line, UOR/UORG = undistributed offsetting receipts. Table 9 F = Function, RSG, SL.
|
|
193
|
+
- In DTS and Debt to the Penny, `src_line_nbr` is likewise the row on the published report.
|
|
194
|
+
- The same letter can be a value of two code columns (`T` is a `data_type_cd`; Table 1's totals have `record_type_cd` SL). Filter on the column the value is in; `request_schema` with `search: "<endpoint> <filter JSON> values"` shows the combinations.
|
|
195
|
+
- **Table 1 holds two fiscal years per release** [live, 2026-09-30 release]: block 1 = prior FY (S header "FY 2025", 12 MTH rows, a "Year-to-Date" row with `record_type_cd` SL and `data_type_cd` T, `sequence_number_cd` 1.13), block 2 = current FY (the same, 2.x). The September release's 2.13 row is the current fiscal year as first published; the next September's 1.13 row is the same year as revised. Check: receipts − outlays = −deficit on every Year-to-Date row.
|
|
196
|
+
- Generally, one release can carry several periods, as columns (`current_month_*`, `current_fytd_*`, `prior_fytd_*`; DTS today / mtd / fytd) or as row blocks (Table 1). Repeated (record_date, classification_desc) keys are the usual symptom.
|
|
197
|
+
9. **Summing all rows double counts.** Table 9 for Sep 2026 has 33 rows: a "Receipts" S header, 9 RSG D rows (6 top-level sources plus the 3 children of the Social Insurance S header), a "Total" T row, a "Net Outlays" S header, 19 function D rows, and a "Total" T row. Use `data_type_cd == "D"` for components and the `T` row named "Total" for totals. Table 5: the sum of all D rows exactly equals the "Total Outlays" T row (7,395,799,983,313.23), but adding the T rows ("Total--Department of ...", "Total On-Budget"/"Off-Budget", "Total Surplus...") inflates it about 4×. **Table 4 is different**: its D rows do not sum to total receipts, because some components only carry amounts on T rows (e.g. "Total -- Individual Income Taxes"). Read the T/SL rows "Total -- Receipts", "Total -- On-Budget" and "Total -- Off-Budget" instead. For receipts by source, prefer Table 9.
|
|
198
|
+
10. **The `fields=` subset aggregates.** If the fields you request leave out columns that make rows unique, the API **groups and sums**. Examples: `mts_table_9?fields=record_date,current_month_rcpt_outly_amt&filter=record_date:eq:2026-09-30` returned one row of 2,285,298,771,157.00, which is receipts + outlays + totals all double-summed. DTS `fields=record_date,transaction_type,transaction_today_amt` returned Deposits 898,351, which is the details plus the "Total Deposits" row (449,175 × 2). The docs mention this. Debt to the Penny with `fields=record_fiscal_year,tot_pub_debt_out_amt` did *not* aggregate, so the behavior varies by table. **Rule: always include record_date and the row-identity columns (`src_line_nbr` or the description columns) in `fields`, or omit `fields`.**
|
|
199
|
+
|
|
200
|
+
**DTS structure changes**
|
|
201
|
+
11. **Operating Cash Balance changed format on 2022-04-18** (first "Treasury General Account (TGA) Closing Balance" row). Before: one row per account (`Federal Reserve Account` until 2021-09-30, then `Treasury General Account (TGA)` from 2021-10-01, plus `Supplementary Financing Program Account` and `Short-Term Cash Investments (Table V)`), with `close_today_bal` = the closing balance. From 2022-04-18 there are 4 rows: "Treasury General Account (TGA) Opening Balance", "Total TGA Deposits (Table II)", "Total TGA Withdrawals (Table II) (-)" and "Treasury General Account (TGA) Closing Balance". **`close_today_bal` is "null"** and the day's amount is in **`open_today_bal`**, which acts as a "today" column; open_month_bal and open_fiscal_year_bal act as MTD and FYTD. A TGA balance series must switch logic at 2022-04-18: before, the TGA/FRA row's `close_today_bal`; after, the "Closing Balance" row's `open_today_bal`.
|
|
202
|
+
12. In DTS Deposits/Withdrawals, from 2022-04-18 there are extra total rows with `account_type` "Treasury General Account Total Deposits" / "... Total Withdrawals" (`transaction_catg` "null"). Detail rows have `account_type` "Treasury General Account (TGA)". Before that, account_type was "Federal Reserve Account" and there were also "Short-Term Cash Investments" rows. Detail sums differ from the totals by about ±1 (rounding to millions). The category text changed too: "Public Debt Cash Issues (Table III-B)" became "(Table IIIB)". Deposits and withdrawals include gross **Public Debt Cash Issues/Redemptions**; exclude these for "operating" flows. Match categories with fuzzy or normalized text.
|
|
203
|
+
13. Federal Tax Deposits and Short-Term Cash Investments tables end 2023-02-13; Inter-Agency Tax Transfers starts 2023-02-14. The DTS notes say DTS debt figures are in millions and **do not total TPDO**. Use Debt to the Penny for total debt.
|
|
204
|
+
14. Debt totals differ by dataset because of FFB debt and rounding. Debt to the Penny is to the cent, while MSPD, DTS and Schedules of Federal Debt are in millions, and Schedules excludes FFB debt (per the catalog's TPDO disclaimer).
|
|
205
|
+
|
|
206
|
+
**Filter values with special characters** [live, 2026-10-20]
|
|
207
|
+
10a. A filter value containing `&` or `,` matches nothing, even URL-encoded (`interest_expense` "Foreign Series Notes & Bonds": 0 rows, 2 exist). Inside `in:(...)` a value with `,` or parentheses is **silently dropped** ("Treasury Floating Rate Notes (FRN)" in a list: 1 row instead of 4). `eq` with parentheses works. `fetch` applies such conditions locally instead (it downloads under the rest of the filter, then applies them; README and `fetch_spec.json` record it as `local_filter`). In hand-written API URLs, leave such values out and filter afterwards.
|
|
208
|
+
|
|
209
|
+
**CSV output**
|
|
210
|
+
15a. **API CSV prefixes negative numbers with an apostrophe** (`'-334128106.88`), a spreadsheet formula-injection guard. JSON does not. `fetch` reads JSON, and `ingest` strips the apostrophe; any other CSV reader would turn every negative value into text or NaN. [live]
|
|
211
|
+
|
|
212
|
+
**Other**
|
|
213
|
+
15. FX: a quarter can have **several rows per currency**. Amendments keep the quarter's `record_date` but have a later `effective_date` (102 such rows since 2023, e.g. Argentina-Peso effective 2023-05-15 under record_date 2023-03-31). Deduplicate on (country_currency_desc, record_date) by taking the max effective_date, or filter on effective_date.
|
|
214
|
+
16. Auctions: `record_date` is the issue date, and upcoming or announced auctions appear with "null" results (`high_yield`, `bid_to_cover_ratio`, ...). Filter `auction_date:lte:<today>` or drop rows where results are null. Some numeric-looking columns are typed STRING (`price_per100`, `high_price`).
|
|
215
|
+
17. Record-Setting Auction is a snapshot table, and its record_date is the refresh date.
|
|
216
|
+
18. A single endpoint can be huge. Check the catalog `row_count` before pulling and use date filters.
|
|
217
|
+
19. A non-JSON error page (HTML 404) is possible, so check the status before parsing.
|
|
218
|
+
20. Treasury Bulletin, Financial Report and Judgment Fund are annual or quarterly and lag by months. Always report `latest_date` from the catalog or the data rather than assuming the data is current.
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
222
|
+
## 5. Website and manual download fallback
|
|
223
|
+
|
|
224
|
+
- **Dataset page URL pattern:** `https://fiscaldata.treasury.gov/datasets/<dataset_path>/`, where `dataset_path` comes from the catalog. Examples: `/datasets/monthly-treasury-statement/`, `/datasets/daily-treasury-statement/`, `/datasets/debt-to-the-penny/`, `/datasets/average-interest-rates-treasury-securities/`, `/datasets/treasury-reporting-rates-exchange/`, `/datasets/historical-debt-outstanding/`, `/datasets/monthly-statement-public-debt/`, `/datasets/treasury-securities-auctions-data/`, `/datasets/interest-expense-debt-outstanding/`. The MTS page fetched live (200).
|
|
225
|
+
- **Download button:** each dataset page has a "Download" panel. You choose one table or "All Data Tables", a date range and a format (**CSV, JSON or XML**), and the result is a **zip** for multi-table or large requests. From the site JS (**[live]**, read from the source; the end-to-end flow was **[unverified]**): the browser opens a WebSocket to `wss://downloads.fiscaldata.treasury.gov/main`, sends {apiIds, dateRange, fileTypes}, polls `https://fiscaldata.treasury.gov/static-data/downloads/zip/<requestToken>/status.json`, then downloads `https://fiscaldata.treasury.gov<final_file_name>`. Zip names derive from `master_static_filename` (e.g. `MTS_all_tables`, `DTS_all_tables`, `MSPD_all_tables`). This is **not a stable direct-file URL**, so it suits manual use only.
|
|
226
|
+
- The "API Quick Guide" CSV link on dataset pages is just `https://api.fiscaldata.treasury.gov/services/api/fiscal_service/<endpoint>?format=csv` (from the site JS), so it returns only the first 100 rows unless the user adds `&page[size]=10000&page[number]=N`.
|
|
227
|
+
- CSV from the website versus the API: website downloads are whole-table or date-range files with no pagination limit, and their headers use the **same snake_case column names** with "null" strings. The site may also offer pretty-name headers **[unverified]**. API CSV is paginated, has no meta, and its filename is a timestamp.
|
|
228
|
+
- **Published PDFs** (the official statements) can be listed with `/services/dtg/publishedfiles?dataset_id=<id>` and live at `https://fiscaldata.treasury.gov/static-data/published-reports/...`. The MTS PDF for 2026-09 returned a binary PDF **[live]**.
|
|
229
|
+
- **Fallback instruction for users without API access:** "Open https://fiscaldata.treasury.gov/datasets/<slug>/, click *Download*, choose the table, date range and *CSV*, unzip, and give the CSV to the assistant." `ingest` accepts those CSVs: same column names, values as strings, "null" for missing.
|
|
230
|
+
|
|
231
|
+
---
|
|
232
|
+
|
|
233
|
+
## 6. Recipes
|
|
234
|
+
|
|
235
|
+
- Latest debt: `v2/accounting/od/debt_to_penny?sort=-record_date&page[size]=1`
|
|
236
|
+
- FY deficit to date (latest): `v1/accounting/mts/mts_table_1?sort=-record_date,src_line_nbr&page[size]=40`, then keep rows with max record_date and take the "Year-to-Date" row (`record_type_cd` SL, `data_type_cd` T) with `sequence_number_cd` 2.13 (the current fiscal year).
|
|
237
|
+
- Annual deficits with revisions: `v1/accounting/mts/mts_table_1?filter=record_calendar_month:eq:09,classification_desc:eq:Year-to-Date&page[size]=10000`. Take each fiscal year from the next September's 1.13 row (revised), and the latest year from its own 2.13 row.
|
|
238
|
+
- Long monthly deficit series: `v1/accounting/mts/mts_receipts_outlays_deficit_surplus?filter=amt_category:eq:Deficit/Surplus (-)&page[size]=10000` ($M, from FY1981).
|
|
239
|
+
- Outlays by function, FYTD: `v1/accounting/mts/mts_table_9?filter=record_date:eq:<latest>,record_type_cd:eq:F`
|
|
240
|
+
- Receipts by source: the same call with `record_type_cd:eq:RSG,data_type_cd:eq:D`
|
|
241
|
+
- TGA closing balance since 2022-04-18: `v1/accounting/dts/operating_cash_balance?filter=account_type:eq:Treasury General Account (TGA) Closing Balance&fields=record_date,open_today_bal&page[size]=10000`
|
|
242
|
+
- Average rate on all interest-bearing debt: `v2/accounting/od/avg_interest_rates?filter=security_desc:eq:Total Interest-bearing Debt&page[size]=10000`
|
|
243
|
+
- FX for a currency: `v1/accounting/od/rates_of_exchange?filter=country_currency_desc:eq:Euro Zone-Euro&sort=-record_date`
|
|
244
|
+
- Completed 10-year note auctions: `v1/accounting/od/auctions_query?filter=security_term:eq:10-Year,security_type:eq:Note,auction_date:lte:<today>&sort=-auction_date`. This returned only original issues; the latest was 2026-08-12. Reopenings carry terms like "9-Year 10-Month", so filter on `original_security_term:eq:10-Year` to include them, and add `inflation_index_security:eq:No`: TIPS are `security_type` "Note" too (`security_type:eq:TIPS` matches nothing), so without it real-yield TIPS auctions mix in. **[live 2026-10-21]**: 502 rows with TIPS, 362 nominal notes; the 2026-09-17 auction is a TIPS reopening, 2026-10-07 a nominal one. `bid_to_cover_ratio` is the published ratio, which excludes SOMA (Federal Reserve) tenders: `total_tendered / total_accepted` includes them and comes out lower (Jan 2025: 2.25 against the published 2.53).
|
|
245
|
+
- Freshness check: `/services/dtg/metadata/summary`, then compare `latest_date`.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Which dataset answers which question
|
|
2
|
+
|
|
3
|
+
Start here to pick endpoints. Each row says whether the measure is a **stock** (a level at a date:
|
|
4
|
+
take the end-of-period value or an average) or a **flow** (an amount over a period: sum months, or
|
|
5
|
+
read a fiscal-year-to-date row). Confirm paths and field names live with `request_schema` (`search: "<words>"`, then
|
|
6
|
+
`search: "<endpoint>"` for its fields); details and pitfalls are in `api_guide.md` (section numbers in brackets).
|
|
7
|
+
|
|
8
|
+
Units: **$** = dollars and cents; **$M** = millions of dollars; **%** = already in percent.
|
|
9
|
+
|
|
10
|
+
"Rows to use" always names the column with the value (`data_type_cd` = T, not "the T row"): the same
|
|
11
|
+
letter can be a value in two columns. Check live with `request_schema` and `search: "<endpoint> <filter JSON> values"`;
|
|
12
|
+
each download's `data/treasury/README.md` also lists the values found in every code and description column.
|
|
13
|
+
|
|
14
|
+
## Question → endpoint
|
|
15
|
+
|
|
16
|
+
| Question | Endpoint | Rows to use | Stock/flow | Units | Pitfalls |
|
|
17
|
+
|---|---|---|---|---|---|
|
|
18
|
+
| Total federal debt, debt held by the public, intragovernmental holdings (daily, since 1993) | `v2/accounting/od/debt_to_penny` | one row per business day | stock | $ | DHP and intragov are null before 2005-03-31; the latest day lags one business day |
|
|
19
|
+
| Debt at each fiscal year end, back to 1790 | `v2/accounting/od/debt_outstanding` | one row per year | stock | $ | early years dated Jan 1, recent years Sep 30; definitions change over two centuries |
|
|
20
|
+
| Debt by security type (bills, notes, bonds, TIPS, FRNs; marketable vs nonmarketable), monthly | `v1/debt/mspd/mspd_table_1` | `security_type_desc`, `security_class_desc`; skip "Total ..." rows when summing | stock | $M | totals differ from Debt to the Penny by rounding and FFB debt [4.14] |
|
|
21
|
+
| Debt subject to the statutory limit | `v1/debt/mspd/mspd_table_2` (monthly) or `v1/accounting/dts/debt_subject_to_limit` (daily) | `debt_catg_desc` | stock | $M | |
|
|
22
|
+
| Monthly receipts, outlays, deficit (long series since FY1981) | `v1/accounting/mts/mts_receipts_outlays_deficit_surplus` | `amt_category` = Receipts / Outlays / Deficit/Surplus (-) | flow | $M | deficit is **positive** in this table [4.3] |
|
|
23
|
+
| Monthly receipts, outlays, deficit (since FY2015, more detail) | `v1/accounting/mts/mts_table_1` | months: the **latest** `record_date` only, `record_type_cd` = MTH; full fiscal year: September `record_date`, `classification_desc` = "Year-to-Date" (`record_type_cd` = SL, `data_type_cd` = T) | flow | $ | each release holds **two fiscal-year blocks**: `sequence_number_cd` 1.x = prior FY (as revised), 2.x = current FY, so "Year-to-Date" appears twice per release [4.8]; releases repeat prior months and revise them: never stack releases [4.5, 4.6]; deficit positive [4.3] |
|
|
24
|
+
| Receipts by source (individual, corporate, payroll, excise, customs ...) and outlays by function (defense, Social Security, Medicare, net interest ...) | `v1/accounting/mts/mts_table_9` | September `record_date` for a full FY; `data_type_cd` = D for components, `data_type_cd` = T with `classification_desc` = "Total" for totals; `record_type_cd` = RSG for receipts, F for functions | flow (`current_fytd_*` is cumulative) | $ | Social Insurance is an S header with 3 D children; never sum all rows [4.9] |
|
|
25
|
+
| Outlays by function and subfunction | `v1/accounting/mts/mts_table_9_outlays_functions_subfunctions` | D rows at the wanted `sequence_level_nbr` | flow | $ | |
|
|
26
|
+
| Receipts detail (gross, refunds, net) | `v1/accounting/mts/mts_table_4` | totals: the rows with `classification_desc` starting "Total -- " (`data_type_cd` = T or `record_type_cd` = SL) | flow | $ | **D rows do not sum to the total** in Table 4 [4.9]; prefer Table 9 for receipts by source |
|
|
27
|
+
| Outlays by agency, bureau, program | `v1/accounting/mts/mts_table_5` | `record_type_cd` A = agency totals; D rows sum to "Total Outlays" | flow | $ | Table 5's "Total Surplus (+) or Deficit (-)" is **negative** for a deficit [4.3]; never add T rows to D rows |
|
|
28
|
+
| Interest expense on the public debt (gross, by security type) | `v2/accounting/od/interest_expense` | `expense_catg_desc`, `expense_group_desc`, `expense_type_desc`; `month_expense_amt` per month or September `fytd_expense_amt` | flow | $ | detail rows only (no total rows): the sum of **all** rows is the total interest expense (FY2024: $1,133.0 billion). From FY2025 it includes a GAS line "Restoration of Interest" ($4.4 billion in FY2025, $0.4 billion in FY2026) that MTS Table 5 "Interest on Treasury Debt Securities (Gross)" leaves out: drop it to match MTS. Marketable TIPS interest is the sum of the TIPS lines, inflation compensation included ("Int. Expense Inflation Compensation (TIPS)"); the GAS "Inflation Compensation" line is not TIPS, so never select TIPS with a substring such as "Inflation". Marketable = the Treasury Bills, Notes, Bonds, TIPS (both TIPS lines) and FRN lines; the other public-issue lines are nonmarketable held by the public (Savings Bonds, State & Local Government (SLGS), Domestic, Foreign and REA Series) or miscellaneous (Matured Debt, Limited Payability, Recertified Agency Payments), about $8 billion in FY2026: public issues are not all marketable. Check the lines with `--values`. Two categories: INTEREST EXPENSE ON PUBLIC ISSUES (debt held by the public) and ON GOVT ACCOUNT SERIES (trust funds; intragovernmental). The GAS groups "ACCRUAL BASIS GAS EXPENSE" (zero-coupon amortized discount only) and "CASH BASIS GAS PAYMENTS" are different line items, not two versions of the same amount: keep both. Some lines are negative (premiums, collected discounts). Total = gross interest; MTS "Net Interest" (Table 9) is the budget's **net** measure (nets out trust-fund interest and other receipts): say which one is used |
|
|
29
|
+
| Average interest rate on the debt | `v2/accounting/od/avg_interest_rates` | `security_desc` = "Total Interest-bearing Debt", "Total Marketable", "Treasury Bills" ... | stock (a rate at month end) | % | rows for totals and components sit side by side; "Total Marketable" leaves out TIPS and FRNs (see source.md) |
|
|
30
|
+
| Treasury cash balance (TGA) | `v1/accounting/dts/operating_cash_balance` | before 2022-04-18: TGA / Federal Reserve Account row, `close_today_bal`; from 2022-04-18: "Treasury General Account (TGA) Closing Balance" row, `open_today_bal` | stock | $M | **format change on 2022-04-18** [4.11] |
|
|
31
|
+
| Daily deposits and withdrawals by category (tax receipts, Social Security, Medicare, interest ...) | `v1/accounting/dts/deposits_withdrawals_operating_cash` | `transaction_type`, `transaction_catg`; drop the "Total ..." account rows when summing details | flow (`transaction_today_amt`; `_mtd`, `_fytd` are cumulative) | $M | gross public debt cash issues and redemptions are in here: exclude for operating flows; category names change over time [4.12] |
|
|
32
|
+
| Gross borrowing: debt issued and redeemed | `v1/accounting/dts/public_debt_transactions` | `transaction_type` Issues / Redemptions, `security_type` | flow | $M | |
|
|
33
|
+
| Auction results (yields, bid-to-cover, who bought) | `v1/accounting/od/auctions_query` | completed auctions only (`auction_date` <= today, non-null `high_yield`); `original_security_term` to include reopenings; `inflation_index_security: No` for nominal securities (TIPS are `security_type` Note too) | event | mixed | future auctions have null results [4.16] |
|
|
34
|
+
| Exchange rates used for federal reporting | `v1/accounting/od/rates_of_exchange` | `country_currency_desc`; latest `effective_date` per quarter | stock | foreign units per USD | amendments create duplicate quarter rows [4.15] |
|
|
35
|
+
| Revenue collections by channel and tax category | `v2/revenue/rcm` | `tax_category_desc`, `channel_type_desc` | flow | $ | collections, not budget receipts |
|
|
36
|
+
| Receivables and delinquent debt owed to agencies | `v2/debt/tror` | per agency × receivable type | stock | $ | ~230 columns: select by name |
|
|
37
|
+
| Treasury Offset Program collections | `v1/debt/treasury_offset_program` | filter by date and agency | flow | $ | 3.5 million rows: always filter |
|
|
38
|
+
| Gifts to reduce the debt | `v2/accounting/od/gift_contributions` | one row per month | flow | $ | |
|
|
39
|
+
| Savings bonds, I bond rates | `v2/accounting/od/sb_value`, `v1/accounting/od/i_bonds_interest_rates` | | | | **no record_date**: set `date_field` [3] |
|
|
40
|
+
| Buybacks | `v1/accounting/od/buybacks_operations` | | event | $ | date column is `operation_date` |
|
|
41
|
+
| Federal government balance sheet, net cost (Financial Report) | `v2/accounting/od/balance_sheets`, `v2/accounting/od/statement_net_cost` | | annual | $ | lags months |
|
|
42
|
+
|
|
43
|
+
Anything else: `request_schema` for treasury with a search (`"<words>"`) lists every matching endpoint with
|
|
44
|
+
frequency, earliest and latest date, row count and the dataset page.
|
|
45
|
+
|
|
46
|
+
## Not in Fiscal Data: say so and offer the right source
|
|
47
|
+
- **GDP, CPI, inflation**: BEA and BLS, through the treasury spec's `context` field (CPI-U from FRED or BLS; GDP from
|
|
48
|
+
FRED, with an annual World Bank fallback).
|
|
49
|
+
- **Budget projections, baselines, scoring**: CBO (https://www.cbo.gov/data/budget-economic-data).
|
|
50
|
+
- **Historical budget tables, % of GDP back to 1930, the President's budget**: OMB Historical Tables
|
|
51
|
+
(https://www.whitehouse.gov/omb/budget/historical-tables/).
|
|
52
|
+
- **Who holds Treasury debt (foreign holders by country)**: Treasury International Capital (TIC), not
|
|
53
|
+
Fiscal Data; the Treasury Bulletin OFS-2 table (`v1/accounting/tb/ofs2_...`) gives ownership by sector.
|
|
54
|
+
- **Market yields (daily Treasury par yield curve)**: the treasury-yields pack (home.treasury.gov interest-rate statistics), not this API;
|
|
55
|
+
Fiscal Data has auction results and average rates on outstanding debt.
|
|
56
|
+
- **State and local finances**: Census Bureau Annual Survey of State and Local Government Finances.
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
# Analysis and report patterns for federal fiscal data
|
|
2
|
+
|
|
3
|
+
Use this file to frame the analysis, choose the critical questions, and shape the product. The aim is
|
|
4
|
+
work a careful budget analyst would recognize: the right measure (stock or flow, gross or net), the
|
|
5
|
+
right period (fiscal or calendar year, complete or partial), stated units and dollar basis, numbers that
|
|
6
|
+
tie to the published statement, and limitations stated plainly.
|
|
7
|
+
|
|
8
|
+
## Typical questions and how they are framed
|
|
9
|
+
|
|
10
|
+
- **Debt level and growth:** "How much has the debt grown since 2015?" Measures: total public debt
|
|
11
|
+
outstanding and debt held by the public (Debt to the Penny) at fiscal-year ends; growth in dollars, in
|
|
12
|
+
percent and per year (CAGR). Benchmark: the September Monthly Statement of the Public Debt.
|
|
13
|
+
- **Deficits:** "What was the deficit in FY2025, and how does it compare?" Measures: receipts, outlays and
|
|
14
|
+
the deficit for the fiscal year (MTS Table 1 Year-to-Date, or Table 9 totals), and against the prior
|
|
15
|
+
year. Often as a share of GDP. Benchmark: Treasury's final MTS for September, and CBO's Monthly Budget Review.
|
|
16
|
+
- **Fiscal year to date:** "How is FY2026 going so far?" Compare the same months of the prior year (October
|
|
17
|
+
through the latest month), never a partial year with a full year.
|
|
18
|
+
- **Composition:** "Where does the money come from and go?" Receipts by source and outlays by function (MTS
|
|
19
|
+
Table 9): levels, shares of the total and changes.
|
|
20
|
+
- **Interest costs:** "How fast is interest on the debt rising?" Measures: net interest outlays (MTS Table 9,
|
|
21
|
+
the budget measure) or gross interest expense (`interest_expense`), the average interest rate on
|
|
22
|
+
interest-bearing debt, and interest as a share of outlays or receipts. Decompose growth into the debt-level
|
|
23
|
+
effect and the rate effect when asked why.
|
|
24
|
+
- **Cash and the debt limit:** "How much cash does Treasury have?" The TGA closing balance (DTS) and debt
|
|
25
|
+
subject to limit; mind the 2022 DTS format change.
|
|
26
|
+
- **Borrowing and auctions:** gross issuance and redemptions (DTS), auction sizes, yields and bid-to-cover by
|
|
27
|
+
security type and term.
|
|
28
|
+
- **Exchange rates:** the Treasury reporting rate for a currency over time (not market rates).
|
|
29
|
+
|
|
30
|
+
## Critical questions bank
|
|
31
|
+
|
|
32
|
+
Ask only the ones that would change a headline number for this request, at most four, in one round,
|
|
33
|
+
with "Don't know — decide for me" on each and the recommended option first. Skip what the request
|
|
34
|
+
already settles.
|
|
35
|
+
|
|
36
|
+
| Choice | Ask when | Options (recommended first, typical) | How to decide empirically when the user doesn't know |
|
|
37
|
+
|---|---|---|---|
|
|
38
|
+
| **Period basis** | annual figures for budget flows or year-end stocks | Federal fiscal year (Oct–Sep) · Calendar year | Fiscal year for budget measures (precedent: MTS, CBO, OMB); calendar year only to match a calendar-year comparison (GDP from the World Bank, a calendar-year report) |
|
|
39
|
+
| **Time span** | the request names no years | last 10 complete fiscal years · since 2015 (MTS API start) · longest available | 10 complete years; include the current partial year only as "year to date" against the same months a year earlier. For **change** over "the past decade / N years", compare endpoints N years apart (latest complete FY vs. latest − N, so N + 1 years shown); for lists or totals, use the N latest complete years. Name the years either way |
|
|
40
|
+
| **Debt measure** | any debt question | Debt held by the public · Total public debt outstanding · Debt subject to limit | Held by the public for economic analysis (CBO precedent); total for "the national debt" in plain usage; report both when unsure and say how they differ |
|
|
41
|
+
| **Dollar basis** | comparisons across more than about 3 years, or "real" growth | Nominal · Real (CPI-U, latest full fiscal year dollars) · Share of GDP | Nominal for levels people quote; add real or % of GDP when growth over a decade or more is the point; run both and say whether the conclusion changes |
|
|
42
|
+
| **Stock: end of period or average** | yearly or monthly debt, cash, rates | End of period · Period average | End of fiscal year (matches published year-end figures); show the average as a sensitivity when the series is volatile (TGA cash) |
|
|
43
|
+
| **Interest measure** | interest questions | Net interest (MTS, budget) · Gross interest expense (`interest_expense`) · Interest on debt held by the public only | Net interest for budget questions; gross for "what Treasury pays"; public-issues expense for market-facing costs; state the choice in notes |
|
|
44
|
+
| **Gross or net** | receipts or outlays | Net (budget convention) · Gross | Net: it is what the MTS totals and CBO report |
|
|
45
|
+
| **Partial latest period** | the latest fiscal year is incomplete | Fiscal year to date vs. same months last year · Exclude it · Trailing 12 months | FYTD against the same months; trailing-12-month totals for trend charts |
|
|
46
|
+
| **Product** | the user did not ask for a report | Short answer + data (default) · Full HTML report · Data files only | The default; offer the report in one line |
|
|
47
|
+
| **Audience and organization** | a report is wanted | Neutral analyst product · Named organization | Neutral unless the user names one |
|
|
48
|
+
|
|
49
|
+
Questions that are **not** critical (decide and record them): CSV vs JSON, field selection, chart type,
|
|
50
|
+
rounding, the exact endpoint when two give identical published totals.
|
|
51
|
+
|
|
52
|
+
## Conventions to follow
|
|
53
|
+
|
|
54
|
+
**Periods and timing**
|
|
55
|
+
- The federal fiscal year runs October 1 to September 30 and is named for the year it ends. Write
|
|
56
|
+
"fiscal year 2025" in prose (style guide), "FY2025" only in tables and charts.
|
|
57
|
+
- `record_date` is the reporting date (month end for the MTS, business day for the DTS and Debt to the
|
|
58
|
+
Penny). The MTS for September is the final, full-year statement; it is published in mid-October.
|
|
59
|
+
- Say how current the data are: "data through September 30, 2025, retrieved October 19, 2026".
|
|
60
|
+
- Fix the cut-off in the spec (`as_of`) so reruns return the same rows.
|
|
61
|
+
|
|
62
|
+
**Stocks and flows**
|
|
63
|
+
- Stocks (debt, cash, rates): take the end-of-period value (`period_end`) or the average (`period_mean`).
|
|
64
|
+
Never sum them.
|
|
65
|
+
- Flows (receipts, outlays, deficit, interest): sum monthly values (`period_sum`, check `complete`), or read
|
|
66
|
+
the September fiscal-year-to-date value. Never sum fiscal-year-to-date values across months.
|
|
67
|
+
|
|
68
|
+
**Tying to published totals**
|
|
69
|
+
- Every component breakdown must add to its published total (`check_total`), and every headline should
|
|
70
|
+
match the official statement for the same date (the MTS, MSPD or DTS PDF, or Treasury's press summary).
|
|
71
|
+
State the benchmark in Data and Methods. A difference above rounding means a filter or hierarchy mistake.
|
|
72
|
+
When the downloaded table is itself the statement's total, check the internal identities instead, plus
|
|
73
|
+
one independent publication (press release, CBO Monthly Budget Review).
|
|
74
|
+
- MTS tables repeat history and revise it. Use the latest release for a monthly series; use the September
|
|
75
|
+
release for a full fiscal year.
|
|
76
|
+
|
|
77
|
+
**Units and signs**
|
|
78
|
+
- MTS tables 1-9, Debt to the Penny and interest expense are in dollars; DTS, MSPD and the long MTS series
|
|
79
|
+
(`mts_receipts_outlays_deficit_surplus`, field `mil_amt`) are in millions. Convert once,
|
|
80
|
+
name the unit in every exhibit subtitle ("Billions of dollars").
|
|
81
|
+
- Deficits: MTS Table 1 and the long MTS series show a deficit as positive; MTS Table 5 shows it as negative.
|
|
82
|
+
Pick one convention for the product ("the deficit was $1.8 trillion") and state it.
|
|
83
|
+
|
|
84
|
+
**Real dollars and GDP**
|
|
85
|
+
- Deflate with the CPI-U averaged over the same fiscal year (`compute` `to_fiscal` with `how` "mean", then
|
|
86
|
+
`deflate`), into the dollars of the latest complete fiscal year; name the index and base year in notes.
|
|
87
|
+
- Fiscal-year GDP is the average of the four quarterly seasonally adjusted annual rates from October to
|
|
88
|
+
September (`to_fiscal` with `freq` "Q", `how` "mean"). Calendar-year GDP (World Bank fallback) does not match fiscal-year budget totals;
|
|
89
|
+
if only that is available, say so or use calendar-year flows.
|
|
90
|
+
- An incomplete period (the `complete` flag is False; `to_fiscal` notes it) is provisional: say so
|
|
91
|
+
in the text and the exhibit notes, with its coverage ("GDP for three of four quarters"). In October the
|
|
92
|
+
latest fiscal year usually lacks GDP's July–September quarter, so its share of GDP is provisional.
|
|
93
|
+
|
|
94
|
+
**Revisions and provenance**
|
|
95
|
+
- Treasury revises some values in later releases. Record the retrieval date (it is in `data/treasury/README.md`)
|
|
96
|
+
and note revisions when a comparison spans releases.
|
|
97
|
+
|
|
98
|
+
## Publication structure (mirrored in `build_report`, `"mode": "report"`)
|
|
99
|
+
|
|
100
|
+
The default layout, the **exhibit chartbook**, runs in this order:
|
|
101
|
+
1. **Cover:** "Month Year", the title (with the period for trend reports), and a hero chart.
|
|
102
|
+
2. **At a Glance** (one page of about 300–420 words): one framing paragraph (what was examined, the measures,
|
|
103
|
+
the period), then 3–5 bullets, each opening with a **bold lead phrase.** that names a section, followed by
|
|
104
|
+
2–4 sentences with the key numbers.
|
|
105
|
+
3. **Contents** and **List of Exhibits** (built automatically).
|
|
106
|
+
4. **Notes About This Report:** fiscal years; rounding; nominal or real dollars (index and base year); the
|
|
107
|
+
data source and retrieval date; sign conventions; partial-year coverage; a pointer to Appendix A.
|
|
108
|
+
5. **Introduction:** a lead paragraph with the headline numbers; question-style subheadings, one per section
|
|
109
|
+
("How Did Interest Costs Change?"); then "What Data Were Used?" and, when updating earlier work,
|
|
110
|
+
"How Do These Estimates Compare With Published Figures?".
|
|
111
|
+
6. **Thematic sections** (2–5): each opens with 1–3 summary paragraphs, then one exhibit per page with 2–4
|
|
112
|
+
narrative paragraphs beside the chart (level, change, comparison; "see Exhibit 3").
|
|
113
|
+
7. **Appendix A: Data and Methods:** endpoints and rows used, filters, the cut-off date, stock/flow treatment,
|
|
114
|
+
period basis, deflator, benchmark comparison with the published statement, revisions, limitations.
|
|
115
|
+
8. **About This Document** (optional).
|
|
116
|
+
|
|
117
|
+
Use `"mode": "paper"` for a prose-led product with the exhibits in the running text.
|
|
118
|
+
|
|
119
|
+
## Chart forms
|
|
120
|
+
- Trends over fiscal years: line charts (debt, interest, rates) or columns (annual deficits), at most 4–5
|
|
121
|
+
series. Trailing-12-month lines suit monthly flows, which are very seasonal (April tax receipts).
|
|
122
|
+
- Composition (receipts by source, outlays by function): horizontal bars for one year, sorted; stacked
|
|
123
|
+
columns for change over time with at most about 6 groups plus "Other".
|
|
124
|
+
- Deficits: columns with the sign convention stated; surpluses below zero if shown as negative deficits.
|
|
125
|
+
- No dual axes, no pie charts, no 3-D. Scale amounts to billions or trillions in the exhibit CSV and name
|
|
126
|
+
the unit in the subtitle.
|