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,152 +1,152 @@
1
- # Bureau of Economic Analysis (BEA) Data API and bulk files
2
- Depth: deep. Key: required (BEA_API_KEY) for the API; the bulk route needs none. U.S. national accounts
3
- (GDP, income, PCE and its prices, saving, profits, government), state and county GDP and income, regional
4
- price parities, GDP by industry, trade and international accounts, multinationals, fixed assets, input-output.
5
-
6
- ## When to use
7
- - GDP and its growth, contributions, prices and deflators; personal income, disposable income, saving rate;
8
- PCE and core PCE price indexes (the Federal Reserve's inflation measure); corporate profits; NIPA
9
- government receipts and spending (calendar years); GDP and personal income by state and county; per capita
10
- income; RPPs; value added and gross output by industry; goods and services trade balances by country;
11
- current account; investment position; direct investment; capital stocks.
12
- - Not here: CPI, jobs, unemployment, wages by occupation (bls); budget data by fiscal year (treasury);
13
- market interest rates (treasury-yields; fred); forecasts (BEA publishes history only); monthly GDP.
14
- - The deliverable decides the work: data only (download, short preview, stop), an answer (compute with
15
- `compute`, answer with the numbers, measure and vintage), or a report (`guide`'s report steps).
16
-
17
- ## Endpoints and datasets
18
- One API endpoint (`https://apps.bea.gov/api/data`, GET, key in `UserID`), 13 datasets. Bulk files serve
19
- the most used ones without a key and count against no limit.
20
-
21
- | `dataset` | What | Spec keys | Bulk (no key)? |
22
- |---|---|---|---|
23
- | `NIPA` | national accounts tables `T10101` ... (titles: `request_schema` search) | `table`, `frequency` A/Q/M, `years`, `line_code` | yes (NIPA flat files) |
24
- | `NIUnderlyingDetail` | detail tables `U20305` ... (lower quality) | same | no (flat files hold only shared lines) |
25
- | `FixedAssets` | `FAAt101` ... annual | `table`, `years` | no |
26
- | `Regional` | state `SA*`/`SQ*`, county `CA*`, metro `MA*` tables | `table`, `line_code`, `geo_fips`, `years` | yes for STATE, COUNTY, postal code (its counties), FIPS lists, MARPP |
27
- | `GDPbyIndustry` | workbook codes `TVA101`-`TVA113`, `TGO1xx`, `TII1xx` | `table`, `frequency` A/Q, `years` | yes (public workbooks) |
28
- | `GDPbyIndustry` (API) | `TableID` 1, 5, 6, 25 ...; `Industry` filters | `params` | no |
29
- | `UnderlyingGDPbyIndustry`, `ITA`, `IIP`, `IntlServTrade`, `IntlServSTA`, `MNE`, `InputOutput` | see `request_schema` with `names: ["<name>"]` | `params` (raw API names) | no |
30
-
31
- Verified lines (September 2026 vintage): T10101 line 1 real GDP percent change (annual rate); T10106 line 1
32
- real GDP (millions of chained 2017 dollars, SAAR); T10105 line 1 nominal GDP; T10111 line 1 year-over-year
33
- real GDP change; T10102 contributions; T20100 lines 1/27/37/35/40 personal income / DPI / real DPI / saving
34
- rate / population (annual and quarterly only: monthly values are in T20600, whose line numbers differ, so
35
- check them with the search `lines T20600`; a table is monthly only when its title says so, and the bulk route refuses
36
- frequency M for any other table); T20804 lines 1/25 PCE / core PCE price index (monthly; published changes: T20807 month over month, not
37
- annualized, T20811 lines 32/37 over 12 months); T70100 lines 1/3 GDP and income
38
- per capita (BEA divides by unrounded population: real GDP over T70100's population, published in thousands,
39
- can miss the published per-capita level by just over 0.5 dollars; allow for that rounding in the benchmark and
40
- say so). Federal civilian wages per FTE (T60600D) jump in 2024-2025: Deferred Resignation staff on paid
41
- administrative leave stayed on the payroll while BEA cut the quantity of federal labor (FAQ 1479,
42
- bea.gov/help/faq/1479): never read those years as federal pay raises; use OPM pay or the GS raise. Regional: SAGDP2/SAGDP9 line 1 all-industry total (current / chained 2017 dollars); SAINC1 and
43
- CAINC1 lines 1/2/3 personal income / population / per capita income; SAINC4/CAINC4 lines 10/20/30; SARPP
44
- and MARPP line 1 all-items RPP. API names may carry an `N` (`SAGDP9N`); the bulk files drop it: both work.
45
- BEA marks nothing as preliminary in the data, but the latest quarter or year of every table is an early
46
- estimate that BEA will revise: register facts from it with `preliminary: true` in `facts` and say so. A year that has
47
- been through an annual update (published at the end of September) is revised, not early: say "subject to
48
- revision at the next annual update" instead.
49
- More tables, the question-to-table map and concepts: `docs/datasets.md`. API parameters, response quirks,
50
- error codes and limits: `docs/bea_api.md`. Report conventions: `docs/report_patterns.md`.
51
-
52
- Discovery with `request_schema` (no key unless noted): `search: "real gross domestic product"` (NIPA titles
53
- and workbook tables), `search: "Regional income"` (the first word names the dataset; API datasets need a key),
54
- `search: "lines T10106"` (lines and series codes), `names: ["ITA"]` (required parameters, rules, spec keys,
55
- and with a key BEA's current parameters); with a key (cached a day): `search: "values Regional TableName"`,
56
- `search: "values Regional LineCode TableName=SAINC1"`. `source_brief` lists the 13 datasets.
57
-
58
- ## Spec examples
59
- ```json
60
- {"description": "Real GDP growth, national and by state, 2019 to 2025",
61
- "requests": [
62
- {"id": "gdp_pct", "dataset": "NIPA", "table": "T10101", "line_code": 1, "frequency": "Q", "years": "2019-2025"},
63
- {"id": "gdp_real", "dataset": "NIPA", "table": "T10106", "line_code": 1, "frequency": "Q", "years": "2019-2025"},
64
- {"id": "state_real", "dataset": "Regional", "table": "SAGDP9", "line_code": 1, "geo_fips": "STATE", "years": "2019-2025"},
65
- {"id": "va_ind", "dataset": "GDPbyIndustry", "table": "TVA105", "frequency": "A", "years": "2024-2025"}]}
66
- ```
67
- ```json
68
- {"description": "Per capita personal income, two counties, last five years",
69
- "requests": [{"id": "cty_pi", "dataset": "Regional", "table": "CAINC1", "line_code": [1, 3],
70
- "geo_fips": ["06037", "17031"], "years": "LAST5"}]}
71
- ```
72
- ```json
73
- {"description": "U.S. goods trade balance with China (needs a key)",
74
- "requests": [{"id": "ita", "dataset": "ITA",
75
- "params": {"Indicator": "BalGds", "AreaOrCountry": "China", "Frequency": "A", "Year": "2023,2024"}}]}
76
- ```
77
- `years`: `"2019-2025"`, a list, `"ALL"` or `"LAST5"`; `line_code`: a number, list or `"ALL"` (NIPA: BEA
78
- sends the whole table and the rows are filtered); `geo_fips`: `STATE`, `COUNTY`, a postal code (its
79
- counties), FIPS codes (`"06"` = `06000`). Keys a dataset does not use are reported in the result's notes. When a growth
80
- rate is computed from levels, also request BEA's published percent change so it can be checked.
81
-
82
- ## Data format and traps
83
- `fetch` writes `data/bea/`: `bea_data.csv` (tidy: `request_id, dataset, table, line, series_code,
84
- description, geo_fips, geo_name, geo_level, industry, time_period, date, year, subperiod, frequency, value,
85
- flag, unit, metric, unit_mult, note_ref, dims`), `notes.csv` (BEA's footnotes: units, reference year, what
86
- the U.S. row means, flag codes), `request.json` (calls without the key, bulk files, route, vintage,
87
- checksums) and `README.md`. Read the README and `notes.csv` before analysing (the NIPA bulk files carry no
88
- footnotes: on the `bulk` route `notes.csv` has only the pack's own note; read a table's footnotes on its
89
- apps.bea.gov page, or fetch it through the API with a key). `line` holds BEA's line numbers, which can carry
90
- letters: match lines exactly (as text, or with `series_code`), never by integer order.
91
- - **Units:** `value` is as BEA prints it; base units = value x 10^`unit_mult` (`compute` `derive`:
92
- `value * pow(10, unit_mult)`).
93
- Check `unit` and `metric` (current dollars, chained dollars, index, percent change) for every series.
94
- - **Special values** `(D)` suppressed, `(NA)` not available, `(NM)` not meaningful, `(L)` under $50,000 or 10
95
- jobs, `(S)`, `(X)`, `(*)` (MNE: rounds to zero): `value` is empty and the code is in `flag`. Never a zero;
96
- list the rows with a `flag` and drop or footnote the area.
97
- - **No sums of chained dollars**, of components or of states; shares from current dollars; drivers of growth
98
- from BEA's contributions tables (T10102, SAGDP11). SAAR levels are averaged, not added, for annual values.
99
- - **Growth measures differ** by a point or more: quarterly at a compound annual rate (BEA's headline:
100
- (level / previous level)^4 - 1), year over year (T10111), Q4 over Q4, annual average; "since <year>":
101
- cumulative change and the average annual rate. Name the measure everywhere; show the alternatives as a
102
- sensitivity.
103
- - **Check against BEA's published numbers** (docs/datasets.md section 5): growth
104
- from T10106 levels vs T10101; the U.S. row of SAGDP9 vs T10106 line 1. A mismatch beyond rounding is an
105
- error; a difference from an older release is a revision (compare dates with the vintage in README.md).
106
- - **Vintage:** BEA serves only its latest estimates (advance, second, third; annual updates each September;
107
- comprehensive updates every five years). Record the release date; old vintages are at apps.bea.gov/histdata.
108
- - **Geography:** every row has `geo_level` (nation, region, state, county, msa); a COUNTY bulk download also
109
- holds state and U.S. rows: filter before summing. `STATE` = 50 states + D.C. + U.S. (say whether D.C. is
110
- ranked). Since February 2026 BEA no longer produces GDP or personal income for metro areas: sum component
111
- counties' current-dollar values and say so. Rank on unrounded values; name near-ties.
112
- - **Calendar years** everywhere (NIPA federal spending too, unlike fiscal-year budget data). NIPA line
113
- numbers change at comprehensive updates: check the description or series code, not only the line.
114
- GDP-by-industry line numbers differ between tables (TVA106 has an extra line): match by description.
115
- - **No standard errors** exist for BEA estimates: never "statistically different".
116
- - Analysis: build growth rates, shares and comparisons with `compute` on `data/bea/bea_data.csv`, and check each
117
- headline against the published table.
118
-
119
- ## Access
120
- - **Key** `BEA_API_KEY` (free, https://apps.bea.gov/API/signup/; BEA emails it and it works only after the
121
- activation link is clicked). Found, in order, in the environment, `BEA_API_KEY_FILE`, keys.json, Claude Code
122
- settings.json and `~/.bea/api_key`; the user stores it with `npx -y data-analyst-mcp setup bea` in their own
123
- terminal. Never ask for the key in chat. BEA puts it in the URL and echoes it in every
124
- reply: the server scrubs both (the key and the USERID echo); never build your own API URLs.
125
- - **Limits** per key: 100 requests, 100 MB and 30 errors a minute; going over blocks the key for a minute to
126
- an hour (HTTP 429, never retried). The client spaces calls 0.75 s, waits before crossing 100 MB a minute,
127
- stops after 30 errors a minute or 10 in a run, validates table and line names against cached metadata
128
- first, and checks dataset parameter rules offline (`invalid_request`), so errors are not spent.
129
- - **Routes** (`route` in the result): `reuse_existing` (`data/bea/` already holds the request; `force: true`
130
- downloads again), `api` (key works), `bulk` (no usable key and every request is in the bulk files: NIPA
131
- flat files, state and county zips, GDP-by-industry workbooks; same latest estimates; the spec's
132
- `"prefer": "bulk"` forces it, `"prefer": "api"` never falls back). A key BEA rejects or has locked out falls
133
- back to the bulk files when they hold every request. Errors: `key_missing` (no key and a request needs the
134
- API: the user runs `npx -y data-analyst-mcp setup bea`, or `manual_bundle`), `key_rejected`,
135
- `rate_limited`, `agency_rejected` (fix the spec; never loop: errors count against the key) and
136
- `agency_unavailable` (BEA unreachable; never invent or recall data). Bulk files are cached in
137
- `<cache_root>/bea/bulk` (`DATA_ANALYST_CACHE` sets the root) and revalidated by Last-Modified; NIPA files are
138
- 12-37 MB, county zips up to 50 MB.
139
- - **Manual download:** `manual_bundle` writes `manual_download/`: `INSTRUCTIONS.md` with the links, and
140
- `download_data.sh` (macOS, Linux) and `download_data.ps1` (Windows), one-command scripts that download the
141
- public files and ask for the key with hidden input only when an API request needs it. Send both scripts and
142
- INSTRUCTIONS.md, and give the one command for the user's system (`user_commands`). BEA repeats the key inside
143
- API replies: `ingest` removes it. Then `ingest` with the uploaded files or their folder (on a hosted server,
144
- `files: ["uploads"]`). Say in the methods that the files were downloaded by hand.
145
-
146
- ## Citation and terms
147
- "U.S. Bureau of Economic Analysis, <tables>, <route> (accessed <date>)." The exact line is in
148
- `data/bea/README.md`; include the release (vintage) when it matters. Source line: "Analyst calculations using
149
- data from the Bureau of Economic Analysis." BEA data are public domain: redistribution allowed (data files
150
- may ship in a replication package). Products that use the API must show: "This product uses the Bureau of
151
- Economic Analysis (BEA) Data API but is not endorsed or certified by BEA." (the API terms' wording) Do not
152
- imply BEA endorsement.
1
+ # Bureau of Economic Analysis (BEA) Data API and bulk files
2
+ Depth: deep. Key: required (BEA_API_KEY) for the API; the bulk route needs none. U.S. national accounts
3
+ (GDP, income, PCE and its prices, saving, profits, government), state and county GDP and income, regional
4
+ price parities, GDP by industry, trade and international accounts, multinationals, fixed assets, input-output.
5
+
6
+ ## When to use
7
+ - GDP and its growth, contributions, prices and deflators; personal income, disposable income, saving rate;
8
+ PCE and core PCE price indexes (the Federal Reserve's inflation measure); corporate profits; NIPA
9
+ government receipts and spending (calendar years); GDP and personal income by state and county; per capita
10
+ income; RPPs; value added and gross output by industry; goods and services trade balances by country;
11
+ current account; investment position; direct investment; capital stocks.
12
+ - Not here: CPI, jobs, unemployment, wages by occupation (bls); budget data by fiscal year (treasury);
13
+ market interest rates (treasury-yields; fred); forecasts (BEA publishes history only); monthly GDP.
14
+ - The deliverable decides the work: data only (download, short preview, stop), an answer (compute with
15
+ `compute`, answer with the numbers, measure and vintage), or a report (`guide`'s report steps).
16
+
17
+ ## Endpoints and datasets
18
+ One API endpoint (`https://apps.bea.gov/api/data`, GET, key in `UserID`), 13 datasets. Bulk files serve
19
+ the most used ones without a key and count against no limit.
20
+
21
+ | `dataset` | What | Spec keys | Bulk (no key)? |
22
+ |---|---|---|---|
23
+ | `NIPA` | national accounts tables `T10101` ... (titles: `request_schema` search) | `table`, `frequency` A/Q/M, `years`, `line_code` | yes (NIPA flat files) |
24
+ | `NIUnderlyingDetail` | detail tables `U20305` ... (lower quality) | same | no (flat files hold only shared lines) |
25
+ | `FixedAssets` | `FAAt101` ... annual | `table`, `years` | no |
26
+ | `Regional` | state `SA*`/`SQ*`, county `CA*`, metro `MA*` tables | `table`, `line_code`, `geo_fips`, `years` | yes for STATE, COUNTY, postal code (its counties), FIPS lists, MARPP |
27
+ | `GDPbyIndustry` | workbook codes `TVA101`-`TVA113`, `TGO1xx`, `TII1xx` | `table`, `frequency` A/Q, `years` | yes (public workbooks) |
28
+ | `GDPbyIndustry` (API) | `TableID` 1, 5, 6, 25 ...; `Industry` filters | `params` | no |
29
+ | `UnderlyingGDPbyIndustry`, `ITA`, `IIP`, `IntlServTrade`, `IntlServSTA`, `MNE`, `InputOutput` | see `request_schema` with `names: ["<name>"]` | `params` (raw API names) | no |
30
+
31
+ Verified lines (September 2026 vintage): T10101 line 1 real GDP percent change (annual rate); T10106 line 1
32
+ real GDP (millions of chained 2017 dollars, SAAR); T10105 line 1 nominal GDP; T10111 line 1 year-over-year
33
+ real GDP change; T10102 contributions; T20100 lines 1/27/37/35/40 personal income / DPI / real DPI / saving
34
+ rate / population (annual and quarterly only: monthly values are in T20600, whose line numbers differ, so
35
+ check them with the search `lines T20600`; a table is monthly only when its title says so, and the bulk route refuses
36
+ frequency M for any other table); T20804 lines 1/25 PCE / core PCE price index (monthly; published changes: T20807 month over month, not
37
+ annualized, T20811 lines 32/37 over 12 months); T70100 lines 1/3 GDP and income
38
+ per capita (BEA divides by unrounded population: real GDP over T70100's population, published in thousands,
39
+ can miss the published per-capita level by just over 0.5 dollars; allow for that rounding in the benchmark and
40
+ say so). Federal civilian wages per FTE (T60600D) jump in 2024-2025: Deferred Resignation staff on paid
41
+ administrative leave stayed on the payroll while BEA cut the quantity of federal labor (FAQ 1479,
42
+ bea.gov/help/faq/1479): never read those years as federal pay raises; use OPM pay or the GS raise. Regional: SAGDP2/SAGDP9 line 1 all-industry total (current / chained 2017 dollars); SAINC1 and
43
+ CAINC1 lines 1/2/3 personal income / population / per capita income; SAINC4/CAINC4 lines 10/20/30; SARPP
44
+ and MARPP line 1 all-items RPP. API names may carry an `N` (`SAGDP9N`); the bulk files drop it: both work.
45
+ BEA marks nothing as preliminary in the data, but the latest quarter or year of every table is an early
46
+ estimate that BEA will revise: register facts from it with `preliminary: true` in `facts` and say so. A year that has
47
+ been through an annual update (published at the end of September) is revised, not early: say "subject to
48
+ revision at the next annual update" instead.
49
+ More tables, the question-to-table map and concepts: `docs/datasets.md`. API parameters, response quirks,
50
+ error codes and limits: `docs/bea_api.md`. Report conventions: `docs/report_patterns.md`.
51
+
52
+ Discovery with `request_schema` (no key unless noted): `search: "real gross domestic product"` (NIPA titles
53
+ and workbook tables), `search: "Regional income"` (the first word names the dataset; API datasets need a key),
54
+ `search: "lines T10106"` (lines and series codes), `names: ["ITA"]` (required parameters, rules, spec keys,
55
+ and with a key BEA's current parameters); with a key (cached a day): `search: "values Regional TableName"`,
56
+ `search: "values Regional LineCode TableName=SAINC1"`. `source_brief` lists the 13 datasets.
57
+
58
+ ## Spec examples
59
+ ```json
60
+ {"description": "Real GDP growth, national and by state, 2019 to 2025",
61
+ "requests": [
62
+ {"id": "gdp_pct", "dataset": "NIPA", "table": "T10101", "line_code": 1, "frequency": "Q", "years": "2019-2025"},
63
+ {"id": "gdp_real", "dataset": "NIPA", "table": "T10106", "line_code": 1, "frequency": "Q", "years": "2019-2025"},
64
+ {"id": "state_real", "dataset": "Regional", "table": "SAGDP9", "line_code": 1, "geo_fips": "STATE", "years": "2019-2025"},
65
+ {"id": "va_ind", "dataset": "GDPbyIndustry", "table": "TVA105", "frequency": "A", "years": "2024-2025"}]}
66
+ ```
67
+ ```json
68
+ {"description": "Per capita personal income, two counties, last five years",
69
+ "requests": [{"id": "cty_pi", "dataset": "Regional", "table": "CAINC1", "line_code": [1, 3],
70
+ "geo_fips": ["06037", "17031"], "years": "LAST5"}]}
71
+ ```
72
+ ```json
73
+ {"description": "U.S. goods trade balance with China (needs a key)",
74
+ "requests": [{"id": "ita", "dataset": "ITA",
75
+ "params": {"Indicator": "BalGds", "AreaOrCountry": "China", "Frequency": "A", "Year": "2023,2024"}}]}
76
+ ```
77
+ `years`: `"2019-2025"`, a list, `"ALL"` or `"LAST5"`; `line_code`: a number, list or `"ALL"` (NIPA: BEA
78
+ sends the whole table and the rows are filtered); `geo_fips`: `STATE`, `COUNTY`, a postal code (its
79
+ counties), FIPS codes (`"06"` = `06000`). Keys a dataset does not use are reported in the result's notes. When a growth
80
+ rate is computed from levels, also request BEA's published percent change so it can be checked.
81
+
82
+ ## Data format and traps
83
+ `fetch` writes `data/bea/`: `bea_data.csv` (tidy: `request_id, dataset, table, line, series_code,
84
+ description, geo_fips, geo_name, geo_level, industry, time_period, date, year, subperiod, frequency, value,
85
+ flag, unit, metric, unit_mult, note_ref, dims`), `notes.csv` (BEA's footnotes: units, reference year, what
86
+ the U.S. row means, flag codes), `request.json` (calls without the key, bulk files, route, vintage,
87
+ checksums) and `README.md`. Read the README and `notes.csv` before analysing (the NIPA bulk files carry no
88
+ footnotes: on the `bulk` route `notes.csv` has only the pack's own note; read a table's footnotes on its
89
+ apps.bea.gov page, or fetch it through the API with a key). `line` holds BEA's line numbers, which can carry
90
+ letters: match lines exactly (as text, or with `series_code`), never by integer order.
91
+ - **Units:** `value` is as BEA prints it; base units = value x 10^`unit_mult` (`compute` `derive`:
92
+ `value * pow(10, unit_mult)`).
93
+ Check `unit` and `metric` (current dollars, chained dollars, index, percent change) for every series.
94
+ - **Special values** `(D)` suppressed, `(NA)` not available, `(NM)` not meaningful, `(L)` under $50,000 or 10
95
+ jobs, `(S)`, `(X)`, `(*)` (MNE: rounds to zero): `value` is empty and the code is in `flag`. Never a zero;
96
+ list the rows with a `flag` and drop or footnote the area.
97
+ - **No sums of chained dollars**, of components or of states; shares from current dollars; drivers of growth
98
+ from BEA's contributions tables (T10102, SAGDP11). SAAR levels are averaged, not added, for annual values.
99
+ - **Growth measures differ** by a point or more: quarterly at a compound annual rate (BEA's headline:
100
+ (level / previous level)^4 - 1), year over year (T10111), Q4 over Q4, annual average; "since <year>":
101
+ cumulative change and the average annual rate. Name the measure everywhere; show the alternatives as a
102
+ sensitivity.
103
+ - **Check against BEA's published numbers** (docs/datasets.md section 5): growth
104
+ from T10106 levels vs T10101; the U.S. row of SAGDP9 vs T10106 line 1. A mismatch beyond rounding is an
105
+ error; a difference from an older release is a revision (compare dates with the vintage in README.md).
106
+ - **Vintage:** BEA serves only its latest estimates (advance, second, third; annual updates each September;
107
+ comprehensive updates every five years). Record the release date; old vintages are at apps.bea.gov/histdata.
108
+ - **Geography:** every row has `geo_level` (nation, region, state, county, msa); a COUNTY bulk download also
109
+ holds state and U.S. rows: filter before summing. `STATE` = 50 states + D.C. + U.S. (say whether D.C. is
110
+ ranked). Since February 2026 BEA no longer produces GDP or personal income for metro areas: sum component
111
+ counties' current-dollar values and say so. Rank on unrounded values; name near-ties.
112
+ - **Calendar years** everywhere (NIPA federal spending too, unlike fiscal-year budget data). NIPA line
113
+ numbers change at comprehensive updates: check the description or series code, not only the line.
114
+ GDP-by-industry line numbers differ between tables (TVA106 has an extra line): match by description.
115
+ - **No standard errors** exist for BEA estimates: never "statistically different".
116
+ - Analysis: build growth rates, shares and comparisons with `compute` on `data/bea/bea_data.csv`, and check each
117
+ headline against the published table.
118
+
119
+ ## Access
120
+ - **Key** `BEA_API_KEY` (free, https://apps.bea.gov/API/signup/; BEA emails it and it works only after the
121
+ activation link is clicked). Found, in order, in the environment, `BEA_API_KEY_FILE`, keys.json, Claude Code
122
+ settings.json and `~/.bea/api_key`; the user stores it with `npx -y data-analyst-mcp setup bea` in their own
123
+ terminal. Never ask for the key in chat. BEA puts it in the URL and echoes it in every
124
+ reply: the server scrubs both (the key and the USERID echo); never build your own API URLs.
125
+ - **Limits** per key: 100 requests, 100 MB and 30 errors a minute; going over blocks the key for a minute to
126
+ an hour (HTTP 429, never retried). The client spaces calls 0.75 s, waits before crossing 100 MB a minute,
127
+ stops after 30 errors a minute or 10 in a run, validates table and line names against cached metadata
128
+ first, and checks dataset parameter rules offline (`invalid_request`), so errors are not spent.
129
+ - **Routes** (`route` in the result): `reuse_existing` (`data/bea/` already holds the request; `force: true`
130
+ downloads again), `api` (key works), `bulk` (no usable key and every request is in the bulk files: NIPA
131
+ flat files, state and county zips, GDP-by-industry workbooks; same latest estimates; the spec's
132
+ `"prefer": "bulk"` forces it, `"prefer": "api"` never falls back). A key BEA rejects or has locked out falls
133
+ back to the bulk files when they hold every request. Errors: `key_missing` (no key and a request needs the
134
+ API: the user runs `npx -y data-analyst-mcp setup bea`, or `manual_bundle`), `key_rejected`,
135
+ `rate_limited`, `agency_rejected` (fix the spec; never loop: errors count against the key) and
136
+ `agency_unavailable` (BEA unreachable; never invent or recall data). Bulk files are cached in
137
+ `<cache_root>/bea/bulk` (`DATA_ANALYST_CACHE` sets the root) and revalidated by Last-Modified; NIPA files are
138
+ 12-37 MB, county zips up to 50 MB.
139
+ - **Manual download:** `manual_bundle` writes `manual_download/`: `INSTRUCTIONS.md` with the links, and
140
+ `download_data.sh` (macOS, Linux) and `download_data.ps1` (Windows), one-command scripts that download the
141
+ public files and ask for the key with hidden input only when an API request needs it. Send both scripts and
142
+ INSTRUCTIONS.md, and give the one command for the user's system (`user_commands`). BEA repeats the key inside
143
+ API replies: `ingest` removes it. Then `ingest` with the uploaded files or their folder (on a hosted server,
144
+ `files: ["uploads"]`). Say in the methods that the files were downloaded by hand.
145
+
146
+ ## Citation and terms
147
+ "U.S. Bureau of Economic Analysis, <tables>, <route> (accessed <date>)." The exact line is in
148
+ `data/bea/README.md`; include the release (vintage) when it matters. Source line: "Analyst calculations using
149
+ data from the Bureau of Economic Analysis." BEA data are public domain: redistribution allowed (data files
150
+ may ship in a replication package). Products that use the API must show: "This product uses the Bureau of
151
+ Economic Analysis (BEA) Data API but is not endorsed or certified by BEA." (the API terms' wording) Do not
152
+ imply BEA endorsement.
@@ -0,0 +1,150 @@
1
+ {
2
+ "base_url": "https://api.ojp.gov/bjsdataset/v1",
3
+ "timeout": 90,
4
+ "endpoints": {
5
+ "query": {
6
+ "path": "/{dataset}.json",
7
+ "method": "GET",
8
+ "description": "NCVS Select records from BJS's API (one row per victimization, person or household, 1993 on, with weights): filter with $where and pick columns with $select. Aggregate SoQL (sum, count, $group) is refused by the site's bot check: aggregate the rows with compute.",
9
+ "params": {
10
+ "dataset": {
11
+ "in": "path",
12
+ "required": true,
13
+ "catalog": true,
14
+ "desc": "personal_victimization, personal_population, household_victimization, household_population (or the 4x4 id)"
15
+ },
16
+ "$select": {
17
+ "desc": "plain columns only, comma-separated: year, newcrime, newoff, newwgt"
18
+ },
19
+ "$where": {
20
+ "desc": "SoQL filter; every column is text, so quote values: year = '2024' AND newcrime = '1'"
21
+ },
22
+ "$order": {
23
+ "desc": "SoQL order; default :id gives stable paging"
24
+ }
25
+ },
26
+ "defaults": {
27
+ "$order": ":id"
28
+ },
29
+ "records": "",
30
+ "paging": {
31
+ "type": "offset",
32
+ "limit_param": "$limit",
33
+ "offset_param": "$offset",
34
+ "size": 50000,
35
+ "manual_size": 50000
36
+ },
37
+ "max_rows": 1000000,
38
+ "missing": [
39
+ ""
40
+ ],
41
+ "flatten": true
42
+ },
43
+ "statistical_table": {
44
+ "path": "https://bjs.ojp.gov/document/{report}.zip",
45
+ "method": "GET",
46
+ "description": "One CSV table from a BJS report's table package (zip): Criminal Victimization, Prisoners, Jail Inmates, Probation and Parole, Capital Punishment. Default: every line numbered (row, col1...) to find the header lines; then header_lines (e.g. '11-12') names the columns.",
47
+ "params": {
48
+ "report": {
49
+ "in": "path",
50
+ "required": true,
51
+ "catalog": true,
52
+ "desc": "report package code or alias: cv24 (criminal_victimization_2024), p23st, ji24st, ppus23, cp22st ..."
53
+ },
54
+ "member": {
55
+ "in": "records",
56
+ "required": true,
57
+ "desc": "the table's file in the zip, e.g. cv24t01.csv (t = table, at = appendix table, f = figure); a glob works"
58
+ },
59
+ "header_lines": {
60
+ "in": "records",
61
+ "desc": "the table's header line numbers, e.g. '11-12' (read them from a first fetch without it)"
62
+ },
63
+ "header_row": {
64
+ "in": "records",
65
+ "desc": "one header line instead of header_lines; 0 (default) returns every line numbered"
66
+ },
67
+ "carry": {
68
+ "in": "records",
69
+ "desc": "which header lines span to the right over blank cells: top (default), all, none; check the names against the numbered lines"
70
+ }
71
+ },
72
+ "defaults": {
73
+ "header_row": 0
74
+ },
75
+ "records": "$zip:",
76
+ "paging": {
77
+ "type": "none"
78
+ },
79
+ "max_rows": 20000
80
+ }
81
+ },
82
+ "catalog": {
83
+ "personal_victimization": {
84
+ "id": "gcuy-rt5g",
85
+ "endpoint": "query",
86
+ "name": "NCVS Select - Personal Victimization",
87
+ "description": "One row per personal victimization (rape/sexual assault, robbery, aggravated and simple assault, personal theft), 1993-2024, with victim and incident characteristics; weight newwgt (series-adjusted) gives victimizations."
88
+ },
89
+ "personal_population": {
90
+ "id": "r4j4-fdwx",
91
+ "endpoint": "query",
92
+ "name": "NCVS Select - Personal Population",
93
+ "description": "Every interviewed person age 12 or older by quarter, 1993-2024, with demographics; weight wgtpercy gives persons (the rate denominator); victim and wgt_ovam_per for prevalence."
94
+ },
95
+ "household_victimization": {
96
+ "id": "gkck-euys",
97
+ "endpoint": "query",
98
+ "name": "NCVS Select - Household Victimization",
99
+ "description": "One row per household property victimization (burglary/trespassing, motor-vehicle theft, other theft), 1993-2024; weight newwgt."
100
+ },
101
+ "household_population": {
102
+ "id": "ya4e-n9zp",
103
+ "endpoint": "query",
104
+ "name": "NCVS Select - Household Population",
105
+ "description": "Every interviewed household by quarter, 1993-2024; weight wgthhcy gives households (the property-crime rate denominator)."
106
+ },
107
+ "criminal_victimization_2024": {
108
+ "id": "cv24",
109
+ "endpoint": "statistical_table",
110
+ "name": "Criminal Victimization, 2024 (NCJ 310547) tables",
111
+ "description": "Official NCVS numbers, rates per 1,000 and standard errors: violent and property victimization by type of crime 2020-2024 (cv24t01...), reporting to police, victim characteristics; appendix tables back to 1993 (cv24at01)."
112
+ },
113
+ "criminal_victimization_2023": {
114
+ "id": "cv23",
115
+ "endpoint": "statistical_table",
116
+ "name": "Criminal Victimization, 2023 tables",
117
+ "description": "The 2023 report's tables (cv23t01 ...)."
118
+ },
119
+ "prisoners_2023": {
120
+ "id": "p23st",
121
+ "endpoint": "statistical_table",
122
+ "name": "Prisoners in 2023 - Statistical Tables (NCJ 310197)",
123
+ "description": "National Prisoner Statistics: prisoners under state and federal jurisdiction by state and sex, imprisonment rates, admissions and releases, by offense, race and age (p23stt01 ... p23stt24, p23stat01 appendix)."
124
+ },
125
+ "jail_inmates_2024": {
126
+ "id": "ji24st",
127
+ "endpoint": "statistical_table",
128
+ "name": "Jail Inmates in 2024 - Statistical Tables",
129
+ "description": "Annual Survey of Jails: jail population, incarceration rates, admissions, turnover, conviction status (ji24stt01 ...)."
130
+ },
131
+ "jail_inmates_2023": {
132
+ "id": "ji23st",
133
+ "endpoint": "statistical_table",
134
+ "name": "Jail Inmates in 2023 - Statistical Tables",
135
+ "description": "The 2023 jail tables."
136
+ },
137
+ "probation_parole_2023": {
138
+ "id": "ppus23",
139
+ "endpoint": "statistical_table",
140
+ "name": "Probation and Parole in the United States, 2023",
141
+ "description": "Annual Probation and Parole Surveys: adults on probation and parole by state, entries and exits (ppus23t01 ..., figures ppus23f..)."
142
+ },
143
+ "capital_punishment_2022": {
144
+ "id": "cp22st",
145
+ "endpoint": "statistical_table",
146
+ "name": "Capital Punishment, 2022 - Statistical Tables",
147
+ "description": "Prisoners under sentence of death and executions by state and year."
148
+ }
149
+ }
150
+ }
@@ -0,0 +1,114 @@
1
+ {
2
+ "id": "bjs",
3
+ "title": "Bureau of Justice Statistics: National Crime Victimization Survey and corrections statistics",
4
+ "agency": "U.S. Department of Justice, Bureau of Justice Statistics",
5
+ "depth": "standard",
6
+ "domains": [
7
+ "crime",
8
+ "criminal justice",
9
+ "public safety",
10
+ "corrections"
11
+ ],
12
+ "keywords": [
13
+ "bjs",
14
+ "bureau of justice statistics",
15
+ "ncvs",
16
+ "national crime victimization survey",
17
+ "victimization",
18
+ "victimization rate",
19
+ "crime victims",
20
+ "crimes not reported to police",
21
+ "reporting to police",
22
+ "violent victimization",
23
+ "property victimization",
24
+ "rape",
25
+ "sexual assault",
26
+ "robbery",
27
+ "aggravated assault",
28
+ "simple assault",
29
+ "burglary",
30
+ "motor vehicle theft",
31
+ "domestic violence",
32
+ "intimate partner violence",
33
+ "prisoners",
34
+ "prison population",
35
+ "imprisonment rate",
36
+ "incarceration",
37
+ "national prisoner statistics",
38
+ "jail population",
39
+ "jail inmates",
40
+ "probation",
41
+ "parole",
42
+ "capital punishment",
43
+ "death row",
44
+ "executions"
45
+ ],
46
+ "questions": [
47
+ "violent victimization rate per 1,000 persons by year",
48
+ "share of violent crimes reported to police",
49
+ "number of robberies or assaults according to the victimization survey",
50
+ "property crime victimization rate for households",
51
+ "state and federal prison population by state",
52
+ "imprisonment rate per 100,000 residents",
53
+ "jail population and incarceration rate",
54
+ "adults on probation or parole by state",
55
+ "prisoners under sentence of death by state"
56
+ ],
57
+ "homepage": "https://bjs.ojp.gov/",
58
+ "terms_url": "https://bjs.ojp.gov/national-crime-victimization-survey-ncvs-api",
59
+ "auth": {
60
+ "env": null,
61
+ "required": "none",
62
+ "placement": "none",
63
+ "signup_url": null,
64
+ "echoes_key": false
65
+ },
66
+ "limits": {
67
+ "rps": 1,
68
+ "burst": 2,
69
+ "max_rows": 1000000
70
+ },
71
+ "routes": {
72
+ "api": {
73
+ "base": "https://api.ojp.gov/bjsdataset/v1",
74
+ "probe": "https://api.ojp.gov/bjsdataset/v1/gcuy-rt5g.json?$limit=1",
75
+ "hosts": [
76
+ "api.ojp.gov",
77
+ "bjs.ojp.gov"
78
+ ]
79
+ },
80
+ "manual": {
81
+ "how": "NCVS Select: open https://api.ojp.gov/bjsdataset/v1/<id>.csv?$where=year='2024'&$limit=200000 in a browser (ids: gcuy-rt5g personal victimization, r4j4-fdwx personal population, gkck-euys household victimization, ya4e-n9zp household population) and save the CSV. Report tables: download https://bjs.ojp.gov/document/<code>.zip (e.g. cv24, p23st) from the report page. Upload the file with ingest."
82
+ }
83
+ },
84
+ "cache": {
85
+ "mode": "run_only",
86
+ "ttl_hours": null,
87
+ "why": "Datasets are replaced when a new year is added; data/ is reused within a run."
88
+ },
89
+ "redistribution": {
90
+ "mode": "allowed",
91
+ "why": "BJS data and tables are U.S. government works in the public domain (17 U.S.C. 105); NCVS Select files are public-use, de-identified records."
92
+ },
93
+ "notices": [],
94
+ "retention": null,
95
+ "citation": "U.S. Department of Justice, Bureau of Justice Statistics, {dataset}, bjs.ojp.gov, retrieved {retrieved_long}.",
96
+ "audit_hooks": [],
97
+ "clarify": [
98
+ "Published estimate or own tabulation? BJS's report tables (statistical_table, e.g. cv24) carry the official numbers, rates and standard errors; tabulating NCVS Select records with the weights reproduces the numbers (2024 violent victimizations: 6,671,636 vs. 6,671,640 published), but standard errors need the survey design and are not computed here. Default: the report table when it has the breakdown asked for.",
99
+ "Victimizations, incidents or prevalence? NCVS counts victimizations by default (one per victim per crime); prevalence counts unique victims (weight wgt_ovam_per and the victim flag). Default: victimizations and the rate per 1,000 persons age 12 or older (households for property crime).",
100
+ "Which year? 2024 comes from the legacy half of a split sample (larger standard errors). Collection year: crimes are counted in the year of the interview, not the year they happened."
101
+ ],
102
+ "formats": [
103
+ "json",
104
+ "csv",
105
+ "zip"
106
+ ],
107
+ "aliases": [
108
+ "BJS",
109
+ "NCVS",
110
+ "Bureau of Justice Statistics",
111
+ "National Crime Victimization Survey",
112
+ "National Prisoner Statistics"
113
+ ]
114
+ }