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.
Files changed (292) hide show
  1. package/README.md +286 -262
  2. package/dist/adapters/bjs.d.ts +13 -0
  3. package/dist/adapters/bjs.js +28 -0
  4. package/dist/adapters/bjs.js.map +1 -0
  5. package/dist/adapters/cbp.d.ts +5 -0
  6. package/dist/adapters/cbp.js +64 -0
  7. package/dist/adapters/cbp.js.map +1 -0
  8. package/dist/adapters/cdc-wonder.d.ts +5 -0
  9. package/dist/adapters/cdc-wonder.js +68 -0
  10. package/dist/adapters/cdc-wonder.js.map +1 -0
  11. package/dist/adapters/cpsc.d.ts +4 -0
  12. package/dist/adapters/cpsc.js +125 -0
  13. package/dist/adapters/cpsc.js.map +1 -0
  14. package/dist/adapters/fhwa.d.ts +9 -0
  15. package/dist/adapters/fhwa.js +16 -0
  16. package/dist/adapters/fhwa.js.map +1 -0
  17. package/dist/adapters/foreign-assistance.d.ts +9 -0
  18. package/dist/adapters/foreign-assistance.js +42 -0
  19. package/dist/adapters/foreign-assistance.js.map +1 -0
  20. package/dist/adapters/hud-ahar.d.ts +3 -0
  21. package/dist/adapters/hud-ahar.js +80 -0
  22. package/dist/adapters/hud-ahar.js.map +1 -0
  23. package/dist/adapters/nces.d.ts +10 -0
  24. package/dist/adapters/nces.js +32 -0
  25. package/dist/adapters/nces.js.map +1 -0
  26. package/dist/adapters/nsf.d.ts +11 -0
  27. package/dist/adapters/nsf.js +25 -0
  28. package/dist/adapters/nsf.js.map +1 -0
  29. package/dist/adapters/onrr.d.ts +9 -0
  30. package/dist/adapters/onrr.js +35 -0
  31. package/dist/adapters/onrr.js.map +1 -0
  32. package/dist/adapters/sba.d.ts +10 -0
  33. package/dist/adapters/sba.js +134 -0
  34. package/dist/adapters/sba.js.map +1 -0
  35. package/dist/adapters/treasury-tic.d.ts +30 -0
  36. package/dist/adapters/treasury-tic.js +149 -0
  37. package/dist/adapters/treasury-tic.js.map +1 -0
  38. package/dist/adapters/uscourts.d.ts +8 -0
  39. package/dist/adapters/uscourts.js +8 -0
  40. package/dist/adapters/uscourts.js.map +1 -0
  41. package/dist/analysis/cite.d.ts +9 -1
  42. package/dist/analysis/cite.js +9 -2
  43. package/dist/analysis/cite.js.map +1 -1
  44. package/dist/bin/cli.d.ts +2 -0
  45. package/dist/bin/cli.js +17 -0
  46. package/dist/bin/cli.js.map +1 -1
  47. package/dist/core/generic-rest.js +42 -17
  48. package/dist/core/generic-rest.js.map +1 -1
  49. package/dist/core/guard.d.ts +32 -0
  50. package/dist/core/guard.js +176 -0
  51. package/dist/core/guard.js.map +1 -0
  52. package/dist/core/http.d.ts +10 -0
  53. package/dist/core/http.js +36 -7
  54. package/dist/core/http.js.map +1 -1
  55. package/dist/core/keys.d.ts +13 -3
  56. package/dist/core/keys.js +67 -7
  57. package/dist/core/keys.js.map +1 -1
  58. package/dist/core/package.d.ts +12 -3
  59. package/dist/core/package.js +56 -12
  60. package/dist/core/package.js.map +1 -1
  61. package/dist/core/secret_patterns.d.ts +6 -0
  62. package/dist/core/secret_patterns.js +20 -0
  63. package/dist/core/secret_patterns.js.map +1 -0
  64. package/dist/core/tabular.d.ts +43 -1
  65. package/dist/core/tabular.js +149 -6
  66. package/dist/core/tabular.js.map +1 -1
  67. package/dist/envelope.js +3 -1
  68. package/dist/envelope.js.map +1 -1
  69. package/dist/index.d.ts +29 -22
  70. package/dist/index.js +45 -46
  71. package/dist/index.js.map +1 -1
  72. package/dist/remote/app.js +87 -31
  73. package/dist/remote/app.js.map +1 -1
  74. package/dist/remote/oauth.js +8 -1
  75. package/dist/remote/oauth.js.map +1 -1
  76. package/dist/remote/pages.d.ts +3 -7
  77. package/dist/remote/pages.js +49 -19
  78. package/dist/remote/pages.js.map +1 -1
  79. package/dist/remote/sign.d.ts +7 -1
  80. package/dist/remote/sign.js +33 -7
  81. package/dist/remote/sign.js.map +1 -1
  82. package/dist/remote/store.js +14 -5
  83. package/dist/remote/store.js.map +1 -1
  84. package/dist/report/audit_report.js +29 -7
  85. package/dist/report/audit_report.js.map +1 -1
  86. package/dist/report/build_report.js +34 -4
  87. package/dist/report/build_report.js.map +1 -1
  88. package/dist/report/method_audit.js +10 -1
  89. package/dist/report/method_audit.js.map +1 -1
  90. package/dist/report/scan_secrets.d.ts +4 -1
  91. package/dist/report/scan_secrets.js +38 -18
  92. package/dist/report/scan_secrets.js.map +1 -1
  93. package/dist/server.d.ts +3 -1
  94. package/dist/server.js +46 -13
  95. package/dist/server.js.map +1 -1
  96. package/dist/tools.js +27 -6
  97. package/dist/tools.js.map +1 -1
  98. package/guide/WORKFLOW.md +134 -134
  99. package/guide/assets/disclaimer.txt +1 -1
  100. package/guide/assets/download_data.ps1 +164 -162
  101. package/guide/assets/download_data.sh +8 -2
  102. package/guide/assets/report_template.html +597 -597
  103. package/guide/references/routing.md +198 -171
  104. package/guide/references/style_guide.md +398 -398
  105. package/package.json +56 -56
  106. package/packs/acf/endpoints.json +114 -114
  107. package/packs/acf/policy.json +104 -104
  108. package/packs/actuaries/endpoints.json +82 -82
  109. package/packs/actuaries/policy.json +109 -109
  110. package/packs/bea/assets/download_bea.ps1 +182 -182
  111. package/packs/bea/docs/bea_api.md +461 -461
  112. package/packs/bea/docs/datasets.md +157 -157
  113. package/packs/bea/docs/report_patterns.md +112 -112
  114. package/packs/bea/policy.json +170 -170
  115. package/packs/bea/source.md +152 -152
  116. package/packs/bjs/endpoints.json +150 -0
  117. package/packs/bjs/policy.json +114 -0
  118. package/packs/bjs/source.md +98 -0
  119. package/packs/bls/assets/download_bls.ps1 +152 -152
  120. package/packs/bls/docs/analysis_patterns.md +108 -108
  121. package/packs/bls/docs/bls_api.md +73 -73
  122. package/packs/bls/docs/series_ids.md +149 -149
  123. package/packs/bls/policy.json +238 -238
  124. package/packs/bts/endpoints.json +346 -346
  125. package/packs/bts/policy.json +94 -94
  126. package/packs/cbp/endpoints.json +31 -0
  127. package/packs/cbp/policy.json +85 -0
  128. package/packs/cbp/source.md +57 -0
  129. package/packs/cdc/endpoints.json +197 -197
  130. package/packs/cdc/policy.json +83 -83
  131. package/packs/cdc/source.md +1 -1
  132. package/packs/cdc-wonder/endpoints.json +26 -0
  133. package/packs/cdc-wonder/policy.json +84 -0
  134. package/packs/cdc-wonder/source.md +53 -0
  135. package/packs/census/endpoints.json +99 -99
  136. package/packs/cfpb/endpoints.json +326 -326
  137. package/packs/cfpb/policy.json +119 -119
  138. package/packs/clinical-trials/endpoints.json +166 -166
  139. package/packs/clinical-trials/policy.json +84 -84
  140. package/packs/cms/endpoints.json +69 -69
  141. package/packs/cms/policy.json +96 -96
  142. package/packs/college-scorecard/endpoints.json +252 -252
  143. package/packs/college-scorecard/policy.json +106 -106
  144. package/packs/college-scorecard/source.md +1 -1
  145. package/packs/congress/endpoints.json +1701 -1701
  146. package/packs/congress/policy.json +117 -117
  147. package/packs/cpsc/endpoints.json +91 -0
  148. package/packs/cpsc/policy.json +91 -0
  149. package/packs/cpsc/source.md +76 -0
  150. package/packs/dhs-ohss/endpoints.json +66 -66
  151. package/packs/dhs-ohss/policy.json +107 -107
  152. package/packs/dhs-ohss/source.md +1 -1
  153. package/packs/doj-news/endpoints.json +59 -59
  154. package/packs/doj-news/policy.json +96 -96
  155. package/packs/doj-news/source.md +1 -1
  156. package/packs/dol/endpoints.json +817 -817
  157. package/packs/dol/policy.json +135 -135
  158. package/packs/eia/endpoints.json +717 -717
  159. package/packs/eia/policy.json +112 -112
  160. package/packs/epa/endpoints.json +291 -291
  161. package/packs/epa/policy.json +99 -99
  162. package/packs/epa-aqs/endpoints.json +173 -173
  163. package/packs/epa-aqs/policy.json +96 -96
  164. package/packs/fbi/endpoints.json +1841 -1841
  165. package/packs/fbi/policy.json +118 -118
  166. package/packs/fbi/source.md +3 -3
  167. package/packs/fda/endpoints.json +237 -237
  168. package/packs/fda/policy.json +121 -121
  169. package/packs/fdic/endpoints.json +416 -416
  170. package/packs/fdic/policy.json +83 -83
  171. package/packs/fec/endpoints.json +707 -707
  172. package/packs/fec/policy.json +93 -93
  173. package/packs/fed-board/endpoints.json +89 -89
  174. package/packs/fed-board/policy.json +136 -136
  175. package/packs/federal-register/endpoints.json +143 -143
  176. package/packs/federal-register/policy.json +86 -86
  177. package/packs/fema/endpoints.json +645 -645
  178. package/packs/fema/policy.json +103 -103
  179. package/packs/fhfa/endpoints.json +105 -105
  180. package/packs/fhfa/policy.json +109 -109
  181. package/packs/fhwa/endpoints.json +48 -0
  182. package/packs/fhwa/policy.json +91 -0
  183. package/packs/fhwa/source.md +59 -0
  184. package/packs/foreign-assistance/endpoints.json +166 -0
  185. package/packs/foreign-assistance/policy.json +80 -0
  186. package/packs/foreign-assistance/source.md +76 -0
  187. package/packs/fred/assets/download_fred.ps1 +122 -122
  188. package/packs/fred/docs/analysis_patterns.md +124 -124
  189. package/packs/fred/docs/fred_api.md +94 -94
  190. package/packs/fred/docs/series.md +188 -188
  191. package/packs/fred/policy.json +253 -253
  192. package/packs/fsa/endpoints.json +150 -150
  193. package/packs/fsa/policy.json +99 -99
  194. package/packs/fsa/source.md +1 -1
  195. package/packs/govinfo/endpoints.json +519 -519
  196. package/packs/gsa-calc/endpoints.json +93 -93
  197. package/packs/gsa-calc/policy.json +97 -97
  198. package/packs/hud/endpoints.json +146 -146
  199. package/packs/hud/policy.json +84 -84
  200. package/packs/hud/source.md +1 -1
  201. package/packs/hud-ahar/endpoints.json +92 -0
  202. package/packs/hud-ahar/policy.json +88 -0
  203. package/packs/hud-ahar/source.md +72 -0
  204. package/packs/ipums/docs/report_patterns.md +117 -117
  205. package/packs/irs-soi/endpoints.json +114 -114
  206. package/packs/irs-soi/policy.json +107 -107
  207. package/packs/medicaid/endpoints.json +412 -412
  208. package/packs/medicaid/policy.json +108 -108
  209. package/packs/naep/endpoints.json +217 -217
  210. package/packs/naep/policy.json +100 -100
  211. package/packs/naep/source.md +1 -1
  212. package/packs/nces/endpoints.json +101 -0
  213. package/packs/nces/policy.json +99 -0
  214. package/packs/nces/source.md +75 -0
  215. package/packs/nhtsa/endpoints.json +132 -132
  216. package/packs/nhtsa/policy.json +93 -93
  217. package/packs/nhtsa/source.md +1 -1
  218. package/packs/nih/endpoints.json +452 -452
  219. package/packs/nih/policy.json +86 -86
  220. package/packs/noaa/endpoints.json +431 -431
  221. package/packs/noaa/policy.json +95 -95
  222. package/packs/nrel/endpoints.json +327 -327
  223. package/packs/nrel/policy.json +96 -96
  224. package/packs/nsf/endpoints.json +33 -0
  225. package/packs/nsf/policy.json +83 -0
  226. package/packs/nsf/source.md +59 -0
  227. package/packs/nws/endpoints.json +271 -271
  228. package/packs/nws/policy.json +82 -82
  229. package/packs/nyfed/endpoints.json +80 -80
  230. package/packs/nyfed/policy.json +92 -92
  231. package/packs/omb/endpoints.json +460 -460
  232. package/packs/omb/policy.json +106 -106
  233. package/packs/onrr/endpoints.json +198 -0
  234. package/packs/onrr/policy.json +91 -0
  235. package/packs/onrr/source.md +55 -0
  236. package/packs/open-payments/endpoints.json +297 -297
  237. package/packs/open-payments/policy.json +101 -101
  238. package/packs/opm/assets/download_opm.ps1 +125 -125
  239. package/packs/opm/docs/fields.md +184 -184
  240. package/packs/opm/docs/opm_api.md +71 -71
  241. package/packs/opm/docs/report_patterns.md +83 -83
  242. package/packs/opm/lib/data_dictionary.csv +73 -73
  243. package/packs/pbgc/endpoints.json +483 -483
  244. package/packs/pbgc/policy.json +94 -94
  245. package/packs/philfed/endpoints.json +85 -85
  246. package/packs/philfed/policy.json +94 -94
  247. package/packs/port.json +65 -0
  248. package/packs/regulations/endpoints.json +287 -287
  249. package/packs/regulations/policy.json +86 -86
  250. package/packs/sba/endpoints.json +34 -0
  251. package/packs/sba/policy.json +86 -0
  252. package/packs/sba/source.md +60 -0
  253. package/packs/sec/endpoints.json +236 -236
  254. package/packs/sec/policy.json +86 -86
  255. package/packs/senate-lobbying/endpoints.json +553 -553
  256. package/packs/senate-lobbying/policy.json +99 -99
  257. package/packs/snapqc/endpoints.json +1426 -1426
  258. package/packs/snapqc/policy.json +92 -92
  259. package/packs/treasury/catalog.json +2267 -2267
  260. package/packs/treasury/docs/api_guide.md +245 -245
  261. package/packs/treasury/docs/datasets.md +56 -56
  262. package/packs/treasury/docs/report_patterns.md +126 -126
  263. package/packs/treasury/policy.json +159 -159
  264. package/packs/treasury/source.md +170 -165
  265. package/packs/treasury-tic/endpoints.json +77 -0
  266. package/packs/treasury-tic/policy.json +89 -0
  267. package/packs/treasury-tic/source.md +80 -0
  268. package/packs/treasury-yields/endpoints.json +226 -226
  269. package/packs/treasury-yields/policy.json +86 -86
  270. package/packs/usaspending/endpoints.json +1315 -1315
  271. package/packs/usaspending/policy.json +109 -109
  272. package/packs/uscourts/endpoints.json +22 -0
  273. package/packs/uscourts/policy.json +87 -0
  274. package/packs/uscourts/source.md +56 -0
  275. package/packs/usda-fna/policy.json +133 -133
  276. package/packs/usda-fooddata/endpoints.json +180 -180
  277. package/packs/usda-fooddata/policy.json +94 -94
  278. package/packs/usda-nass/endpoints.json +323 -323
  279. package/packs/usda-nass/policy.json +95 -95
  280. package/packs/usda-outlook/endpoints.json +86 -86
  281. package/packs/usda-outlook/policy.json +109 -109
  282. package/packs/usgs/endpoints.json +313 -313
  283. package/packs/usgs/policy.json +95 -95
  284. package/packs/usitc/endpoints.json +74 -74
  285. package/packs/usitc/policy.json +111 -111
  286. package/packs/uspto/endpoints.json +141 -141
  287. package/packs/uspto/policy.json +95 -95
  288. package/packs/uspto/source.md +1 -1
  289. package/packs/va/endpoints.json +414 -414
  290. package/packs/va/policy.json +101 -101
  291. package/packs/world-bank/endpoints.json +122 -122
  292. package/packs/world-bank/policy.json +101 -101
