data-analyst-mcp 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +286 -262
- package/dist/adapters/bjs.d.ts +13 -0
- package/dist/adapters/bjs.js +28 -0
- package/dist/adapters/bjs.js.map +1 -0
- package/dist/adapters/cbp.d.ts +5 -0
- package/dist/adapters/cbp.js +64 -0
- package/dist/adapters/cbp.js.map +1 -0
- package/dist/adapters/cdc-wonder.d.ts +5 -0
- package/dist/adapters/cdc-wonder.js +68 -0
- package/dist/adapters/cdc-wonder.js.map +1 -0
- package/dist/adapters/cpsc.d.ts +4 -0
- package/dist/adapters/cpsc.js +125 -0
- package/dist/adapters/cpsc.js.map +1 -0
- package/dist/adapters/fhwa.d.ts +9 -0
- package/dist/adapters/fhwa.js +16 -0
- package/dist/adapters/fhwa.js.map +1 -0
- package/dist/adapters/foreign-assistance.d.ts +9 -0
- package/dist/adapters/foreign-assistance.js +42 -0
- package/dist/adapters/foreign-assistance.js.map +1 -0
- package/dist/adapters/hud-ahar.d.ts +3 -0
- package/dist/adapters/hud-ahar.js +80 -0
- package/dist/adapters/hud-ahar.js.map +1 -0
- package/dist/adapters/nces.d.ts +10 -0
- package/dist/adapters/nces.js +32 -0
- package/dist/adapters/nces.js.map +1 -0
- package/dist/adapters/nsf.d.ts +11 -0
- package/dist/adapters/nsf.js +25 -0
- package/dist/adapters/nsf.js.map +1 -0
- package/dist/adapters/onrr.d.ts +9 -0
- package/dist/adapters/onrr.js +35 -0
- package/dist/adapters/onrr.js.map +1 -0
- package/dist/adapters/sba.d.ts +10 -0
- package/dist/adapters/sba.js +134 -0
- package/dist/adapters/sba.js.map +1 -0
- package/dist/adapters/treasury-tic.d.ts +30 -0
- package/dist/adapters/treasury-tic.js +149 -0
- package/dist/adapters/treasury-tic.js.map +1 -0
- package/dist/adapters/uscourts.d.ts +8 -0
- package/dist/adapters/uscourts.js +8 -0
- package/dist/adapters/uscourts.js.map +1 -0
- package/dist/analysis/cite.d.ts +9 -1
- package/dist/analysis/cite.js +9 -2
- package/dist/analysis/cite.js.map +1 -1
- package/dist/bin/cli.d.ts +2 -0
- package/dist/bin/cli.js +17 -0
- package/dist/bin/cli.js.map +1 -1
- package/dist/core/generic-rest.js +42 -17
- package/dist/core/generic-rest.js.map +1 -1
- package/dist/core/guard.d.ts +32 -0
- package/dist/core/guard.js +176 -0
- package/dist/core/guard.js.map +1 -0
- package/dist/core/http.d.ts +10 -0
- package/dist/core/http.js +36 -7
- package/dist/core/http.js.map +1 -1
- package/dist/core/keys.d.ts +13 -3
- package/dist/core/keys.js +67 -7
- package/dist/core/keys.js.map +1 -1
- package/dist/core/package.d.ts +12 -3
- package/dist/core/package.js +56 -12
- package/dist/core/package.js.map +1 -1
- package/dist/core/secret_patterns.d.ts +6 -0
- package/dist/core/secret_patterns.js +20 -0
- package/dist/core/secret_patterns.js.map +1 -0
- package/dist/core/tabular.d.ts +43 -1
- package/dist/core/tabular.js +149 -6
- package/dist/core/tabular.js.map +1 -1
- package/dist/envelope.js +3 -1
- package/dist/envelope.js.map +1 -1
- package/dist/index.d.ts +29 -22
- package/dist/index.js +45 -46
- package/dist/index.js.map +1 -1
- package/dist/remote/app.js +87 -31
- package/dist/remote/app.js.map +1 -1
- package/dist/remote/oauth.js +8 -1
- package/dist/remote/oauth.js.map +1 -1
- package/dist/remote/pages.d.ts +3 -7
- package/dist/remote/pages.js +49 -19
- package/dist/remote/pages.js.map +1 -1
- package/dist/remote/sign.d.ts +7 -1
- package/dist/remote/sign.js +33 -7
- package/dist/remote/sign.js.map +1 -1
- package/dist/remote/store.js +14 -5
- package/dist/remote/store.js.map +1 -1
- package/dist/report/audit_report.js +29 -7
- package/dist/report/audit_report.js.map +1 -1
- package/dist/report/build_report.js +34 -4
- package/dist/report/build_report.js.map +1 -1
- package/dist/report/method_audit.js +10 -1
- package/dist/report/method_audit.js.map +1 -1
- package/dist/report/scan_secrets.d.ts +4 -1
- package/dist/report/scan_secrets.js +38 -18
- package/dist/report/scan_secrets.js.map +1 -1
- package/dist/server.d.ts +3 -1
- package/dist/server.js +46 -13
- package/dist/server.js.map +1 -1
- package/dist/tools.js +27 -6
- package/dist/tools.js.map +1 -1
- package/guide/WORKFLOW.md +134 -134
- package/guide/assets/disclaimer.txt +1 -1
- package/guide/assets/download_data.ps1 +164 -162
- package/guide/assets/download_data.sh +8 -2
- package/guide/assets/report_template.html +597 -597
- package/guide/references/routing.md +198 -171
- package/guide/references/style_guide.md +398 -398
- package/package.json +56 -56
- package/packs/acf/endpoints.json +114 -114
- package/packs/acf/policy.json +104 -104
- package/packs/actuaries/endpoints.json +82 -82
- package/packs/actuaries/policy.json +109 -109
- package/packs/bea/assets/download_bea.ps1 +182 -182
- package/packs/bea/docs/bea_api.md +461 -461
- package/packs/bea/docs/datasets.md +157 -157
- package/packs/bea/docs/report_patterns.md +112 -112
- package/packs/bea/policy.json +170 -170
- package/packs/bea/source.md +152 -152
- package/packs/bjs/endpoints.json +150 -0
- package/packs/bjs/policy.json +114 -0
- package/packs/bjs/source.md +98 -0
- package/packs/bls/assets/download_bls.ps1 +152 -152
- package/packs/bls/docs/analysis_patterns.md +108 -108
- package/packs/bls/docs/bls_api.md +73 -73
- package/packs/bls/docs/series_ids.md +149 -149
- package/packs/bls/policy.json +238 -238
- package/packs/bts/endpoints.json +346 -346
- package/packs/bts/policy.json +94 -94
- package/packs/cbp/endpoints.json +31 -0
- package/packs/cbp/policy.json +85 -0
- package/packs/cbp/source.md +57 -0
- package/packs/cdc/endpoints.json +197 -197
- package/packs/cdc/policy.json +83 -83
- package/packs/cdc/source.md +1 -1
- package/packs/cdc-wonder/endpoints.json +26 -0
- package/packs/cdc-wonder/policy.json +84 -0
- package/packs/cdc-wonder/source.md +53 -0
- package/packs/census/endpoints.json +99 -99
- package/packs/cfpb/endpoints.json +326 -326
- package/packs/cfpb/policy.json +119 -119
- package/packs/clinical-trials/endpoints.json +166 -166
- package/packs/clinical-trials/policy.json +84 -84
- package/packs/cms/endpoints.json +69 -69
- package/packs/cms/policy.json +96 -96
- package/packs/college-scorecard/endpoints.json +252 -252
- package/packs/college-scorecard/policy.json +106 -106
- package/packs/college-scorecard/source.md +1 -1
- package/packs/congress/endpoints.json +1701 -1701
- package/packs/congress/policy.json +117 -117
- package/packs/cpsc/endpoints.json +91 -0
- package/packs/cpsc/policy.json +91 -0
- package/packs/cpsc/source.md +76 -0
- package/packs/dhs-ohss/endpoints.json +66 -66
- package/packs/dhs-ohss/policy.json +107 -107
- package/packs/dhs-ohss/source.md +1 -1
- package/packs/doj-news/endpoints.json +59 -59
- package/packs/doj-news/policy.json +96 -96
- package/packs/doj-news/source.md +1 -1
- package/packs/dol/endpoints.json +817 -817
- package/packs/dol/policy.json +135 -135
- package/packs/eia/endpoints.json +717 -717
- package/packs/eia/policy.json +112 -112
- package/packs/epa/endpoints.json +291 -291
- package/packs/epa/policy.json +99 -99
- package/packs/epa-aqs/endpoints.json +173 -173
- package/packs/epa-aqs/policy.json +96 -96
- package/packs/fbi/endpoints.json +1841 -1841
- package/packs/fbi/policy.json +118 -118
- package/packs/fbi/source.md +3 -3
- package/packs/fda/endpoints.json +237 -237
- package/packs/fda/policy.json +121 -121
- package/packs/fdic/endpoints.json +416 -416
- package/packs/fdic/policy.json +83 -83
- package/packs/fec/endpoints.json +707 -707
- package/packs/fec/policy.json +93 -93
- package/packs/fed-board/endpoints.json +89 -89
- package/packs/fed-board/policy.json +136 -136
- package/packs/federal-register/endpoints.json +143 -143
- package/packs/federal-register/policy.json +86 -86
- package/packs/fema/endpoints.json +645 -645
- package/packs/fema/policy.json +103 -103
- package/packs/fhfa/endpoints.json +105 -105
- package/packs/fhfa/policy.json +109 -109
- package/packs/fhwa/endpoints.json +48 -0
- package/packs/fhwa/policy.json +91 -0
- package/packs/fhwa/source.md +59 -0
- package/packs/foreign-assistance/endpoints.json +166 -0
- package/packs/foreign-assistance/policy.json +80 -0
- package/packs/foreign-assistance/source.md +76 -0
- package/packs/fred/assets/download_fred.ps1 +122 -122
- package/packs/fred/docs/analysis_patterns.md +124 -124
- package/packs/fred/docs/fred_api.md +94 -94
- package/packs/fred/docs/series.md +188 -188
- package/packs/fred/policy.json +253 -253
- package/packs/fsa/endpoints.json +150 -150
- package/packs/fsa/policy.json +99 -99
- package/packs/fsa/source.md +1 -1
- package/packs/govinfo/endpoints.json +519 -519
- package/packs/gsa-calc/endpoints.json +93 -93
- package/packs/gsa-calc/policy.json +97 -97
- package/packs/hud/endpoints.json +146 -146
- package/packs/hud/policy.json +84 -84
- package/packs/hud/source.md +1 -1
- package/packs/hud-ahar/endpoints.json +92 -0
- package/packs/hud-ahar/policy.json +88 -0
- package/packs/hud-ahar/source.md +72 -0
- package/packs/ipums/docs/report_patterns.md +117 -117
- package/packs/irs-soi/endpoints.json +114 -114
- package/packs/irs-soi/policy.json +107 -107
- package/packs/medicaid/endpoints.json +412 -412
- package/packs/medicaid/policy.json +108 -108
- package/packs/naep/endpoints.json +217 -217
- package/packs/naep/policy.json +100 -100
- package/packs/naep/source.md +1 -1
- package/packs/nces/endpoints.json +101 -0
- package/packs/nces/policy.json +99 -0
- package/packs/nces/source.md +75 -0
- package/packs/nhtsa/endpoints.json +132 -132
- package/packs/nhtsa/policy.json +93 -93
- package/packs/nhtsa/source.md +1 -1
- package/packs/nih/endpoints.json +452 -452
- package/packs/nih/policy.json +86 -86
- package/packs/noaa/endpoints.json +431 -431
- package/packs/noaa/policy.json +95 -95
- package/packs/nrel/endpoints.json +327 -327
- package/packs/nrel/policy.json +96 -96
- package/packs/nsf/endpoints.json +33 -0
- package/packs/nsf/policy.json +83 -0
- package/packs/nsf/source.md +59 -0
- package/packs/nws/endpoints.json +271 -271
- package/packs/nws/policy.json +82 -82
- package/packs/nyfed/endpoints.json +80 -80
- package/packs/nyfed/policy.json +92 -92
- package/packs/omb/endpoints.json +460 -460
- package/packs/omb/policy.json +106 -106
- package/packs/onrr/endpoints.json +198 -0
- package/packs/onrr/policy.json +91 -0
- package/packs/onrr/source.md +55 -0
- package/packs/open-payments/endpoints.json +297 -297
- package/packs/open-payments/policy.json +101 -101
- package/packs/opm/assets/download_opm.ps1 +125 -125
- package/packs/opm/docs/fields.md +184 -184
- package/packs/opm/docs/opm_api.md +71 -71
- package/packs/opm/docs/report_patterns.md +83 -83
- package/packs/opm/lib/data_dictionary.csv +73 -73
- package/packs/pbgc/endpoints.json +483 -483
- package/packs/pbgc/policy.json +94 -94
- package/packs/philfed/endpoints.json +85 -85
- package/packs/philfed/policy.json +94 -94
- package/packs/port.json +65 -0
- package/packs/regulations/endpoints.json +287 -287
- package/packs/regulations/policy.json +86 -86
- package/packs/sba/endpoints.json +34 -0
- package/packs/sba/policy.json +86 -0
- package/packs/sba/source.md +60 -0
- package/packs/sec/endpoints.json +236 -236
- package/packs/sec/policy.json +86 -86
- package/packs/senate-lobbying/endpoints.json +553 -553
- package/packs/senate-lobbying/policy.json +99 -99
- package/packs/snapqc/endpoints.json +1426 -1426
- package/packs/snapqc/policy.json +92 -92
- package/packs/treasury/catalog.json +2267 -2267
- package/packs/treasury/docs/api_guide.md +245 -245
- package/packs/treasury/docs/datasets.md +56 -56
- package/packs/treasury/docs/report_patterns.md +126 -126
- package/packs/treasury/policy.json +159 -159
- package/packs/treasury/source.md +170 -165
- package/packs/treasury-tic/endpoints.json +77 -0
- package/packs/treasury-tic/policy.json +89 -0
- package/packs/treasury-tic/source.md +80 -0
- package/packs/treasury-yields/endpoints.json +226 -226
- package/packs/treasury-yields/policy.json +86 -86
- package/packs/usaspending/endpoints.json +1315 -1315
- package/packs/usaspending/policy.json +109 -109
- package/packs/uscourts/endpoints.json +22 -0
- package/packs/uscourts/policy.json +87 -0
- package/packs/uscourts/source.md +56 -0
- package/packs/usda-fna/policy.json +133 -133
- package/packs/usda-fooddata/endpoints.json +180 -180
- package/packs/usda-fooddata/policy.json +94 -94
- package/packs/usda-nass/endpoints.json +323 -323
- package/packs/usda-nass/policy.json +95 -95
- package/packs/usda-outlook/endpoints.json +86 -86
- package/packs/usda-outlook/policy.json +109 -109
- package/packs/usgs/endpoints.json +313 -313
- package/packs/usgs/policy.json +95 -95
- package/packs/usitc/endpoints.json +74 -74
- package/packs/usitc/policy.json +111 -111
- package/packs/uspto/endpoints.json +141 -141
- package/packs/uspto/policy.json +95 -95
- package/packs/uspto/source.md +1 -1
- package/packs/va/endpoints.json +414 -414
- package/packs/va/policy.json +101 -101
- package/packs/world-bank/endpoints.json +122 -122
- package/packs/world-bank/policy.json +101 -101
package/packs/bea/source.md
CHANGED
|
@@ -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
|
+
}
|