@@ -1,109 +1,109 @@
1
- {
2
- "id": "usaspending",
3
- "title": "USAspending.gov API (federal awards and spending)",
4
- "agency": "U.S. Department of the Treasury, Bureau of the Fiscal Service",
5
- "depth": "standard",
6
- "domains": [
7
- "spending",
8
- "federal budget",
9
- "procurement",
10
- "grants"
11
- ],
12
- "keywords": [
13
- "usaspending",
14
- "federal spending",
15
- "contracts",
16
- "contract",
17
- "grants",
18
- "grant",
19
- "loans",
20
- "awards",
21
- "award",
22
- "recipient",
23
- "recipients",
24
- "contractor",
25
- "contractors",
26
- "procurement",
27
- "obligations",
28
- "outlays",
29
- "federal dollars",
30
- "agency spending",
31
- "budgetary resources",
32
- "spending by state",
33
- "per capita federal spending",
34
- "cfda",
35
- "assistance listing",
36
- "naics",
37
- "psc",
38
- "subaward",
39
- "direct payments",
40
- "federal funds to states",
41
- "defense contractors"
42
- ],
43
- "questions": [
44
- "which companies received the most federal contracts",
45
- "federal spending by state per capita",
46
- "grants from an agency over time",
47
- "top recipients of a program",
48
- "how much did an agency obligate in a fiscal year",
49
- "contracts mentioning a keyword"
50
- ],
51
- "homepage": "https://www.usaspending.gov/",
52
- "terms_url": "https://www.usaspending.gov/about",
53
- "auth": {
54
- "env": null,
55
- "required": "none",
56
- "placement": "none",
57
- "signup_url": null,
58
- "echoes_key": false
59
- },
60
- "limits": {
61
- "rps": 2,
62
- "burst": 5,
63
- "max_rows": 10000
64
- },
65
- "routes": {
66
- "api": {
67
- "base": "https://api.usaspending.gov/api/v2",
68
- "probe": "https://api.usaspending.gov/api/v2/references/toptier_agencies/?sort=agency_name&order=asc",
69
- "hosts": [
70
- "api.usaspending.gov"
71
- ]
72
- },
73
- "manual": {
74
- "how": "Run download_data.sh (macOS, Linux) or download_data.ps1 (Windows) from manual_download/ with one command: the search endpoints are POST requests, which a browser cannot open; GET links (agency, budgetary resources, recipient state, award) also open in a browser (save each under the name shown). Upload the files, then call ingest. Without the bundle: on https://www.usaspending.gov/search set the filters (time period as fiscal years, award type, agency, location, keyword) and use Download > Award or Transaction CSV, or Advanced Search > the tab for the breakdown (e.g. Spending by Category) and its table download; upload the CSV and say which view it is."
75
- }
76
- },
77
- "cache": {
78
- "mode": "run_only",
79
- "ttl_hours": null,
80
- "why": "The database is updated nightly and award records are revised; data/ is reused only within a run."
81
- },
82
- "redistribution": {
83
- "mode": "allowed",
84
- "why": "USAspending data are published by the U.S. Treasury under the DATA Act (31 U.S.C. 6101 note); they are U.S. government works in the public domain (17 U.S.C. 105). Recipient names and amounts are public records; cite USAspending.gov as the source."
85
- },
86
- "notices": [],
87
- "retention": null,
88
- "citation": "U.S. Department of the Treasury, USAspending.gov, {dataset}, api.usaspending.gov (API v2), retrieved {retrieved_long}.",
89
- "audit_hooks": [
90
- {
91
- "id": "usaspending_period_basis",
92
- "kind": "require_text",
93
- "any": [
94
- "fiscal year",
95
- "fy20"
96
- ],
97
- "why": "USAspending periods are federal fiscal years (October-September); the report must say so before comparing with calendar-year data."
98
- }
99
- ],
100
- "clarify": [
101
- "Federal fiscal years (October-September, the API's basis) or calendar years? Converting needs monthly data (over_time with group=month).",
102
- "Obligations (commitments made, what the search endpoints sum) or outlays (cash paid out, from agency budgetary resources or award outlays)? They differ by year and can differ a lot for multi-year awards and loans.",
103
- "Which award types: contracts, grants, loans (face value, not cost), direct payments, or all? Award searches take one type group at a time."
104
- ],
105
- "formats": [
106
- "json",
107
- "csv (website downloads)"
108
- ]
109
- }
1
+ {
2
+ "id": "usaspending",
3
+ "title": "USAspending.gov API (federal awards and spending)",
4
+ "agency": "U.S. Department of the Treasury, Bureau of the Fiscal Service",
5
+ "depth": "standard",
6
+ "domains": [
7
+ "spending",
8
+ "federal budget",
9
+ "procurement",
10
+ "grants"
11
+ ],
12
+ "keywords": [
13
+ "usaspending",
14
+ "federal spending",
15
+ "contracts",
16
+ "contract",
17
+ "grants",
18
+ "grant",
19
+ "loans",
20
+ "awards",
21
+ "award",
22
+ "recipient",
23
+ "recipients",
24
+ "contractor",
25
+ "contractors",
26
+ "procurement",
27
+ "obligations",
28
+ "outlays",
29
+ "federal dollars",
30
+ "agency spending",
31
+ "budgetary resources",
32
+ "spending by state",
33
+ "per capita federal spending",
34
+ "cfda",
35
+ "assistance listing",
36
+ "naics",
37
+ "psc",
38
+ "subaward",
39
+ "direct payments",
40
+ "federal funds to states",
41
+ "defense contractors"
42
+ ],
43
+ "questions": [
44
+ "which companies received the most federal contracts",
45
+ "federal spending by state per capita",
46
+ "grants from an agency over time",
47
+ "top recipients of a program",
48
+ "how much did an agency obligate in a fiscal year",
49
+ "contracts mentioning a keyword"
50
+ ],
51
+ "homepage": "https://www.usaspending.gov/",
52
+ "terms_url": "https://www.usaspending.gov/about",
53
+ "auth": {
54
+ "env": null,
55
+ "required": "none",
56
+ "placement": "none",
57
+ "signup_url": null,
58
+ "echoes_key": false
59
+ },
60
+ "limits": {
61
+ "rps": 2,
62
+ "burst": 5,
63
+ "max_rows": 10000
64
+ },
65
+ "routes": {
66
+ "api": {
67
+ "base": "https://api.usaspending.gov/api/v2",
68
+ "probe": "https://api.usaspending.gov/api/v2/references/toptier_agencies/?sort=agency_name&order=asc",
69
+ "hosts": [
70
+ "api.usaspending.gov"
71
+ ]
72
+ },
73
+ "manual": {
74
+ "how": "Run download_data.sh (macOS, Linux) or download_data.ps1 (Windows) from manual_download/ with one command: the search endpoints are POST requests, which a browser cannot open; GET links (agency, budgetary resources, recipient state, award) also open in a browser (save each under the name shown). Upload the files, then call ingest. Without the bundle: on https://www.usaspending.gov/search set the filters (time period as fiscal years, award type, agency, location, keyword) and use Download > Award or Transaction CSV, or Advanced Search > the tab for the breakdown (e.g. Spending by Category) and its table download; upload the CSV and say which view it is."
75
+ }
76
+ },
77
+ "cache": {
78
+ "mode": "run_only",
79
+ "ttl_hours": null,
80
+ "why": "The database is updated nightly and award records are revised; data/ is reused only within a run."
81
+ },
82
+ "redistribution": {
83
+ "mode": "allowed",
84
+ "why": "USAspending data are published by the U.S. Treasury under the DATA Act (31 U.S.C. 6101 note); they are U.S. government works in the public domain (17 U.S.C. 105). Recipient names and amounts are public records; cite USAspending.gov as the source."
85
+ },
86
+ "notices": [],
87
+ "retention": null,
88
+ "citation": "U.S. Department of the Treasury, USAspending.gov, {dataset}, api.usaspending.gov (API v2), retrieved {retrieved_long}.",
89
+ "audit_hooks": [
90
+ {
91
+ "id": "usaspending_period_basis",
92
+ "kind": "require_text",
93
+ "any": [
94
+ "fiscal year",
95
+ "fy20"
96
+ ],
97
+ "why": "USAspending periods are federal fiscal years (October-September); the report must say so before comparing with calendar-year data."
98
+ }
99
+ ],
100
+ "clarify": [
101
+ "Federal fiscal years (October-September, the API's basis) or calendar years? Converting needs monthly data (over_time with group=month).",
102
+ "Obligations (commitments made, what the search endpoints sum) or outlays (cash paid out, from agency budgetary resources or award outlays)? They differ by year and can differ a lot for multi-year awards and loans.",
103
+ "Which award types: contracts, grants, loans (face value, not cost), direct payments, or all? Award searches take one type group at a time."
104
+ ],
105
+ "formats": [
106
+ "json",
107
+ "csv (website downloads)"
108
+ ]
109
+ }
@@ -0,0 +1,22 @@
1
+ {
2
+ "base_url": "https://www.uscourts.gov",
3
+ "timeout": 90,
4
+ "endpoints": {
5
+ "table": {
6
+ "path": "/sites/default/files/document/{file}.xlsx",
7
+ "method": "GET",
8
+ "description": "One caseload statistics table of the federal courts as its Excel file (bankruptcy filings F-2, F-5A; Statistical Tables for the Federal Judiciary; Federal Judicial Caseload Statistics; Judicial Business), by circuit and district. Default: every line numbered (row, col1...) to find the header lines; then header_lines names the columns.",
9
+ "params": {
10
+ "file": {"in": "path", "required": true, "desc": "the file name without .xlsx as on the table's page, e.g. bf_f2_0930.2026 (bankruptcy filings, table F-2, 12 months to Sept 30, 2026) or stfj_b_630.2026"},
11
+ "sheet": {"in": "records", "desc": "sheet name or number (default 1)"},
12
+ "header_lines": {"in": "records", "desc": "the header line numbers, e.g. '3-5'"},
13
+ "header_row": {"in": "records", "desc": "one header line instead; 0 (default) returns every line numbered"},
14
+ "carry": {"in": "records", "desc": "which header lines span to the right over blank cells: top (default), all, none"}
15
+ },
16
+ "defaults": {"header_row": 0},
17
+ "records": "$xlsx",
18
+ "paging": {"type": "none"},
19
+ "max_rows": 20000
20
+ }
21
+ }
22
+ }
@@ -0,0 +1,87 @@
1
+ {
2
+ "id": "uscourts",
3
+ "title": "U.S. Courts caseload statistics: federal court and bankruptcy filings, terminations and pending cases",
4
+ "agency": "Administrative Office of the U.S. Courts",
5
+ "depth": "standard",
6
+ "domains": [
7
+ "courts",
8
+ "criminal justice",
9
+ "bankruptcy"
10
+ ],
11
+ "keywords": [
12
+ "federal courts",
13
+ "u.s. courts",
14
+ "caseload statistics",
15
+ "bankruptcy filings",
16
+ "chapter 7",
17
+ "chapter 11",
18
+ "chapter 13",
19
+ "business bankruptcies",
20
+ "district courts",
21
+ "courts of appeals",
22
+ "civil cases filed",
23
+ "criminal cases filed",
24
+ "federal defendants",
25
+ "judicial business",
26
+ "pending cases",
27
+ "jurors"
28
+ ],
29
+ "questions": [
30
+ "bankruptcy filings by chapter and district",
31
+ "business vs consumer bankruptcy filings",
32
+ "civil and criminal cases filed in federal district courts",
33
+ "appeals filed, terminated and pending by circuit",
34
+ "federal court caseload trends"
35
+ ],
36
+ "homepage": "https://www.uscourts.gov/statistics-reports/caseload-statistics-data-tables",
37
+ "terms_url": "https://www.uscourts.gov/statistics-reports/caseload-statistics-data-tables",
38
+ "auth": {
39
+ "env": null,
40
+ "required": "none",
41
+ "placement": "none",
42
+ "signup_url": null,
43
+ "echoes_key": false
44
+ },
45
+ "limits": {
46
+ "rps": 1,
47
+ "burst": 3,
48
+ "max_rows": 20000
49
+ },
50
+ "routes": {
51
+ "api": {
52
+ "base": "https://www.uscourts.gov",
53
+ "probe": "https://www.uscourts.gov/sites/default/files/document/bf_f2_0930.2026.xlsx",
54
+ "hosts": [
55
+ "www.uscourts.gov"
56
+ ]
57
+ },
58
+ "manual": {
59
+ "how": "Open https://www.uscourts.gov/statistics-reports/caseload-statistics-data-tables, filter to the table, click 'Download xlsx', and upload the workbook with ingest."
60
+ }
61
+ },
62
+ "cache": {
63
+ "mode": "run_only",
64
+ "ttl_hours": null,
65
+ "why": "Tables are published quarterly; data/ is reused within a run."
66
+ },
67
+ "redistribution": {
68
+ "mode": "allowed",
69
+ "why": "Judiciary statistics are U.S. government works in the public domain (17 U.S.C. 105)."
70
+ },
71
+ "notices": [],
72
+ "retention": null,
73
+ "citation": "Administrative Office of the U.S. Courts, {dataset}, uscourts.gov, retrieved {retrieved_long}.",
74
+ "audit_hooks": [],
75
+ "clarify": [
76
+ "Which period? Most tables cover a 12-month period ending March 31, June 30, September 30 or December 31 (the file name carries the end date); some cover 1 or 3 months. Default: the latest 12-month table, with the same period a year earlier.",
77
+ "Which series? Bankruptcy filings (bf_), Statistical Tables for the Federal Judiciary (stfj_), Federal Judicial Caseload Statistics and Judicial Business: they repeat some tables for different periods. Default: the series whose period matches the question."
78
+ ],
79
+ "formats": [
80
+ "xlsx"
81
+ ],
82
+ "aliases": [
83
+ "U.S. Courts",
84
+ "Administrative Office of the U.S. Courts",
85
+ "federal judiciary statistics"
86
+ ]
87
+ }
@@ -0,0 +1,56 @@
1
+ # U.S. Courts caseload statistics: federal court and bankruptcy filings, terminations and pending cases
2
+ Depth: standard. Key: none. The Administrative Office of the U.S. Courts' caseload statistics tables, as the
3
+ Excel files on uscourts.gov, read line by line or with a named stacked header. They cover bankruptcy filings by
4
+ chapter, business vs nonbusiness, and district; district court civil and criminal cases and defendants; courts
5
+ of appeals; magistrate judges; jurors; all by circuit and district for 1-, 3- or 12-month periods.
6
+
7
+ ## When to use
8
+ - Bankruptcy filings by chapter and district; trends in business or consumer bankruptcies.
9
+ - Federal civil cases and criminal defendants filed, terminated and pending; appeals by circuit; how long cases
10
+ take (median times in some tables).
11
+ - Not here: crimes and arrests (fbi), victimization and prisoners (bjs), DOJ press releases (doj-news), case
12
+ documents or dockets (not covered), state courts.
13
+
14
+ ## Endpoints
15
+ | Endpoint | Returns | Parameters |
16
+ |---|---|---|
17
+ | `table` | one caseload table: without `header_lines`, every line numbered (`row`, `col1`...); with it, named columns | `file` (the file name without .xlsx), `sheet`, `header_lines`, `header_row`, `carry` |
18
+
19
+ The file name is on the table's entry in https://www.uscourts.gov/statistics-reports/caseload-statistics-data-tables
20
+ ("Download xlsx"):
21
+ - `bf_` is the Bankruptcy Filings series: `bf_f2_0930.2026` is table F-2 for the 12 months to September 30, 2026;
22
+ `bf_f2.1_` is the one-month table and `bf_f2.3_` the three-month table.
23
+ - `stfj_` is the Statistical Tables for the Federal Judiciary: `stfj_b_630.2026` is table B (courts of appeals),
24
+ June 30, 2026.
25
+ - The date part is not zero-padded the same way in every series: copy it.
26
+
27
+ ## Spec example
28
+ ```json
29
+ {"description": "Bankruptcy filings by chapter and district, 12 months to September 30, 2026 (table F-2)",
30
+ "requests": [{"name": "f2", "endpoint": "table",
31
+ "params": {"file": "bf_f2_0930.2026", "header_lines": "3-5", "carry": "all"}}]}
32
+ ```
33
+
34
+ ## Data format and traps
35
+ - Read the raw lines first. In F-2, line 2 is the title (with line breaks), lines 3-5 are the header, and the
36
+ rows begin with the national Total.
37
+ - Stacked headers: `carry: "all"` gives F-2's names (`Predominant Nature of Debt | Business | Chapter 7`). Check
38
+ the names against the numbered lines for any other table.
39
+ - Rows mix levels: `Total`, then each circuit (` 1st`, indented, a subtotal) and its districts (`ME`,
40
+ `MA`, ...; DC stands alone). Keep districts or circuits, never both, when summing. A circuit row's label keeps
41
+ its leading spaces: trim it.
42
+ - Some workbooks have a second sheet with more columns (F-2's second sheet: chapters 9, 12 and 15).
43
+ - Header cells carry footnote marks (`Total Other Chapters ¹`); the notes are below the table.
44
+ - Periods: the file name and title give the period end date and length. Compare like periods (12 months to
45
+ September 30 with the same a year earlier), and say whether the table is 1, 3 or 12 months.
46
+ - Counts are cases (bankruptcy petitions, civil cases) or defendants (criminal tables), as the title says.
47
+
48
+ ## Access
49
+ No key. `fetch` reads www.uscourts.gov/sites/default/files/document/<file>.xlsx (verified 2026-11-07). The FJC
50
+ Integrated Database (case-level records, www.fjc.gov/research/idb) is not covered. Manual: Download xlsx from the
51
+ Data Tables page, then `ingest`.
52
+
53
+ ## Citation and terms
54
+ "Administrative Office of the U.S. Courts, Table F-2, U.S. Bankruptcy Courts, Business and Nonbusiness Cases
55
+ Commenced, by Chapter of the Bankruptcy Code, During the 12-Month Period Ending September 30, 2026, uscourts.gov,
56
+ retrieved <date>." Public domain (17 U.S.C. 105).