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
|
@@ -1,461 +1,461 @@
|
|
|
1
|
-
# BEA Data API reference
|
|
2
|
-
|
|
3
|
-
This server's `fetch` for bea already implements this: key lookup and redaction, throttling,
|
|
4
|
-
error handling, response quirks, tidy output, and the no-key bulk route. Read this file when you need a
|
|
5
|
-
dataset or parameter the friendly spec does not cover, or when debugging an API error.
|
|
6
|
-
|
|
7
|
-
Contents: 1. Endpoint and methods · 2. Datasets and GetData parameters (NIPA, FixedAssets, MNE,
|
|
8
|
-
GDPbyIndustry, ITA, IIP, InputOutput, IntlServTrade, IntlServSTA, Regional) · 3. Response structure and
|
|
9
|
-
special values · 4. Rate limits · 5. Error codes · 6. Registration, terms, attribution · 7. Time periods,
|
|
10
|
-
revisions, release timing · 8. Common table codes · 9. Implementation checklist
|
|
11
|
-
|
|
12
|
-
**Bulk files (no key).** Besides the API, BEA posts complete files that `fetch` reads when no key works:
|
|
13
|
-
- NIPA: `https://apps.bea.gov/national/Release/TXT/` → `NipaDataA.txt`, `NipaDataQ.txt`, `NipaDataM.txt`
|
|
14
|
-
(`%SeriesCode,Period,Value`), `SeriesRegister.txt` (`SeriesCode,SeriesLabel,MetricName,CalculationType,
|
|
15
|
-
DefaultScale,TableId:LineNo|...,SeriesCodeParents`; DefaultScale -6 = millions) and `TablesRegister.txt`.
|
|
16
|
-
Every published NIPA and NIUnderlyingDetail table can be rebuilt from them (TableId:LineNo → series).
|
|
17
|
-
- Regional: `https://apps.bea.gov/regional/zip/<NAME>.zip`. State tables come in family zips (`SAGDP.zip`,
|
|
18
|
-
`SQGDP.zip`, `SAINC.zip`, `SQINC.zip`, `SAPCE.zip`, `SARPP.zip`, `SAOR.zip`); county tables one per zip
|
|
19
|
-
(`CAINC1.zip`, `CAINC4.zip`, `CAGDP2.zip`, `CAGDP9.zip`, ...); MSA price parities in `MARPP.zip`. Inside:
|
|
20
|
-
`<TABLE>__ALL_AREAS_<first>_<last>.csv` (wide: GeoFIPS, GeoName, Region, TableName, LineCode,
|
|
21
|
-
IndustryClassification, Description, Unit, then one column per year or `2026:Q1` quarter; footer lines
|
|
22
|
-
give "Last updated: ..."), plus `definition.xml` (line definitions) and `Footnotes.html`. A missing zip
|
|
23
|
-
returns HTTP 200 with an HTML page, so check for the `PK` zip signature. Zips for API-only tables
|
|
24
|
-
(metro-area GDP and income, MSA personal income) do not exist.
|
|
25
|
-
- GDP by industry: `https://apps.bea.gov/industry/Release/XLS/GDPxInd/` → `ValueAdded.xlsx` (sheets
|
|
26
|
-
`TVA101-A`, `TVA101-Q` ... `TVA113-A`), `GrossOutput.xlsx` (`TGO1xx`), `IntermediateInputs.xlsx` (`TII1xx`). Each
|
|
27
|
-
sheet: title, `[unit]`, period range, "Data published <date>", then a header row starting `Line` and one row per
|
|
28
|
-
industry; footnotes below. A `Contents` sheet lists the codes. `fetch` reads them itself (no key, no other software).
|
|
29
|
-
- Data are the same, latest vintage as the API. Bulk files are large (NIPA quarterly 35 MB; some county
|
|
30
|
-
zips 45 MB) but need no key and count against no rate limit.
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
Compiled 2026-10-19. Main source: *BEA API for Data Retrieval User Guide* (PDF, main body dated April 20, 2026, 69 pages including appendices). Other sources are the live swagger.json, the Terms of Service PDF, BEA's own `us-bea/beaapi` Python package (v0.2.0, Feb 2026), test calls made with an invalid key, and the BEA pages listed at the end.
|
|
34
|
-
Tags: **[guide]** user guide PDF; **[swagger]** apps.bea.gov/api/swagger/swagger.json; **[live]** observed today with an invalid key; **[beaapi]** source code of BEA's official Python client; **[2024-htm]** Wayback copy (2024-03-16) of the older HTML guide. **UNVERIFIED** means no primary source was checked or data calls were not possible.
|
|
35
|
-
|
|
36
|
-
---------------------------------------------------------------------------------------------------
|
|
37
|
-
## 1. Endpoint, request format, methods
|
|
38
|
-
|
|
39
|
-
- **Single endpoint:** `https://apps.bea.gov/api/data` (also accepts `.../api/data/`) [guide]. The guide says "All API access is through this URI; no other paths are used."
|
|
40
|
-
- **Requests:** HTTP **GET** with query-string parameters only. Every request needs `UserID` and `method`. GetData and the parameter metadata methods also need `DatasetName`.
|
|
41
|
-
- **Case:** parameter names are case-insensitive [live]: `userid=…&METHOD=getdatasetlist&resultformat=xml` worked, and the server echoes names and values in UPPERCASE in `Request.RequestParam`. Method names and dataset names are case-insensitive too (the guide's own examples use `GETDATASETLIST`, `getparameterlist`, `INTLSERVTRADE`, `underlyingGDPbyIndustry`). Case-insensitivity of other parameter *values*, such as table names, is UNVERIFIED (likely), so pass codes exactly as returned by GetParameterValues.
|
|
42
|
-
- **Multiple values:** use one comma-separated string, e.g. `Year=2022,2023,2024` or `Frequency=A,Q,M` [guide]. URL-encode it, although commas work raw.
|
|
43
|
-
- **`ResultFormat`:** `JSON` (the default, also used when the value is invalid) or `XML` [guide]. Content-Type is `application/json` or `application/xml` [live].
|
|
44
|
-
- **Other features:** an optional `jsonp=<callbackName>` wraps the response for legacy browsers. CORS headers are on all responses [guide].
|
|
45
|
-
- **Encoding:** beaapi decodes responses as `iso-8859-1` because "utf-8 returns decode errors" [beaapi].
|
|
46
|
-
- **Methods** [guide] (the guide has a separate section for each):
|
|
47
|
-
|
|
48
|
-
| method | required params (besides UserID) | returns `Results.` |
|
|
49
|
-
|---|---|---|
|
|
50
|
-
| `GetDataSetList` | – | `Dataset[]` {DatasetName, DatasetDescription} |
|
|
51
|
-
| `GetParameterList` | `DatasetName` | `Parameter[]` {ParameterName, ParameterDataType (string/integer), ParameterDescription, ParameterIsRequiredFlag 0/1, ParameterDefaultValue, MultipleAcceptedFlag 0/1, AllValue} |
|
|
52
|
-
| `GetParameterValues` | `DatasetName`, `ParameterName` | `ParamValue[]`, usually {Key, Desc}. Some datasets use other attribute names, e.g. FixedAssets in 2024-htm: `TableID`/`Description`. Read the keys generically. |
|
|
53
|
-
| `GetParameterValuesFiltered` | `DatasetName`, `TargetParameter`, plus filter params | `ParamValue[]` {Key, Desc}. **Not supported by every dataset**: NIPA returns error 34. Supported by Regional, and ITA in the beaapi README example (`targetparameter='Indicator', AreaOrCountry='China', Frequency='A', Year='2011'`). Support in other datasets is UNVERIFIED. |
|
|
54
|
-
| `GetData` | `DatasetName` + dataset-specific params | `Dimensions`, `Data`, `Notes` (+ dataset extras); see §3 |
|
|
55
|
-
|
|
56
|
-
- The guide says that for NIPA/NIUnderlyingDetail/FixedAssets, "passing a TableName value" to GetParameterValues tells you the valid frequencies and years for that table. The exact request form is UNVERIFIED.
|
|
57
|
-
- **Key format:** a 36-character GUID, e.g. `11111111-2222-3333-4444-555555555555` in the guide's example [guide]. beaapi strips spaces and rejects any key whose length is not 36 [beaapi].
|
|
58
|
-
|
|
59
|
-
---------------------------------------------------------------------------------------------------
|
|
60
|
-
## 2. Datasets and GetData parameters
|
|
61
|
-
|
|
62
|
-
**Current dataset list** (from the GetDataSetList example in the April 2026 guide; the same 13 appear in swagger and the beaapi README):
|
|
63
|
-
NIPA, NIUnderlyingDetail, MNE, FixedAssets, ITA, IIP, InputOutput, IntlServTrade, IntlServSTA, GDPbyIndustry, Regional, UnderlyingGDPbyIndustry, APIDatasetMetaData.
|
|
64
|
-
|
|
65
|
-
**Retired (calls "will no longer function")** [guide App. A/I/J]:
|
|
66
|
-
- `RegionalData` (2019)
|
|
67
|
-
- `RegionalIncome` and `RegionalProduct` (Dec 2019). Use `Regional` instead. Crosswalk: apps.bea.gov/regional/pdf/RegionalApi.pdf, e.g. RegionalIncome SA1 → SAINC1, CA4 → CAINC4; RegionalProduct GDP_SAN → SAGDP2N, RGDP_SAN → SAGDP9N, RGDP_SQN → SQGDP9.
|
|
68
|
-
|
|
69
|
-
**Retired parameters:**
|
|
70
|
-
- NIPA/NIUnderlyingDetail `TableID` was replaced by `TableName` (Feb 2018). The guide has crosswalks, e.g. TableID 1 = T10101.
|
|
71
|
-
- FixedAssets `TableID` → `TableName` (Oct 2018).
|
|
72
|
-
- NIPA `ShowMillions` was discontinued in Oct 2017 [2024-htm], although swagger still lists it. Use UNIT_MULT instead.
|
|
73
|
-
|
|
74
|
-
**NIUnderlyingDetail is still active.** It is in the 2026 guide, swagger, signup page and TablesRegister.txt (U-prefixed tables). Some underlying tables were dropped: Section 0 inventories/sales tables 4AU*, 4BU*, 6U, 7U (2024-07-01), and 9.2U and 9.5U (2025-09-25) [discontinued-stats page]. BEA caution: underlying detail is lower quality than the published aggregates [guide App. C/L].
|
|
75
|
-
|
|
76
|
-
The tables below use these columns: Req = required; Multi = multiple values accepted; All = "all" keyword. Parameter details come from the guide appendices.
|
|
77
|
-
|
|
78
|
-
### NIPA (App. B) and NIUnderlyingDetail (App. C): same parameters
|
|
79
|
-
| param | Req | Multi | All | notes |
|
|
80
|
-
|---|---|---|---|---|
|
|
81
|
-
| TableName | Y | N | – | e.g. `T10101`, `U20305`. One table per request. |
|
|
82
|
-
| Frequency | Y | Y | – | `A`, `Q`, `M`. Frequencies a table lacks are skipped; if none match, an error is returned. |
|
|
83
|
-
| Year | Y | Y | `X` or `ALL` | Q/M requests return all available periods within each requested year. |
|
|
84
|
-
|
|
85
|
-
Examples:
|
|
86
|
-
- `?UserID=KEY&method=GetData&DataSetName=NIPA&TableName=T10101&Frequency=A,Q&Year=ALL`
|
|
87
|
-
- `?UserID=KEY&method=GetData&DataSetName=NIPA&TableName=T20600&Frequency=M&Year=2015,2016`
|
|
88
|
-
- `?UserID=KEY&method=GetData&DataSetName=NIUnderlyingDetail&TableName=U70205S&Frequency=M&Year=2015,2016`
|
|
89
|
-
|
|
90
|
-
### FixedAssets (App. D)
|
|
91
|
-
| param | Req | Multi | All |
|
|
92
|
-
|---|---|---|---|
|
|
93
|
-
| TableName (e.g. `FAAt201`) | Y | N | – |
|
|
94
|
-
| Year | Y | Y | `X` or `ALL` |
|
|
95
|
-
|
|
96
|
-
Annual only. Updated once a year, typically late August to early October.
|
|
97
|
-
Example: `?UserID=KEY&method=GetData&DataSetName=FixedAssets&TableName=FAAt201&Year=ALL`
|
|
98
|
-
Caveat: swagger names the parameter `tableID` while the guide uses `TableName`. Prefer `TableName`.
|
|
99
|
-
|
|
100
|
-
### MNE (App. E): two request types
|
|
101
|
-
- **Direct Investment (DI):**
|
|
102
|
-
- Required: `DirectionOfInvestment` (`Outward` or `Inward`), `Classification` (single value, e.g. `Country`, `CountryByIndustry`), `Year` (multiple values or `all`).
|
|
103
|
-
- Optional: `SeriesID` (multiple; default all, `0` = all), `Country` (3-digit codes; `000` = all-countries total, `all` = every country and region), `Industry` (4-digit NAICS-like codes; `0000` = all-industries total, `all` = every industry), `GetFootnotes` (`Yes` or `No`, default No).
|
|
104
|
-
- **Activities of MNEs (AMNE):**
|
|
105
|
-
- Required: `DirectionOfInvestment` (`Outward`, `Inward`, `State` or `Parent`), `OwnershipLevel` (`0` = majority-owned affiliates, `1` = all affiliates; must be 1 when Direction=Parent), `NonBankAffiliatesOnly` (`0` = bank and nonbank affiliates, which suits outward 2009+ and inward 2007+; `1` = nonbank only, for earlier years), `Classification`, `Year`.
|
|
106
|
-
- Optional: `SeriesID`, `Country`, `Industry`, `State` (2-digit FIPS; `00` = US total, `70` = other US areas, `75` = foreign, `all`), `GetFootnotes`.
|
|
107
|
-
- With `State`, only employment (and, for limited years, gross property, plant and equipment) is available.
|
|
108
|
-
- Swagger also lists the undocumented parameters `investment` and `parentInvestment` (meaning UNVERIFIED).
|
|
109
|
-
|
|
110
|
-
Examples:
|
|
111
|
-
- `?UserID=KEY&method=GetData&DataSetName=MNE&SeriesID=30&Year=2011,2012&Country=650,699&DirectionOfInvestment=Outward&Classification=Country`
|
|
112
|
-
- `?UserID=KEY&method=GetData&DataSetName=MNE&Year=2011&Country=all&Industry=0000&DirectionOfInvestment=Inward&Classification=Country&SeriesID=8&OwnershipLevel=0&NonbankAffiliatesOnly=0&GetFootnotes=Yes`
|
|
113
|
-
|
|
114
|
-
### GDPbyIndustry (App. F; the PDF page footers mislabel this appendix as "Appendix E - MNE")
|
|
115
|
-
| param | Req | Multi | All |
|
|
116
|
-
|---|---|---|---|
|
|
117
|
-
| TableID (integer) | Y | Y | `ALL` |
|
|
118
|
-
| Frequency | Y | Y | `A` and/or `Q` |
|
|
119
|
-
| Year | Y | Y | `ALL` |
|
|
120
|
-
| Industry | Y | Y | `ALL` |
|
|
121
|
-
|
|
122
|
-
- Annual data start in 1997 (1998 for percent-change and contributions tables). Quarterly data start in 2005.
|
|
123
|
-
- In GetParameterValues, a description marked "(A)" means annual and "(Q)" means also quarterly.
|
|
124
|
-
- Requesting Q for a table that is annual-only gives error 204.
|
|
125
|
-
|
|
126
|
-
Examples:
|
|
127
|
-
- `?UserID=KEY&method=GetData&DataSetName=GDPbyIndustry&TableID=1&Frequency=A&Year=2011,2012&Industry=ALL`
|
|
128
|
-
- `?UserID=KEY&method=GetData&DataSetName=GDPbyIndustry&TableID=ALL&Frequency=A,Q&Year=2010&Industry=11`
|
|
129
|
-
|
|
130
|
-
### UnderlyingGDPbyIndustry (App. L)
|
|
131
|
-
- Same 4 parameters as GDPbyIndustry, all required, but **Frequency=A only** (Q gives error 206, "Invalid frequency: Q").
|
|
132
|
-
- Data run from 1997 to the present.
|
|
133
|
-
|
|
134
|
-
Example: `?UserID=KEY&method=GetData&DataSetName=UnderlyingGDPbyIndustry&TableID=210&Frequency=A&Year=2012,2013&Industry=ALL`
|
|
135
|
-
|
|
136
|
-
### ITA, International Transactions (App. G). All parameters optional and multi-valued.
|
|
137
|
-
- `Indicator` (default All; e.g. `BalGds`, `PfInvAssets`)
|
|
138
|
-
- `AreaOrCountry` (default `AllCountries` = total; `All` = every area and country; e.g. `China`)
|
|
139
|
-
- `Frequency` (`A`, `QSA`, `QNSA`)
|
|
140
|
-
- `Year` (default All)
|
|
141
|
-
|
|
142
|
-
**Rule:** you can request multiple Indicators only with exactly one AreaOrCountry that is not All or AllCountries. Likewise, a list of countries (or AllCountries) works only with exactly one Indicator.
|
|
143
|
-
|
|
144
|
-
Examples:
|
|
145
|
-
- `?UserID=KEY&method=GetData&DataSetName=ITA&Indicator=BalGds&AreaOrCountry=China&Frequency=A&Year=2011,2012`
|
|
146
|
-
- `?UserID=KEY&method=GetData&DataSetName=ITA&Indicator=PfInvAssets&AreaOrCountry=AllCountries&Frequency=QNSA&Year=2013`
|
|
147
|
-
|
|
148
|
-
### IIP, International Investment Position (App. H). All optional and multi-valued.
|
|
149
|
-
- `TypeOfInvestment` (e.g. `FinAssetsExclFinDeriv`, `FinLiabsFoa`)
|
|
150
|
-
- `Component` (`Pos` = position; changes such as `ChgPosTrans`, `ChgPosPrice`)
|
|
151
|
-
- `Frequency` (`A`, `QNSA`)
|
|
152
|
-
- `Year`
|
|
153
|
-
|
|
154
|
-
**Rule:** more than one TypeOfInvestment requires exactly one Year that is not ALL, and more than one Year requires exactly one TypeOfInvestment.
|
|
155
|
-
|
|
156
|
-
Examples:
|
|
157
|
-
- `?UserID=KEY&method=GetData&DataSetName=IIP&TypeOfInvestment=FinAssetsExclFinDeriv&Component=ChgPosPrice&Frequency=A&Year=ALL`
|
|
158
|
-
- `?UserID=KEY&method=GetData&DataSetName=IIP&TypeOfInvestment=FinLiabsFoa&Component=Pos&Frequency=QNSA&Year=2013`
|
|
159
|
-
|
|
160
|
-
### InputOutput (App. K)
|
|
161
|
-
| param | Req | Multi | All |
|
|
162
|
-
|---|---|---|---|
|
|
163
|
-
| TableID (integer) | Y | Y | none |
|
|
164
|
-
| Year | Y | Y | `ALL` |
|
|
165
|
-
|
|
166
|
-
Some tables exist only for benchmark years (e.g. Use tables in purchasers' prices: 2007).
|
|
167
|
-
Examples:
|
|
168
|
-
- `?UserID=KEY&method=GetData&DataSetName=InputOutput&TableID=56&Year=2010,2011,2012,2013`
|
|
169
|
-
- `?UserID=KEY&method=GetData&DataSetName=InputOutput&TableID=56,57&Year=2007`
|
|
170
|
-
|
|
171
|
-
The guide warns that IO parameter values change, so always refresh them with GetParameterValues.
|
|
172
|
-
|
|
173
|
-
### IntlServTrade (App. M). Annual data, updated each July. All optional and multi-valued.
|
|
174
|
-
- `TypeOfService` (default All; e.g. `AllServiceTypes`, `Telecom`)
|
|
175
|
-
- `TradeDirection` (`Exports`, `Imports`, `Balance`, `SupplementalIns`)
|
|
176
|
-
- `Affiliation` (`AllAffiliations`, `Unaffiliated`, `Affiliated`, `UsParents`, `UsAffiliates`)
|
|
177
|
-
- `AreaOrCountry` (default `AllCountries`; `All` = every area and country)
|
|
178
|
-
- `Year`
|
|
179
|
-
|
|
180
|
-
**Rule:** multiple TypeOfService values require one specific AreaOrCountry, and a list of countries requires one specific TypeOfService.
|
|
181
|
-
|
|
182
|
-
Examples:
|
|
183
|
-
- `?UserID=KEY&method=GetData&DataSetName=IntlServTrade&TypeOfService=AllServiceTypes&TradeDirection=Imports&Affiliation=AllAffiliations&AreaOrCountry=Germany&Year=2014,2015`
|
|
184
|
-
- `?UserID=KEY&method=GetData&DataSetName=IntlServTrade&TypeOfService=Telecom&TradeDirection=Exports&Affiliation=UsParents&AreaOrCountry=AllCountries&Year=All`
|
|
185
|
-
|
|
186
|
-
### IntlServSTA (App. O, Oct 2023). Annual data, updated each October. All optional and multi-valued.
|
|
187
|
-
- `Channel` (`Mofas`, `Mousas`, `AllChannels`, `Trade`, `UsExportsByMousas`, `UsImportsFromMofas`)
|
|
188
|
-
- `Destination`:
|
|
189
|
-
- MOFAs: `AllForeign`, `ForeignAffs`, `ForeignUnaff`, `HostCtry`, `HostCtryAffs`, `HostCtryUnaff`, `ForeignOther`, `ForeignOtherAffs`, `ForeignOtherUnaff`
|
|
190
|
-
- MOUSAs: `AllUs`
|
|
191
|
-
- `Industry` (default `AllInd` = total; `All` = every industry; e.g. `RetailTrade`, `Mining`)
|
|
192
|
-
- `AreaOrCountry` (default `AllCountries`)
|
|
193
|
-
- `Year`
|
|
194
|
-
|
|
195
|
-
Examples:
|
|
196
|
-
- `?UserID=KEY&method=GetData&DataSetName=IntlServSTA&Channel=Mofas&Destination=AllForeign&Industry=RetailTrade&AreaOrCountry=India&Year=2015,2016`
|
|
197
|
-
- `?UserID=KEY&method=GetData&DataSetName=IntlServSTA&Channel=Mousas&Destination=AllUs&Industry=Mining&AreaOrCountry=Europe`
|
|
198
|
-
|
|
199
|
-
### Regional (App. N, dated April 24, 2026)
|
|
200
|
-
| param | Req | Multi | special values |
|
|
201
|
-
|---|---|---|---|
|
|
202
|
-
| TableName | Y | N | one table per request |
|
|
203
|
-
| LineCode | Y | N | integer, or `ALL`. With `ALL`, **only one GeoFips** is allowed. |
|
|
204
|
-
| GeoFips | Y | Y (unless LineCode=ALL) | `STATE`, `COUNTY`, `MSA`, `MIC`, `PORT`, `DIV`, `CSA`, `TERR`, a state postal abbreviation (all counties in that state, e.g. `NY`), or a list of 5-digit codes |
|
|
205
|
-
| Year | N | Y | default `LAST5`; also `LAST10`, `ALL` |
|
|
206
|
-
|
|
207
|
-
- **GeoFips codes:** `00000` = US; states are `SS000` (e.g. `01000` Alabama); counties are `SSCCC`; BEA regions are `91000`–`98000` (e.g. `97000` Rocky Mountain, `98000` Far West); `72000` = Puerto Rico (PRGDP* tables). Component counties of each MSA: apps.bea.gov/regional/geography.htm.
|
|
208
|
-
- **GetParameterValuesFiltered (Regional)** accepts comma-separated lists for TableName and LineCode, unlike GetData:
|
|
209
|
-
- `TargetParameter=LineCode&TableName=SAINC4`: line codes for a table
|
|
210
|
-
- `TargetParameter=Year&TableName=CAINC5N&GeoFips=01001`: years available
|
|
211
|
-
- `TargetParameter=GeoFips&TableName=CAINC4&LineCode=10`: geographies
|
|
212
|
-
- `TargetParameter=TableName&GeoFips=00000&Year=2024`: tables
|
|
213
|
-
- **Feb 2026 change:** BEA **stopped producing GDP and personal income for MSAs, MICs, DIVs, CSAs and metro/nonmetro PORTs** in the county tables (CAINC1/4/5N/5S/6N/6S/30, CAGDP1/2/8/9/11). It announced this in 2025 and in the 2026-02-05 county release. MARPI/PARPI (real personal income) for MSAs and portions were dropped on 2026-02-19 [discontinued-stats page; us-bea/bea_geo_aggregator README; FAQ 1481].
|
|
214
|
-
- Expect `MSA`/`PORT` GeoFips to fail or return only historical data for these tables (UNVERIFIED which).
|
|
215
|
-
- BEA's `bea_geo_aggregator` repo rebuilds MSA estimates from county data. The archive apps.bea.gov/histdata/ has the old MSA vintages.
|
|
216
|
-
- Status of MARPP and PARPP (regional price parities) by MSA is UNVERIFIED. They are still listed in App. N.
|
|
217
|
-
- **Earlier cuts** (2024): SAEMP25, SAEMP27, SAINC45, CAEMP25, CAINC35, CAINC45 discontinued; specific lines dropped, e.g. CAINC4 7010/7020/7040, CAINC30 240–310, SAINC30 270/280/310.
|
|
218
|
-
|
|
219
|
-
Examples:
|
|
220
|
-
- `?UserID=KEY&method=GetData&datasetname=Regional&TableName=CAINC1&LineCode=1&GeoFips=COUNTY&Year=2012,2013`
|
|
221
|
-
- `?UserID=KEY&method=GetData&datasetname=Regional&TableName=SAINC1&LineCode=3&GeoFips=STATE&Year=2013`
|
|
222
|
-
- `?UserID=KEY&method=GetData&datasetname=Regional&TableName=SAGDP9N&LineCode=2&GeoFips=STATE&Year=ALL` (the guide calls this "Real GDP for all states")
|
|
223
|
-
|
|
224
|
-
### APIDatasetMetaData (still listed; not documented in the guide)
|
|
225
|
-
- Swagger shows one required parameter, `dataset`. beaapi calls `method=GetData&datasetname=APIDatasetMetaData&dataset=NIPA,NIUnderlyingDetail,FixedAssets`.
|
|
226
|
-
- **The response is not wrapped in `Results`.** It looks like `BEAAPI.Datasets[]`, each with {Datasetname, MetaDataUpdated, `APITable[]`}. Each APITable has {TableId, TableName (the title), ReleaseDate, NextReleaseDate, `Line[]`}, and each Line has {SeriesCode, RowNumber, LineDescription, LineNumber, ParentLineNumber, Tier, Path}.
|
|
227
|
-
- ReleaseDate looks like `"Feb 28 2019 8:30AM"` [beaapi README]. Only NIPA, NIUnderlyingDetail and FixedAssets are known to be supported [beaapi].
|
|
228
|
-
- Its structure comes from beaapi source only, so treat it as UNVERIFIED live.
|
|
229
|
-
|
|
230
|
-
---------------------------------------------------------------------------------------------------
|
|
231
|
-
## 3. GetData response structure
|
|
232
|
-
|
|
233
|
-
Common shape [guide]: `{"BEAAPI":{"Request":{"RequestParam":[{ParameterName,ParameterValue}…]},"Results":{…}}}`. Results usually contains:
|
|
234
|
-
- **`Dimensions[]`**: {Ordinal, Name, DataType ("string" or "numeric"), IsValue ("1" for the value column)}.
|
|
235
|
-
- Regional sometimes omits `Ordinal` [beaapi].
|
|
236
|
-
- Fields within a Data row are **not in a guaranteed order**, so always read them by name.
|
|
237
|
-
- **`Data[]`**: one object per observation; **every field is a string**.
|
|
238
|
-
- **`Notes[]`**: {NoteRef, NoteText}.
|
|
239
|
-
- A `NoteRef` on a data row (or on Results) points to a note. It can hold several comma-separated refs, or extra symbols (e.g. `"2 *"` matches notes "2" and "*").
|
|
240
|
-
- Regional also returns notes with `NoteRef` `"Note."` (units) and `" "` (e.g. "Last updated: February 5, 2026-- new statistics for 2024; revised statistics for 2020-2023.").
|
|
241
|
-
- For NIPA, every row has at least one NoteRef pointing to the table title. In practice it is the TableName, e.g. `T20305` [beaapi README].
|
|
242
|
-
- **Extras:**
|
|
243
|
-
- Regional: `Statistic`, `UnitOfMeasure`, `PublicTable`, `UTCProductionTime` (e.g. `2026-03-25T19:25:39.113`), `NoteRef` [guide].
|
|
244
|
-
- NIPA: `Statistic` ("NIPA Table"), `UTCProductionTime` [beaapi].
|
|
245
|
-
- **Quirks** [beaapi]:
|
|
246
|
-
- `Results` can be a **1-element list** instead of an object (unwrap it).
|
|
247
|
-
- **IIP puts `Data` at `BEAAPI.Data`**, not inside Results.
|
|
248
|
-
- `Data` (and `Notes`) can be a single **object** instead of a list when there is only one observation.
|
|
249
|
-
- `Error` can appear at `BEAAPI.Error` as well as `Results.Error`, and can be a list.
|
|
250
|
-
|
|
251
|
-
**Fields per dataset** ([guide] where marked; otherwise [beaapi]):
|
|
252
|
-
- **NIPA / NIUnderlyingDetail / FixedAssets** [guide]: TableName, SeriesCode, LineNumber, LineDescription, TimePeriod, METRIC_NAME (the guide writes "Metric_Name", but live output uses `METRIC_NAME`), CL_UNIT, UNIT_MULT, DataValue, NoteRef.
|
|
253
|
-
- Sample row: `{"TableName":"T20305","SeriesCode":"DPCERC","LineNumber":"1","LineDescription":"Personal consumption expenditures (PCE)","TimePeriod":"2015Q1","METRIC_NAME":"Current Dollars","CL_UNIT":"Level","UNIT_MULT":"6","DataValue":"12,119,763","NoteRef":"T20305"}`. The commas are inferred from the guide ("formatted with commas"); beaapi removes them.
|
|
254
|
-
- SeriesCode values may repeat across LineNumbers. Key on (LineNumber, TimePeriod).
|
|
255
|
-
- **Regional** [guide]: Code (`TABLE-LINE`, e.g. `CAINC1-3`), GeoFips, GeoName (may end in ` *` when there is a footnote), TimePeriod, CL_UNIT (e.g. "Dollars"), UNIT_MULT, DataValue, NoteRef. beaapi also expects an optional `Description`.
|
|
256
|
-
- **ITA / IIP** [guide]: Indicator or TypeOfInvestment, AreaOrCountry or Component, Frequency, Year, TimeSeriesId, TimeSeriesDescription, TimePeriod, CL_UNIT (e.g. USD), UNIT_MULT, DataValue (**may be blank**), NoteRef (may be blank).
|
|
257
|
-
- **IntlServTrade** [guide]: TypeOfService, TradeDirection, Affiliation, AreaOrCountry, Year, TimeSeriesId, TimeSeriesDescription, TimePeriod, CL_UNIT, UNIT_MULT, DataValue (may be blank), NoteRef.
|
|
258
|
-
- **IntlServSTA** [guide]: Channel, Destination, Industry, AreaOrCountry, Year, TimeSeriesId, TimeSeriesDescription, TimePeriod, CL_UNIT, UNIT_MULT, DataValue, NoteRef.
|
|
259
|
-
- **GDPbyIndustry** [beaapi]: TableID, Frequency, Year, Quarter (equals Year when Frequency=A, otherwise I–IV), Industry, `IndustrYDescription` (sic, odd capitalisation), DataValue, NoteRef.
|
|
260
|
-
- **UnderlyingGDPbyIndustry** [beaapi]: TableID, Frequency, Year, Industry, IndustrYDescription, DataValue, NoteRef.
|
|
261
|
-
- **InputOutput** [beaapi]: TableID, Year, RowCode, RowDescr, RowType, ColCode, ColDescr, ColType, DataValue, NoteRef.
|
|
262
|
-
- **MNE** [beaapi]: SeriesID, SeriesName, Row, RowCode, Column, ColumnCode, ColumnParent, ColumnParentCode, ColumnGParent, ColumnGParentCode, TableScale, Year, TableRowDisplayOrder, TableColumnDisplayOrder, DataValue, DataValueUnformatted. `RowCode` can be `' '` on several rows, so key with the display-order fields too.
|
|
263
|
-
- **GDPbyIndustry / UnderlyingGDPbyIndustry / InputOutput:** "Blanks will not be returned for missing data" [guide].
|
|
264
|
-
|
|
265
|
-
**Value handling:**
|
|
266
|
-
- DataValue is a string that may contain thousands separators, e.g. "1,337". Strip commas before parsing.
|
|
267
|
-
- Real value = DataValue × 10^UNIT_MULT (6 = millions, 9 = billions) [guide].
|
|
268
|
-
- CL_UNIT tells you the unit, e.g. "USD", "PC" (percent), "Level", "Dollars" [guide].
|
|
269
|
-
- Non-numeric DataValues that beaapi handles:
|
|
270
|
-
- `(D)` = suppressed to avoid disclosing data of individual companies or establishments; also used for MNE, Regional and Fixed Assets cells. BEA FAQ: "A (D) indicates a data suppression".
|
|
271
|
-
- `(NM)` = not meaningful.
|
|
272
|
-
- `(NA)` = not available.
|
|
273
|
-
- `(*)` = MNE: nonzero value that rounds to zero (beaapi maps it to 0).
|
|
274
|
-
- `n.s.` = MNE: not shown.
|
|
275
|
-
- `n.a.` = not available.
|
|
276
|
-
- beaapi only blanks `(D)` and `(NM)` when NoteRef has the same code.
|
|
277
|
-
- Regional table symbols `(L)` (less than $50,000 or fewer than 10 jobs, shown as 0), `(S)`, `(X)`, `(T)`, `(NA)` are **UNVERIFIED**: no BEA page found that defines them.
|
|
278
|
-
- Robust approach: if `DataValue.replace(',','')` does not parse as a float, store NaN and keep the raw string in a `flag` column.
|
|
279
|
-
|
|
280
|
-
---------------------------------------------------------------------------------------------------
|
|
281
|
-
## 4. Rate limits and throttling
|
|
282
|
-
|
|
283
|
-
**Current guide (2026)**, per user account:
|
|
284
|
-
- **100 requests/minute**, and/or
|
|
285
|
-
- **100 MB of data retrieved/minute**, and/or
|
|
286
|
-
- **30 errors/minute**.
|
|
287
|
-
|
|
288
|
-
If any limit was exceeded in the previous minute, every further request errors during the timeout. The guide says the timeout is "currently one minute – but may change dynamically to accommodate API activity levels". BEA says it adjusts these limits periodically.
|
|
289
|
-
|
|
290
|
-
**Throttled response:**
|
|
291
|
-
- **HTTP 429 Too Many Requests**, with a `Retry-After` header in seconds (example `retry-after: 59`). The value counts down on each further request until the timeout ends.
|
|
292
|
-
- JSON body error, e.g. `APIErrorCode "7"` "Request Denied - exceeded Requests per minute quota." Matching messages for the data-volume and error quotas presumably exist; their wording and codes are UNVERIFIED.
|
|
293
|
-
|
|
294
|
-
**Contradiction: lockout length.** BEA's own code says the block lasts **1 hour**:
|
|
295
|
-
- beaapi: `BACKOFF_SECS = 60*60`, and the message "your requests will be blocked for the next hour".
|
|
296
|
-
- bea_geo_aggregator README (2026): "temporarily blocked from the API for an hour".
|
|
297
|
-
- Plan for up to 1 hour, and obey `Retry-After` when it is present.
|
|
298
|
-
|
|
299
|
-
**Older limits** [2024-htm, archived Mar 2024]: 1000 calls/min, 30 errors/min, 50 MB/min. Current limits are **lower on requests (100) and higher on data volume (100 MB)**.
|
|
300
|
-
|
|
301
|
-
**No documented maximum on rows or response size.** Signs of an oversized request:
|
|
302
|
-
- An empty 200 body. beaapi reads this as "Likely the query timed out. Try again with narrower parameters."
|
|
303
|
-
- An HTML error page ("An error occurred while executing the application").
|
|
304
|
-
|
|
305
|
-
**Guidance** [guide]:
|
|
306
|
-
1. Fetch only after releases; check the schedule.
|
|
307
|
-
2. Count requests and bytes and pause before reaching the limits. beaapi counts 100 MB as 100·1000·1024 bytes and leaves headroom of 1 request, 1 error and the largest recent response.
|
|
308
|
-
3. On a 429, pause for the `Retry-After` period (the guide says 60 s); retrying during the timeout just extends it.
|
|
309
|
-
4. Use a single thread and run requests one after another. beaapi warns that throttling cannot coordinate across processes.
|
|
310
|
-
5. Use `ALL`/`X` on **at most one parameter**.
|
|
311
|
-
|
|
312
|
-
**Ways to split requests:** by year range (e.g. 10-year chunks for Q/M NIPA data), by one table per call (already required for NIPA/Regional), by GeoFips list instead of `COUNTY`+`ALL`, and one LineCode per call for Regional.
|
|
313
|
-
Errors count toward the 30/min limit, so validate parameters with metadata calls first and never retry on API error codes.
|
|
314
|
-
|
|
315
|
-
---------------------------------------------------------------------------------------------------
|
|
316
|
-
## 5. Error codes
|
|
317
|
-
|
|
318
|
-
Errors normally arrive as **HTTP 200** with `Results.Error {APIErrorCode, APIErrorDescription}`. There may also be `ErrorDetail {Description}` children; in JSON, collect every key other than code and description. Throttling is the exception: HTTP 429.
|
|
319
|
-
|
|
320
|
-
**The guide has no master table.** Every code BEA documents or that was observed:
|
|
321
|
-
|
|
322
|
-
| code | description (verbatim) | source |
|
|
323
|
-
|---|---|---|
|
|
324
|
-
| 1 | Invalid Request - Invalid API UserId. | guide; live (GUID-shaped bad key on GetData or a bad method) |
|
|
325
|
-
| 3 | The BEA API UserID provided in the request does not exist. | 2024-htm |
|
|
326
|
-
| 4 | This UserId is not active. Please activate it and try again. | live (key `X`; and an all-zero GUID on GETDATASETLIST). Also what an unactivated key would return (inferred). |
|
|
327
|
-
| 7 | Request Denied - exceeded Requests per minute quota. | guide (sent with HTTP 429) |
|
|
328
|
-
| 34 | The GetParameterValuesFiltered method has not been implemented on this dataset (coming soon). | guide (NIPA) |
|
|
329
|
-
| 40 | The dataset requested requires parameters that were missing from the request | guide. Regional also uses 40 for invalid values: detail such as "TableName entered is invalid" or "TableName entered is incompatible with the entered GeoFips, LineCode and Year", plus suggested values. |
|
|
330
|
-
| 201 | Error retrieving Fixed Assets data. (detail e.g. "Invalid table IDs were requested.", "The requested parameters did not return data.") | 2024-htm |
|
|
331
|
-
| 203 | No parameter values match the filtered list requested (Regional GetParameterValuesFiltered; detail e.g. "LineCode entered is invalid", "Values of GeoFips and LineCode are incompatible") | guide |
|
|
332
|
-
| 204 | Error retrieving GDP by Industry data. (detail e.g. "This TableID is not published quarterly: 25", "Quarterly data begin in 2005. Invalid year: 1997", "Invalid industry: 111CA", "No data exist for selected criteria") | guide |
|
|
333
|
-
| 205 | Error retrieving Input-Output data. ("No data exist for selected criteria") | guide |
|
|
334
|
-
| 206 | Error retrieving GDP by Industry data. (UnderlyingGDPbyIndustry: "Invalid frequency: Q", "Invalid year: 1996", "Invalid industry: 11") | guide |
|
|
335
|
-
|
|
336
|
-
- NIPA, ITA, IIP, MNE and IntlServ* also have error codes; the guide says only "an error will be returned". Those codes are UNVERIFIED.
|
|
337
|
-
- An unregistered key gave code 1 on some requests and code 4 on others [live], so treat both as "bad or inactive key".
|
|
338
|
-
- **Missing `UserID` returns HTTP 200 with an empty body** (Content-Length 0) [live].
|
|
339
|
-
|
|
340
|
-
---------------------------------------------------------------------------------------------------
|
|
341
|
-
## 6. Registration, terms of service, attribution
|
|
342
|
-
|
|
343
|
-
- **Registration:** https://apps.bea.gov/API/signup/ (`/api/` redirects there).
|
|
344
|
-
- The form asks for name or organization, email, a CAPTCHA, and a tick for "I agree to the Terms of Service". **A person must complete it**; the assistant must not try.
|
|
345
|
-
- BEA emails a **36-character UserID** and a link; **the key works only after the link is clicked** [guide].
|
|
346
|
-
- Disposable email addresses are refused, and such registrations may be removed without notice [guide].
|
|
347
|
-
- Contact: developers@bea.gov.
|
|
348
|
-
- **Terms of Service** (apps.bea.gov/API/_pdf/bea_api_tos.pdf). **Required attribution** for any service that uses the API, "displayed prominently": **"This product uses the Bureau of Economic Analysis (BEA) Data API but is not endorsed or certified by BEA."**
|
|
349
|
-
- You may name BEA as the source, but not in a way that implies endorsement.
|
|
350
|
-
- You may not modify or misrepresent content and still credit BEA.
|
|
351
|
-
- BEA may limit access, monitor usage, and block users who try to exceed or get around limits, temporarily or permanently.
|
|
352
|
-
- The API is provided "as is"; federal law governs.
|
|
353
|
-
- **Citation format** (bea.gov/help/guidelines-for-citing-bea): `U.S. Bureau of Economic Analysis, "Table 1.1.1. Percent Change From Preceding Period in Real Gross Domestic Product" (accessed <date>).` Include the vintage of the estimate when relevant, e.g. "second estimates for the second quarter of 2012".
|
|
354
|
-
- **Key storage:** keep the key in an environment variable or `.env` (beaapi suggests a `.env` with `beakey=…`). Never log the full URL with the key in it.
|
|
355
|
-
|
|
356
|
-
---------------------------------------------------------------------------------------------------
|
|
357
|
-
## 7. Time periods, revisions, release timing
|
|
358
|
-
|
|
359
|
-
- **TimePeriod formats:**
|
|
360
|
-
- Annual: `YYYY`
|
|
361
|
-
- Quarterly: `YYYYQn` (e.g. `2015Q1`)
|
|
362
|
-
- Monthly: `YYYYMx` per the guide ("x is the month digit"). In practice months are zero-padded, `2024M01`: this is UNVERIFIED, so parse with the regex `^(\d{4})M(\d{1,2})$`.
|
|
363
|
-
- **The Year parameter takes years only.** For Q/M data, ask for the years and you get every quarter or month in them; filter afterwards.
|
|
364
|
-
- **Frequency codes by dataset:** NIPA/NIUD `A`, `Q`, `M`; GDPbyIndustry `A`, `Q`; ITA `A`, `QSA`, `QNSA`; IIP `A`, `QNSA`. Regional chooses frequency through the table: SA* = annual, SQ* = quarterly, CA* = county annual.
|
|
365
|
-
- **Only the latest estimates.** API data update "on the same release schedule as other published sources of BEA data (e.g. Interactive Tables)" [guide]. The Interactive Tables "only display the most recently released data" and do not identify vintage [citing guidelines].
|
|
366
|
-
- **There is no vintage or as-of parameter.**
|
|
367
|
-
- To spot a revision, use Regional `UTCProductionTime` and "Last updated" notes, or APIDatasetMetaData `ReleaseDate`/`NextReleaseDate`.
|
|
368
|
-
- Past vintages: BEA Data Archive https://apps.bea.gov/histdata/ (not through the API). Third-party vintage sources such as ALFRED are UNVERIFIED here.
|
|
369
|
-
- **Release schedule:** https://www.bea.gov/news/schedule. Machine-readable: **https://apps.bea.gov/API/signup/release_dates.json** (keys are release names, each with `release_dates[]` as ISO-8601 UTC strings, e.g. "Gross Domestic Product", "Personal Income and Outlays", "GDP by County and Personal Income by County"; there is also a `file_last_updated` key). An ICS feed is at /news/schedule/ics/online-calendar-subscription.ics.
|
|
370
|
-
- **Upcoming releases (as of today):** GDP advance estimate for 2026Q3 and Personal Income and Outlays for Sept 2026, both 2026-10-29 at 8:30 ET. Releases come out at 8:30 AM ET.
|
|
371
|
-
- **Annual cycles:** FixedAssets, late August to early October. IntlServTrade, July. IntlServSTA, October.
|
|
372
|
-
|
|
373
|
-
---------------------------------------------------------------------------------------------------
|
|
374
|
-
## 8. Common table codes
|
|
375
|
-
|
|
376
|
-
**NIPA TableName** (titles checked against TablesRegister.txt, apps.bea.gov/national/Release/TXT/TablesRegister.txt, CSV `TableId,TableTitle`, 318 tables including U*, GFS*, OECD*, Rf*). Frequencies follow BEA convention: Q tables also have A, and monthly tables are named. Confirm with GetParameterValues.
|
|
377
|
-
|
|
378
|
-
| TableName | title |
|
|
379
|
-
|---|---|
|
|
380
|
-
| T10101 | 1.1.1 Percent Change From Preceding Period in Real GDP (line 1 = GDP, series A191RL) |
|
|
381
|
-
| T10102 | 1.1.2 Contributions to Percent Change in Real GDP |
|
|
382
|
-
| T10103 | 1.1.3 Real GDP, Quantity Indexes |
|
|
383
|
-
| T10104 | 1.1.4 Price Indexes for GDP |
|
|
384
|
-
| T10105 | 1.1.5 Gross Domestic Product (nominal) |
|
|
385
|
-
| T10106 | 1.1.6 Real GDP, Chained Dollars |
|
|
386
|
-
| T10107 | 1.1.7 Percent Change From Preceding Period in Prices for GDP |
|
|
387
|
-
| T10109 | 1.1.9 Implicit Price Deflators for GDP |
|
|
388
|
-
| T10111 | 1.1.11 Real GDP: Percent Change From Quarter One Year Ago |
|
|
389
|
-
| T10204 / T10205 / T10206 | 1.2.x GDP by Major Type of Product (prices / nominal / real) |
|
|
390
|
-
| T10501–T10506 | 1.5.x GDP, Expanded Detail |
|
|
391
|
-
| T10604 | 1.6.4 Price Indexes for Gross Domestic Purchases |
|
|
392
|
-
| T11000 | 1.10 Gross Domestic Income by Type of Income |
|
|
393
|
-
| T11200 | 1.12 National Income by Type of Income |
|
|
394
|
-
| T11706 | 1.17.6 Real GDP, Real GDI, and Other Major NIPA Aggregates, Chained Dollars |
|
|
395
|
-
| T20100 | 2.1 Personal Income and Its Disposition |
|
|
396
|
-
| T20301 / T20304 / T20305 / T20306 | 2.3.x PCE by Major Type of Product: real % change / price indexes / nominal / real |
|
|
397
|
-
| T20600 | 2.6 Personal Income and Its Disposition, Monthly |
|
|
398
|
-
| T20801–T20807 | 2.8.x PCE by Major Type of Product, Monthly. T20804 = **PCE price indexes, monthly** (PCE and core PCE); T20805 = nominal; T20806 = real; T20807 = % change in prices. |
|
|
399
|
-
| T30100 / T30200 / T30300 | 3.1 / 3.2 / 3.3 Government (total / federal / state and local) current receipts and expenditures |
|
|
400
|
-
| T40100 | 4.1 Foreign Transactions in the NIPAs |
|
|
401
|
-
| T50100 | 5.1 Saving and Investment by Sector |
|
|
402
|
-
| T61600D | 6.16D Corporate Profits by Industry |
|
|
403
|
-
| T70100 | 7.1 Selected Per Capita Product and Income Series |
|
|
404
|
-
| U20304/U20305/U20306, U20404/U20405/U20406 | NIUnderlyingDetail PCE detail: by type and function / by type of product |
|
|
405
|
-
| U70205S | Auto and Truck Unit Sales, Production, Inventories, Expenditures, and Price |
|
|
406
|
-
| U90100 | Reconciliation of Percent Change in the CPI with Percent Change in the PCE Price Index |
|
|
407
|
-
|
|
408
|
-
- Line numbers within a table are not fixed across comprehensive revisions. Pick series by `SeriesCode` + `LineDescription`, not by LineNumber alone.
|
|
409
|
-
- Discontinued 2025-09-25: T20700A (2.7A), T31400 (3.14), and the 6.xA/B/C historical industry tables. T6xxxxD tables are still listed.
|
|
410
|
-
|
|
411
|
-
**Regional TableName** (App. N list). Inside a table, LineCode picks the statistic; `Code` = `TABLE-LINE`.
|
|
412
|
-
|
|
413
|
-
| TableName | content | LineCode convention |
|
|
414
|
-
|---|---|---|
|
|
415
|
-
| SAINC1 / SQINC1 / CAINC1 | personal income summary: state annual 1929→, state quarterly 1948→, county 1969→ | 1 = personal income (thousands of $ for county, millions for state), 2 = population, 3 = per-capita PI ($) [guide] |
|
|
416
|
-
| SAINC4 / SQINC4 / CAINC4 | personal income (and employment) by major component | 10 = personal income, 20 = population, 30 = per-capita PI (the guide's examples use CAINC4 lines 10 and 30); other lines are components (UNVERIFIED) |
|
|
417
|
-
| SAINC5N / CAINC5N, SAINC6N / CAINC6N, SAINC7N | earnings / compensation / wages by NAICS industry | industry line codes; list them with GetParameterValuesFiltered |
|
|
418
|
-
| SAINC30 / CAINC30 | economic profile | see the cuts in §2 |
|
|
419
|
-
| SAINC35, SAINC40, SAINC50, SAINC51 | transfers, property income, taxes, disposable PI | – |
|
|
420
|
-
| SASUMMARY | state annual income and product summary (1998→) | – |
|
|
421
|
-
| SAGDP1–SAGDP11 (also written SAGDP2N, SAGDP9N…) | annual state GDP: 2 = current $ by industry, 3 = taxes less subsidies, 4 = compensation, 8 = quantity index, 9 = real (chained) GDP, 11 = contributions | industry lines. Line 1 = all-industry total (verified in the SAGDP9 bulk file: line 1 "All industry total", line 2 "Private industries"). The guide's SAGDP9N "Real GDP" example uses LineCode=2. |
|
|
422
|
-
| SQGDP1, SQGDP2, SQGDP8, SQGDP9, SQGDP11 | quarterly state GDP (2005→) | same as SAGDP |
|
|
423
|
-
| CAGDP1, CAGDP2, CAGDP8, CAGDP9, CAGDP11 | county GDP (2001→; MSA rows dropped Feb 2026) | industry lines |
|
|
424
|
-
| SARPP / MARPP / PARPP | regional price parities: state / MSA / portion (2008→) | e.g. 1 = all items RPP (UNVERIFIED) |
|
|
425
|
-
| SAPCE1–SAPCE4 | PCE by state (1997→) | – |
|
|
426
|
-
| SAACArts* / SAAC* | arts and culture satellite account by state (2001→); the program is "no longer regularly produced" (2026-02-10) | – |
|
|
427
|
-
| TASUMMARY(1), TASUMMARY2; PRGDP*-* | U.S. territories; Puerto Rico GDP (GeoFips=72000) | – |
|
|
428
|
-
|
|
429
|
-
**Table-name inconsistency:** the 2026 App. N list writes `SAGDP2`, `SAGDP9`, `TASUMMARY`, but its own example and RegionalApi.pdf use `SAGDP9N`/`SAGDP2N`, and the guide's GetParameterValues sample shows `TASUMMARY1`. **Always resolve names with `GetParameterValues(DatasetName=Regional, ParameterName=TableName)`** before calling GetData.
|
|
430
|
-
|
|
431
|
-
---------------------------------------------------------------------------------------------------
|
|
432
|
-
## 9. Implementation checklist
|
|
433
|
-
1. Read the key from the environment, check it is 36 characters, and redact it in logs.
|
|
434
|
-
2. Use metadata calls (cached) to check TableName, LineCode, Frequency and Year before calling GetData.
|
|
435
|
-
3. Request `ResultFormat=JSON`. Parse defensively:
|
|
436
|
-
- unwrap a list-valued `Results`
|
|
437
|
-
- look for `Error` at both `BEAAPI` and `Results`
|
|
438
|
-
- handle `BEAAPI.Data` (IIP) and single-object `Data`
|
|
439
|
-
- treat an empty body or HTML as a server failure
|
|
440
|
-
4. Raise errors with APIErrorCode, description and ErrorDetail. Do not retry on codes 1, 3, 4, 40 or 2xx. On HTTP 429 or code 7, sleep for `Retry-After` (or 60 s), and if the block continues assume up to 1 hour.
|
|
441
|
-
5. Throttle on the client to at most about 90 requests/min, a running byte budget under 100 MB/min, and an error budget under 30/min, all single-threaded.
|
|
442
|
-
6. Parse values: strip commas, map suppression codes to NaN while keeping the raw flag, apply UNIT_MULT, parse TimePeriod (`Y`, `YQn`, `YMmm`), and join Notes through NoteRef.
|
|
443
|
-
7. Show the ToS attribution sentence in outputs and record `UTCProductionTime` or the date retrieved as the vintage.
|
|
444
|
-
|
|
445
|
-
---------------------------------------------------------------------------------------------------
|
|
446
|
-
## URLs opened
|
|
447
|
-
- https://apps.bea.gov/api/_pdf/bea_web_service_api_user_guide.pdf (pypdf, 69 pp.)
|
|
448
|
-
- https://apps.bea.gov/API/signup/ and https://apps.bea.gov/api/ (redirect to signup), https://apps.bea.gov/developers/ (redirect)
|
|
449
|
-
- https://apps.bea.gov/API/_pdf/bea_api_tos.pdf
|
|
450
|
-
- https://apps.bea.gov/API/swagger/index.htm and https://apps.bea.gov/api/swagger/swagger.json
|
|
451
|
-
- https://apps.bea.gov/API/docs/index.htm; https://apps.bea.gov/api/bea_web_service_api_user_guide.htm (now 404)
|
|
452
|
-
- https://web.archive.org/web/20240316125212/https://apps.bea.gov/API/bea_web_service_api_user_guide.htm
|
|
453
|
-
- https://apps.bea.gov/api/data?… (invalid-key test calls, 7 requests)
|
|
454
|
-
- https://apps.bea.gov/national/Release/TXT/TablesRegister.txt
|
|
455
|
-
- https://apps.bea.gov/regional/pdf/RegionalApi.pdf; https://apps.bea.gov/regional/definitions/
|
|
456
|
-
- https://www.bea.gov/data/discontinued-or-delayed-statistics; https://www.bea.gov/itable/discontinued-data-tables
|
|
457
|
-
- https://www.bea.gov/help/guidelines-for-citing-bea; https://www.bea.gov/resources/for-developers; https://apps.bea.gov/developers/r-index.htm
|
|
458
|
-
- https://www.bea.gov/news/schedule; https://apps.bea.gov/API/signup/release_dates.json; https://apps.bea.gov/histdata/
|
|
459
|
-
- https://api.github.com/orgs/us-bea/repos; github.com/us-bea/beaapi (README.md, CHANGELOG.md, beaapi/{__init__, api_request, response_to_dict, response_to_table, throttling_caller, get_data, get_row_data_value, beaapi_error, update_metadata}.py, docs/example_tables.ipynb)
|
|
460
|
-
- https://raw.githubusercontent.com/us-bea/bea_geo_aggregator/HEAD/README.md
|
|
461
|
-
- https://reaproject.org/united-states-sub/analysis/personal-income-ca05n/ (no symbol definitions found)
|
|
1
|
+
# BEA Data API reference
|
|
2
|
+
|
|
3
|
+
This server's `fetch` for bea already implements this: key lookup and redaction, throttling,
|
|
4
|
+
error handling, response quirks, tidy output, and the no-key bulk route. Read this file when you need a
|
|
5
|
+
dataset or parameter the friendly spec does not cover, or when debugging an API error.
|
|
6
|
+
|
|
7
|
+
Contents: 1. Endpoint and methods · 2. Datasets and GetData parameters (NIPA, FixedAssets, MNE,
|
|
8
|
+
GDPbyIndustry, ITA, IIP, InputOutput, IntlServTrade, IntlServSTA, Regional) · 3. Response structure and
|
|
9
|
+
special values · 4. Rate limits · 5. Error codes · 6. Registration, terms, attribution · 7. Time periods,
|
|
10
|
+
revisions, release timing · 8. Common table codes · 9. Implementation checklist
|
|
11
|
+
|
|
12
|
+
**Bulk files (no key).** Besides the API, BEA posts complete files that `fetch` reads when no key works:
|
|
13
|
+
- NIPA: `https://apps.bea.gov/national/Release/TXT/` → `NipaDataA.txt`, `NipaDataQ.txt`, `NipaDataM.txt`
|
|
14
|
+
(`%SeriesCode,Period,Value`), `SeriesRegister.txt` (`SeriesCode,SeriesLabel,MetricName,CalculationType,
|
|
15
|
+
DefaultScale,TableId:LineNo|...,SeriesCodeParents`; DefaultScale -6 = millions) and `TablesRegister.txt`.
|
|
16
|
+
Every published NIPA and NIUnderlyingDetail table can be rebuilt from them (TableId:LineNo → series).
|
|
17
|
+
- Regional: `https://apps.bea.gov/regional/zip/<NAME>.zip`. State tables come in family zips (`SAGDP.zip`,
|
|
18
|
+
`SQGDP.zip`, `SAINC.zip`, `SQINC.zip`, `SAPCE.zip`, `SARPP.zip`, `SAOR.zip`); county tables one per zip
|
|
19
|
+
(`CAINC1.zip`, `CAINC4.zip`, `CAGDP2.zip`, `CAGDP9.zip`, ...); MSA price parities in `MARPP.zip`. Inside:
|
|
20
|
+
`<TABLE>__ALL_AREAS_<first>_<last>.csv` (wide: GeoFIPS, GeoName, Region, TableName, LineCode,
|
|
21
|
+
IndustryClassification, Description, Unit, then one column per year or `2026:Q1` quarter; footer lines
|
|
22
|
+
give "Last updated: ..."), plus `definition.xml` (line definitions) and `Footnotes.html`. A missing zip
|
|
23
|
+
returns HTTP 200 with an HTML page, so check for the `PK` zip signature. Zips for API-only tables
|
|
24
|
+
(metro-area GDP and income, MSA personal income) do not exist.
|
|
25
|
+
- GDP by industry: `https://apps.bea.gov/industry/Release/XLS/GDPxInd/` → `ValueAdded.xlsx` (sheets
|
|
26
|
+
`TVA101-A`, `TVA101-Q` ... `TVA113-A`), `GrossOutput.xlsx` (`TGO1xx`), `IntermediateInputs.xlsx` (`TII1xx`). Each
|
|
27
|
+
sheet: title, `[unit]`, period range, "Data published <date>", then a header row starting `Line` and one row per
|
|
28
|
+
industry; footnotes below. A `Contents` sheet lists the codes. `fetch` reads them itself (no key, no other software).
|
|
29
|
+
- Data are the same, latest vintage as the API. Bulk files are large (NIPA quarterly 35 MB; some county
|
|
30
|
+
zips 45 MB) but need no key and count against no rate limit.
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
Compiled 2026-10-19. Main source: *BEA API for Data Retrieval User Guide* (PDF, main body dated April 20, 2026, 69 pages including appendices). Other sources are the live swagger.json, the Terms of Service PDF, BEA's own `us-bea/beaapi` Python package (v0.2.0, Feb 2026), test calls made with an invalid key, and the BEA pages listed at the end.
|
|
34
|
+
Tags: **[guide]** user guide PDF; **[swagger]** apps.bea.gov/api/swagger/swagger.json; **[live]** observed today with an invalid key; **[beaapi]** source code of BEA's official Python client; **[2024-htm]** Wayback copy (2024-03-16) of the older HTML guide. **UNVERIFIED** means no primary source was checked or data calls were not possible.
|
|
35
|
+
|
|
36
|
+
---------------------------------------------------------------------------------------------------
|
|
37
|
+
## 1. Endpoint, request format, methods
|
|
38
|
+
|
|
39
|
+
- **Single endpoint:** `https://apps.bea.gov/api/data` (also accepts `.../api/data/`) [guide]. The guide says "All API access is through this URI; no other paths are used."
|
|
40
|
+
- **Requests:** HTTP **GET** with query-string parameters only. Every request needs `UserID` and `method`. GetData and the parameter metadata methods also need `DatasetName`.
|
|
41
|
+
- **Case:** parameter names are case-insensitive [live]: `userid=…&METHOD=getdatasetlist&resultformat=xml` worked, and the server echoes names and values in UPPERCASE in `Request.RequestParam`. Method names and dataset names are case-insensitive too (the guide's own examples use `GETDATASETLIST`, `getparameterlist`, `INTLSERVTRADE`, `underlyingGDPbyIndustry`). Case-insensitivity of other parameter *values*, such as table names, is UNVERIFIED (likely), so pass codes exactly as returned by GetParameterValues.
|
|
42
|
+
- **Multiple values:** use one comma-separated string, e.g. `Year=2022,2023,2024` or `Frequency=A,Q,M` [guide]. URL-encode it, although commas work raw.
|
|
43
|
+
- **`ResultFormat`:** `JSON` (the default, also used when the value is invalid) or `XML` [guide]. Content-Type is `application/json` or `application/xml` [live].
|
|
44
|
+
- **Other features:** an optional `jsonp=<callbackName>` wraps the response for legacy browsers. CORS headers are on all responses [guide].
|
|
45
|
+
- **Encoding:** beaapi decodes responses as `iso-8859-1` because "utf-8 returns decode errors" [beaapi].
|
|
46
|
+
- **Methods** [guide] (the guide has a separate section for each):
|
|
47
|
+
|
|
48
|
+
| method | required params (besides UserID) | returns `Results.` |
|
|
49
|
+
|---|---|---|
|
|
50
|
+
| `GetDataSetList` | – | `Dataset[]` {DatasetName, DatasetDescription} |
|
|
51
|
+
| `GetParameterList` | `DatasetName` | `Parameter[]` {ParameterName, ParameterDataType (string/integer), ParameterDescription, ParameterIsRequiredFlag 0/1, ParameterDefaultValue, MultipleAcceptedFlag 0/1, AllValue} |
|
|
52
|
+
| `GetParameterValues` | `DatasetName`, `ParameterName` | `ParamValue[]`, usually {Key, Desc}. Some datasets use other attribute names, e.g. FixedAssets in 2024-htm: `TableID`/`Description`. Read the keys generically. |
|
|
53
|
+
| `GetParameterValuesFiltered` | `DatasetName`, `TargetParameter`, plus filter params | `ParamValue[]` {Key, Desc}. **Not supported by every dataset**: NIPA returns error 34. Supported by Regional, and ITA in the beaapi README example (`targetparameter='Indicator', AreaOrCountry='China', Frequency='A', Year='2011'`). Support in other datasets is UNVERIFIED. |
|
|
54
|
+
| `GetData` | `DatasetName` + dataset-specific params | `Dimensions`, `Data`, `Notes` (+ dataset extras); see §3 |
|
|
55
|
+
|
|
56
|
+
- The guide says that for NIPA/NIUnderlyingDetail/FixedAssets, "passing a TableName value" to GetParameterValues tells you the valid frequencies and years for that table. The exact request form is UNVERIFIED.
|
|
57
|
+
- **Key format:** a 36-character GUID, e.g. `11111111-2222-3333-4444-555555555555` in the guide's example [guide]. beaapi strips spaces and rejects any key whose length is not 36 [beaapi].
|
|
58
|
+
|
|
59
|
+
---------------------------------------------------------------------------------------------------
|
|
60
|
+
## 2. Datasets and GetData parameters
|
|
61
|
+
|
|
62
|
+
**Current dataset list** (from the GetDataSetList example in the April 2026 guide; the same 13 appear in swagger and the beaapi README):
|
|
63
|
+
NIPA, NIUnderlyingDetail, MNE, FixedAssets, ITA, IIP, InputOutput, IntlServTrade, IntlServSTA, GDPbyIndustry, Regional, UnderlyingGDPbyIndustry, APIDatasetMetaData.
|
|
64
|
+
|
|
65
|
+
**Retired (calls "will no longer function")** [guide App. A/I/J]:
|
|
66
|
+
- `RegionalData` (2019)
|
|
67
|
+
- `RegionalIncome` and `RegionalProduct` (Dec 2019). Use `Regional` instead. Crosswalk: apps.bea.gov/regional/pdf/RegionalApi.pdf, e.g. RegionalIncome SA1 → SAINC1, CA4 → CAINC4; RegionalProduct GDP_SAN → SAGDP2N, RGDP_SAN → SAGDP9N, RGDP_SQN → SQGDP9.
|
|
68
|
+
|
|
69
|
+
**Retired parameters:**
|
|
70
|
+
- NIPA/NIUnderlyingDetail `TableID` was replaced by `TableName` (Feb 2018). The guide has crosswalks, e.g. TableID 1 = T10101.
|
|
71
|
+
- FixedAssets `TableID` → `TableName` (Oct 2018).
|
|
72
|
+
- NIPA `ShowMillions` was discontinued in Oct 2017 [2024-htm], although swagger still lists it. Use UNIT_MULT instead.
|
|
73
|
+
|
|
74
|
+
**NIUnderlyingDetail is still active.** It is in the 2026 guide, swagger, signup page and TablesRegister.txt (U-prefixed tables). Some underlying tables were dropped: Section 0 inventories/sales tables 4AU*, 4BU*, 6U, 7U (2024-07-01), and 9.2U and 9.5U (2025-09-25) [discontinued-stats page]. BEA caution: underlying detail is lower quality than the published aggregates [guide App. C/L].
|
|
75
|
+
|
|
76
|
+
The tables below use these columns: Req = required; Multi = multiple values accepted; All = "all" keyword. Parameter details come from the guide appendices.
|
|
77
|
+
|
|
78
|
+
### NIPA (App. B) and NIUnderlyingDetail (App. C): same parameters
|
|
79
|
+
| param | Req | Multi | All | notes |
|
|
80
|
+
|---|---|---|---|---|
|
|
81
|
+
| TableName | Y | N | – | e.g. `T10101`, `U20305`. One table per request. |
|
|
82
|
+
| Frequency | Y | Y | – | `A`, `Q`, `M`. Frequencies a table lacks are skipped; if none match, an error is returned. |
|
|
83
|
+
| Year | Y | Y | `X` or `ALL` | Q/M requests return all available periods within each requested year. |
|
|
84
|
+
|
|
85
|
+
Examples:
|
|
86
|
+
- `?UserID=KEY&method=GetData&DataSetName=NIPA&TableName=T10101&Frequency=A,Q&Year=ALL`
|
|
87
|
+
- `?UserID=KEY&method=GetData&DataSetName=NIPA&TableName=T20600&Frequency=M&Year=2015,2016`
|
|
88
|
+
- `?UserID=KEY&method=GetData&DataSetName=NIUnderlyingDetail&TableName=U70205S&Frequency=M&Year=2015,2016`
|
|
89
|
+
|
|
90
|
+
### FixedAssets (App. D)
|
|
91
|
+
| param | Req | Multi | All |
|
|
92
|
+
|---|---|---|---|
|
|
93
|
+
| TableName (e.g. `FAAt201`) | Y | N | – |
|
|
94
|
+
| Year | Y | Y | `X` or `ALL` |
|
|
95
|
+
|
|
96
|
+
Annual only. Updated once a year, typically late August to early October.
|
|
97
|
+
Example: `?UserID=KEY&method=GetData&DataSetName=FixedAssets&TableName=FAAt201&Year=ALL`
|
|
98
|
+
Caveat: swagger names the parameter `tableID` while the guide uses `TableName`. Prefer `TableName`.
|
|
99
|
+
|
|
100
|
+
### MNE (App. E): two request types
|
|
101
|
+
- **Direct Investment (DI):**
|
|
102
|
+
- Required: `DirectionOfInvestment` (`Outward` or `Inward`), `Classification` (single value, e.g. `Country`, `CountryByIndustry`), `Year` (multiple values or `all`).
|
|
103
|
+
- Optional: `SeriesID` (multiple; default all, `0` = all), `Country` (3-digit codes; `000` = all-countries total, `all` = every country and region), `Industry` (4-digit NAICS-like codes; `0000` = all-industries total, `all` = every industry), `GetFootnotes` (`Yes` or `No`, default No).
|
|
104
|
+
- **Activities of MNEs (AMNE):**
|
|
105
|
+
- Required: `DirectionOfInvestment` (`Outward`, `Inward`, `State` or `Parent`), `OwnershipLevel` (`0` = majority-owned affiliates, `1` = all affiliates; must be 1 when Direction=Parent), `NonBankAffiliatesOnly` (`0` = bank and nonbank affiliates, which suits outward 2009+ and inward 2007+; `1` = nonbank only, for earlier years), `Classification`, `Year`.
|
|
106
|
+
- Optional: `SeriesID`, `Country`, `Industry`, `State` (2-digit FIPS; `00` = US total, `70` = other US areas, `75` = foreign, `all`), `GetFootnotes`.
|
|
107
|
+
- With `State`, only employment (and, for limited years, gross property, plant and equipment) is available.
|
|
108
|
+
- Swagger also lists the undocumented parameters `investment` and `parentInvestment` (meaning UNVERIFIED).
|
|
109
|
+
|
|
110
|
+
Examples:
|
|
111
|
+
- `?UserID=KEY&method=GetData&DataSetName=MNE&SeriesID=30&Year=2011,2012&Country=650,699&DirectionOfInvestment=Outward&Classification=Country`
|
|
112
|
+
- `?UserID=KEY&method=GetData&DataSetName=MNE&Year=2011&Country=all&Industry=0000&DirectionOfInvestment=Inward&Classification=Country&SeriesID=8&OwnershipLevel=0&NonbankAffiliatesOnly=0&GetFootnotes=Yes`
|
|
113
|
+
|
|
114
|
+
### GDPbyIndustry (App. F; the PDF page footers mislabel this appendix as "Appendix E - MNE")
|
|
115
|
+
| param | Req | Multi | All |
|
|
116
|
+
|---|---|---|---|
|
|
117
|
+
| TableID (integer) | Y | Y | `ALL` |
|
|
118
|
+
| Frequency | Y | Y | `A` and/or `Q` |
|
|
119
|
+
| Year | Y | Y | `ALL` |
|
|
120
|
+
| Industry | Y | Y | `ALL` |
|
|
121
|
+
|
|
122
|
+
- Annual data start in 1997 (1998 for percent-change and contributions tables). Quarterly data start in 2005.
|
|
123
|
+
- In GetParameterValues, a description marked "(A)" means annual and "(Q)" means also quarterly.
|
|
124
|
+
- Requesting Q for a table that is annual-only gives error 204.
|
|
125
|
+
|
|
126
|
+
Examples:
|
|
127
|
+
- `?UserID=KEY&method=GetData&DataSetName=GDPbyIndustry&TableID=1&Frequency=A&Year=2011,2012&Industry=ALL`
|
|
128
|
+
- `?UserID=KEY&method=GetData&DataSetName=GDPbyIndustry&TableID=ALL&Frequency=A,Q&Year=2010&Industry=11`
|
|
129
|
+
|
|
130
|
+
### UnderlyingGDPbyIndustry (App. L)
|
|
131
|
+
- Same 4 parameters as GDPbyIndustry, all required, but **Frequency=A only** (Q gives error 206, "Invalid frequency: Q").
|
|
132
|
+
- Data run from 1997 to the present.
|
|
133
|
+
|
|
134
|
+
Example: `?UserID=KEY&method=GetData&DataSetName=UnderlyingGDPbyIndustry&TableID=210&Frequency=A&Year=2012,2013&Industry=ALL`
|
|
135
|
+
|
|
136
|
+
### ITA, International Transactions (App. G). All parameters optional and multi-valued.
|
|
137
|
+
- `Indicator` (default All; e.g. `BalGds`, `PfInvAssets`)
|
|
138
|
+
- `AreaOrCountry` (default `AllCountries` = total; `All` = every area and country; e.g. `China`)
|
|
139
|
+
- `Frequency` (`A`, `QSA`, `QNSA`)
|
|
140
|
+
- `Year` (default All)
|
|
141
|
+
|
|
142
|
+
**Rule:** you can request multiple Indicators only with exactly one AreaOrCountry that is not All or AllCountries. Likewise, a list of countries (or AllCountries) works only with exactly one Indicator.
|
|
143
|
+
|
|
144
|
+
Examples:
|
|
145
|
+
- `?UserID=KEY&method=GetData&DataSetName=ITA&Indicator=BalGds&AreaOrCountry=China&Frequency=A&Year=2011,2012`
|
|
146
|
+
- `?UserID=KEY&method=GetData&DataSetName=ITA&Indicator=PfInvAssets&AreaOrCountry=AllCountries&Frequency=QNSA&Year=2013`
|
|
147
|
+
|
|
148
|
+
### IIP, International Investment Position (App. H). All optional and multi-valued.
|
|
149
|
+
- `TypeOfInvestment` (e.g. `FinAssetsExclFinDeriv`, `FinLiabsFoa`)
|
|
150
|
+
- `Component` (`Pos` = position; changes such as `ChgPosTrans`, `ChgPosPrice`)
|
|
151
|
+
- `Frequency` (`A`, `QNSA`)
|
|
152
|
+
- `Year`
|
|
153
|
+
|
|
154
|
+
**Rule:** more than one TypeOfInvestment requires exactly one Year that is not ALL, and more than one Year requires exactly one TypeOfInvestment.
|
|
155
|
+
|
|
156
|
+
Examples:
|
|
157
|
+
- `?UserID=KEY&method=GetData&DataSetName=IIP&TypeOfInvestment=FinAssetsExclFinDeriv&Component=ChgPosPrice&Frequency=A&Year=ALL`
|
|
158
|
+
- `?UserID=KEY&method=GetData&DataSetName=IIP&TypeOfInvestment=FinLiabsFoa&Component=Pos&Frequency=QNSA&Year=2013`
|
|
159
|
+
|
|
160
|
+
### InputOutput (App. K)
|
|
161
|
+
| param | Req | Multi | All |
|
|
162
|
+
|---|---|---|---|
|
|
163
|
+
| TableID (integer) | Y | Y | none |
|
|
164
|
+
| Year | Y | Y | `ALL` |
|
|
165
|
+
|
|
166
|
+
Some tables exist only for benchmark years (e.g. Use tables in purchasers' prices: 2007).
|
|
167
|
+
Examples:
|
|
168
|
+
- `?UserID=KEY&method=GetData&DataSetName=InputOutput&TableID=56&Year=2010,2011,2012,2013`
|
|
169
|
+
- `?UserID=KEY&method=GetData&DataSetName=InputOutput&TableID=56,57&Year=2007`
|
|
170
|
+
|
|
171
|
+
The guide warns that IO parameter values change, so always refresh them with GetParameterValues.
|
|
172
|
+
|
|
173
|
+
### IntlServTrade (App. M). Annual data, updated each July. All optional and multi-valued.
|
|
174
|
+
- `TypeOfService` (default All; e.g. `AllServiceTypes`, `Telecom`)
|
|
175
|
+
- `TradeDirection` (`Exports`, `Imports`, `Balance`, `SupplementalIns`)
|
|
176
|
+
- `Affiliation` (`AllAffiliations`, `Unaffiliated`, `Affiliated`, `UsParents`, `UsAffiliates`)
|
|
177
|
+
- `AreaOrCountry` (default `AllCountries`; `All` = every area and country)
|
|
178
|
+
- `Year`
|
|
179
|
+
|
|
180
|
+
**Rule:** multiple TypeOfService values require one specific AreaOrCountry, and a list of countries requires one specific TypeOfService.
|
|
181
|
+
|
|
182
|
+
Examples:
|
|
183
|
+
- `?UserID=KEY&method=GetData&DataSetName=IntlServTrade&TypeOfService=AllServiceTypes&TradeDirection=Imports&Affiliation=AllAffiliations&AreaOrCountry=Germany&Year=2014,2015`
|
|
184
|
+
- `?UserID=KEY&method=GetData&DataSetName=IntlServTrade&TypeOfService=Telecom&TradeDirection=Exports&Affiliation=UsParents&AreaOrCountry=AllCountries&Year=All`
|
|
185
|
+
|
|
186
|
+
### IntlServSTA (App. O, Oct 2023). Annual data, updated each October. All optional and multi-valued.
|
|
187
|
+
- `Channel` (`Mofas`, `Mousas`, `AllChannels`, `Trade`, `UsExportsByMousas`, `UsImportsFromMofas`)
|
|
188
|
+
- `Destination`:
|
|
189
|
+
- MOFAs: `AllForeign`, `ForeignAffs`, `ForeignUnaff`, `HostCtry`, `HostCtryAffs`, `HostCtryUnaff`, `ForeignOther`, `ForeignOtherAffs`, `ForeignOtherUnaff`
|
|
190
|
+
- MOUSAs: `AllUs`
|
|
191
|
+
- `Industry` (default `AllInd` = total; `All` = every industry; e.g. `RetailTrade`, `Mining`)
|
|
192
|
+
- `AreaOrCountry` (default `AllCountries`)
|
|
193
|
+
- `Year`
|
|
194
|
+
|
|
195
|
+
Examples:
|
|
196
|
+
- `?UserID=KEY&method=GetData&DataSetName=IntlServSTA&Channel=Mofas&Destination=AllForeign&Industry=RetailTrade&AreaOrCountry=India&Year=2015,2016`
|
|
197
|
+
- `?UserID=KEY&method=GetData&DataSetName=IntlServSTA&Channel=Mousas&Destination=AllUs&Industry=Mining&AreaOrCountry=Europe`
|
|
198
|
+
|
|
199
|
+
### Regional (App. N, dated April 24, 2026)
|
|
200
|
+
| param | Req | Multi | special values |
|
|
201
|
+
|---|---|---|---|
|
|
202
|
+
| TableName | Y | N | one table per request |
|
|
203
|
+
| LineCode | Y | N | integer, or `ALL`. With `ALL`, **only one GeoFips** is allowed. |
|
|
204
|
+
| GeoFips | Y | Y (unless LineCode=ALL) | `STATE`, `COUNTY`, `MSA`, `MIC`, `PORT`, `DIV`, `CSA`, `TERR`, a state postal abbreviation (all counties in that state, e.g. `NY`), or a list of 5-digit codes |
|
|
205
|
+
| Year | N | Y | default `LAST5`; also `LAST10`, `ALL` |
|
|
206
|
+
|
|
207
|
+
- **GeoFips codes:** `00000` = US; states are `SS000` (e.g. `01000` Alabama); counties are `SSCCC`; BEA regions are `91000`–`98000` (e.g. `97000` Rocky Mountain, `98000` Far West); `72000` = Puerto Rico (PRGDP* tables). Component counties of each MSA: apps.bea.gov/regional/geography.htm.
|
|
208
|
+
- **GetParameterValuesFiltered (Regional)** accepts comma-separated lists for TableName and LineCode, unlike GetData:
|
|
209
|
+
- `TargetParameter=LineCode&TableName=SAINC4`: line codes for a table
|
|
210
|
+
- `TargetParameter=Year&TableName=CAINC5N&GeoFips=01001`: years available
|
|
211
|
+
- `TargetParameter=GeoFips&TableName=CAINC4&LineCode=10`: geographies
|
|
212
|
+
- `TargetParameter=TableName&GeoFips=00000&Year=2024`: tables
|
|
213
|
+
- **Feb 2026 change:** BEA **stopped producing GDP and personal income for MSAs, MICs, DIVs, CSAs and metro/nonmetro PORTs** in the county tables (CAINC1/4/5N/5S/6N/6S/30, CAGDP1/2/8/9/11). It announced this in 2025 and in the 2026-02-05 county release. MARPI/PARPI (real personal income) for MSAs and portions were dropped on 2026-02-19 [discontinued-stats page; us-bea/bea_geo_aggregator README; FAQ 1481].
|
|
214
|
+
- Expect `MSA`/`PORT` GeoFips to fail or return only historical data for these tables (UNVERIFIED which).
|
|
215
|
+
- BEA's `bea_geo_aggregator` repo rebuilds MSA estimates from county data. The archive apps.bea.gov/histdata/ has the old MSA vintages.
|
|
216
|
+
- Status of MARPP and PARPP (regional price parities) by MSA is UNVERIFIED. They are still listed in App. N.
|
|
217
|
+
- **Earlier cuts** (2024): SAEMP25, SAEMP27, SAINC45, CAEMP25, CAINC35, CAINC45 discontinued; specific lines dropped, e.g. CAINC4 7010/7020/7040, CAINC30 240–310, SAINC30 270/280/310.
|
|
218
|
+
|
|
219
|
+
Examples:
|
|
220
|
+
- `?UserID=KEY&method=GetData&datasetname=Regional&TableName=CAINC1&LineCode=1&GeoFips=COUNTY&Year=2012,2013`
|
|
221
|
+
- `?UserID=KEY&method=GetData&datasetname=Regional&TableName=SAINC1&LineCode=3&GeoFips=STATE&Year=2013`
|
|
222
|
+
- `?UserID=KEY&method=GetData&datasetname=Regional&TableName=SAGDP9N&LineCode=2&GeoFips=STATE&Year=ALL` (the guide calls this "Real GDP for all states")
|
|
223
|
+
|
|
224
|
+
### APIDatasetMetaData (still listed; not documented in the guide)
|
|
225
|
+
- Swagger shows one required parameter, `dataset`. beaapi calls `method=GetData&datasetname=APIDatasetMetaData&dataset=NIPA,NIUnderlyingDetail,FixedAssets`.
|
|
226
|
+
- **The response is not wrapped in `Results`.** It looks like `BEAAPI.Datasets[]`, each with {Datasetname, MetaDataUpdated, `APITable[]`}. Each APITable has {TableId, TableName (the title), ReleaseDate, NextReleaseDate, `Line[]`}, and each Line has {SeriesCode, RowNumber, LineDescription, LineNumber, ParentLineNumber, Tier, Path}.
|
|
227
|
+
- ReleaseDate looks like `"Feb 28 2019 8:30AM"` [beaapi README]. Only NIPA, NIUnderlyingDetail and FixedAssets are known to be supported [beaapi].
|
|
228
|
+
- Its structure comes from beaapi source only, so treat it as UNVERIFIED live.
|
|
229
|
+
|
|
230
|
+
---------------------------------------------------------------------------------------------------
|
|
231
|
+
## 3. GetData response structure
|
|
232
|
+
|
|
233
|
+
Common shape [guide]: `{"BEAAPI":{"Request":{"RequestParam":[{ParameterName,ParameterValue}…]},"Results":{…}}}`. Results usually contains:
|
|
234
|
+
- **`Dimensions[]`**: {Ordinal, Name, DataType ("string" or "numeric"), IsValue ("1" for the value column)}.
|
|
235
|
+
- Regional sometimes omits `Ordinal` [beaapi].
|
|
236
|
+
- Fields within a Data row are **not in a guaranteed order**, so always read them by name.
|
|
237
|
+
- **`Data[]`**: one object per observation; **every field is a string**.
|
|
238
|
+
- **`Notes[]`**: {NoteRef, NoteText}.
|
|
239
|
+
- A `NoteRef` on a data row (or on Results) points to a note. It can hold several comma-separated refs, or extra symbols (e.g. `"2 *"` matches notes "2" and "*").
|
|
240
|
+
- Regional also returns notes with `NoteRef` `"Note."` (units) and `" "` (e.g. "Last updated: February 5, 2026-- new statistics for 2024; revised statistics for 2020-2023.").
|
|
241
|
+
- For NIPA, every row has at least one NoteRef pointing to the table title. In practice it is the TableName, e.g. `T20305` [beaapi README].
|
|
242
|
+
- **Extras:**
|
|
243
|
+
- Regional: `Statistic`, `UnitOfMeasure`, `PublicTable`, `UTCProductionTime` (e.g. `2026-03-25T19:25:39.113`), `NoteRef` [guide].
|
|
244
|
+
- NIPA: `Statistic` ("NIPA Table"), `UTCProductionTime` [beaapi].
|
|
245
|
+
- **Quirks** [beaapi]:
|
|
246
|
+
- `Results` can be a **1-element list** instead of an object (unwrap it).
|
|
247
|
+
- **IIP puts `Data` at `BEAAPI.Data`**, not inside Results.
|
|
248
|
+
- `Data` (and `Notes`) can be a single **object** instead of a list when there is only one observation.
|
|
249
|
+
- `Error` can appear at `BEAAPI.Error` as well as `Results.Error`, and can be a list.
|
|
250
|
+
|
|
251
|
+
**Fields per dataset** ([guide] where marked; otherwise [beaapi]):
|
|
252
|
+
- **NIPA / NIUnderlyingDetail / FixedAssets** [guide]: TableName, SeriesCode, LineNumber, LineDescription, TimePeriod, METRIC_NAME (the guide writes "Metric_Name", but live output uses `METRIC_NAME`), CL_UNIT, UNIT_MULT, DataValue, NoteRef.
|
|
253
|
+
- Sample row: `{"TableName":"T20305","SeriesCode":"DPCERC","LineNumber":"1","LineDescription":"Personal consumption expenditures (PCE)","TimePeriod":"2015Q1","METRIC_NAME":"Current Dollars","CL_UNIT":"Level","UNIT_MULT":"6","DataValue":"12,119,763","NoteRef":"T20305"}`. The commas are inferred from the guide ("formatted with commas"); beaapi removes them.
|
|
254
|
+
- SeriesCode values may repeat across LineNumbers. Key on (LineNumber, TimePeriod).
|
|
255
|
+
- **Regional** [guide]: Code (`TABLE-LINE`, e.g. `CAINC1-3`), GeoFips, GeoName (may end in ` *` when there is a footnote), TimePeriod, CL_UNIT (e.g. "Dollars"), UNIT_MULT, DataValue, NoteRef. beaapi also expects an optional `Description`.
|
|
256
|
+
- **ITA / IIP** [guide]: Indicator or TypeOfInvestment, AreaOrCountry or Component, Frequency, Year, TimeSeriesId, TimeSeriesDescription, TimePeriod, CL_UNIT (e.g. USD), UNIT_MULT, DataValue (**may be blank**), NoteRef (may be blank).
|
|
257
|
+
- **IntlServTrade** [guide]: TypeOfService, TradeDirection, Affiliation, AreaOrCountry, Year, TimeSeriesId, TimeSeriesDescription, TimePeriod, CL_UNIT, UNIT_MULT, DataValue (may be blank), NoteRef.
|
|
258
|
+
- **IntlServSTA** [guide]: Channel, Destination, Industry, AreaOrCountry, Year, TimeSeriesId, TimeSeriesDescription, TimePeriod, CL_UNIT, UNIT_MULT, DataValue, NoteRef.
|
|
259
|
+
- **GDPbyIndustry** [beaapi]: TableID, Frequency, Year, Quarter (equals Year when Frequency=A, otherwise I–IV), Industry, `IndustrYDescription` (sic, odd capitalisation), DataValue, NoteRef.
|
|
260
|
+
- **UnderlyingGDPbyIndustry** [beaapi]: TableID, Frequency, Year, Industry, IndustrYDescription, DataValue, NoteRef.
|
|
261
|
+
- **InputOutput** [beaapi]: TableID, Year, RowCode, RowDescr, RowType, ColCode, ColDescr, ColType, DataValue, NoteRef.
|
|
262
|
+
- **MNE** [beaapi]: SeriesID, SeriesName, Row, RowCode, Column, ColumnCode, ColumnParent, ColumnParentCode, ColumnGParent, ColumnGParentCode, TableScale, Year, TableRowDisplayOrder, TableColumnDisplayOrder, DataValue, DataValueUnformatted. `RowCode` can be `' '` on several rows, so key with the display-order fields too.
|
|
263
|
+
- **GDPbyIndustry / UnderlyingGDPbyIndustry / InputOutput:** "Blanks will not be returned for missing data" [guide].
|
|
264
|
+
|
|
265
|
+
**Value handling:**
|
|
266
|
+
- DataValue is a string that may contain thousands separators, e.g. "1,337". Strip commas before parsing.
|
|
267
|
+
- Real value = DataValue × 10^UNIT_MULT (6 = millions, 9 = billions) [guide].
|
|
268
|
+
- CL_UNIT tells you the unit, e.g. "USD", "PC" (percent), "Level", "Dollars" [guide].
|
|
269
|
+
- Non-numeric DataValues that beaapi handles:
|
|
270
|
+
- `(D)` = suppressed to avoid disclosing data of individual companies or establishments; also used for MNE, Regional and Fixed Assets cells. BEA FAQ: "A (D) indicates a data suppression".
|
|
271
|
+
- `(NM)` = not meaningful.
|
|
272
|
+
- `(NA)` = not available.
|
|
273
|
+
- `(*)` = MNE: nonzero value that rounds to zero (beaapi maps it to 0).
|
|
274
|
+
- `n.s.` = MNE: not shown.
|
|
275
|
+
- `n.a.` = not available.
|
|
276
|
+
- beaapi only blanks `(D)` and `(NM)` when NoteRef has the same code.
|
|
277
|
+
- Regional table symbols `(L)` (less than $50,000 or fewer than 10 jobs, shown as 0), `(S)`, `(X)`, `(T)`, `(NA)` are **UNVERIFIED**: no BEA page found that defines them.
|
|
278
|
+
- Robust approach: if `DataValue.replace(',','')` does not parse as a float, store NaN and keep the raw string in a `flag` column.
|
|
279
|
+
|
|
280
|
+
---------------------------------------------------------------------------------------------------
|
|
281
|
+
## 4. Rate limits and throttling
|
|
282
|
+
|
|
283
|
+
**Current guide (2026)**, per user account:
|
|
284
|
+
- **100 requests/minute**, and/or
|
|
285
|
+
- **100 MB of data retrieved/minute**, and/or
|
|
286
|
+
- **30 errors/minute**.
|
|
287
|
+
|
|
288
|
+
If any limit was exceeded in the previous minute, every further request errors during the timeout. The guide says the timeout is "currently one minute – but may change dynamically to accommodate API activity levels". BEA says it adjusts these limits periodically.
|
|
289
|
+
|
|
290
|
+
**Throttled response:**
|
|
291
|
+
- **HTTP 429 Too Many Requests**, with a `Retry-After` header in seconds (example `retry-after: 59`). The value counts down on each further request until the timeout ends.
|
|
292
|
+
- JSON body error, e.g. `APIErrorCode "7"` "Request Denied - exceeded Requests per minute quota." Matching messages for the data-volume and error quotas presumably exist; their wording and codes are UNVERIFIED.
|
|
293
|
+
|
|
294
|
+
**Contradiction: lockout length.** BEA's own code says the block lasts **1 hour**:
|
|
295
|
+
- beaapi: `BACKOFF_SECS = 60*60`, and the message "your requests will be blocked for the next hour".
|
|
296
|
+
- bea_geo_aggregator README (2026): "temporarily blocked from the API for an hour".
|
|
297
|
+
- Plan for up to 1 hour, and obey `Retry-After` when it is present.
|
|
298
|
+
|
|
299
|
+
**Older limits** [2024-htm, archived Mar 2024]: 1000 calls/min, 30 errors/min, 50 MB/min. Current limits are **lower on requests (100) and higher on data volume (100 MB)**.
|
|
300
|
+
|
|
301
|
+
**No documented maximum on rows or response size.** Signs of an oversized request:
|
|
302
|
+
- An empty 200 body. beaapi reads this as "Likely the query timed out. Try again with narrower parameters."
|
|
303
|
+
- An HTML error page ("An error occurred while executing the application").
|
|
304
|
+
|
|
305
|
+
**Guidance** [guide]:
|
|
306
|
+
1. Fetch only after releases; check the schedule.
|
|
307
|
+
2. Count requests and bytes and pause before reaching the limits. beaapi counts 100 MB as 100·1000·1024 bytes and leaves headroom of 1 request, 1 error and the largest recent response.
|
|
308
|
+
3. On a 429, pause for the `Retry-After` period (the guide says 60 s); retrying during the timeout just extends it.
|
|
309
|
+
4. Use a single thread and run requests one after another. beaapi warns that throttling cannot coordinate across processes.
|
|
310
|
+
5. Use `ALL`/`X` on **at most one parameter**.
|
|
311
|
+
|
|
312
|
+
**Ways to split requests:** by year range (e.g. 10-year chunks for Q/M NIPA data), by one table per call (already required for NIPA/Regional), by GeoFips list instead of `COUNTY`+`ALL`, and one LineCode per call for Regional.
|
|
313
|
+
Errors count toward the 30/min limit, so validate parameters with metadata calls first and never retry on API error codes.
|
|
314
|
+
|
|
315
|
+
---------------------------------------------------------------------------------------------------
|
|
316
|
+
## 5. Error codes
|
|
317
|
+
|
|
318
|
+
Errors normally arrive as **HTTP 200** with `Results.Error {APIErrorCode, APIErrorDescription}`. There may also be `ErrorDetail {Description}` children; in JSON, collect every key other than code and description. Throttling is the exception: HTTP 429.
|
|
319
|
+
|
|
320
|
+
**The guide has no master table.** Every code BEA documents or that was observed:
|
|
321
|
+
|
|
322
|
+
| code | description (verbatim) | source |
|
|
323
|
+
|---|---|---|
|
|
324
|
+
| 1 | Invalid Request - Invalid API UserId. | guide; live (GUID-shaped bad key on GetData or a bad method) |
|
|
325
|
+
| 3 | The BEA API UserID provided in the request does not exist. | 2024-htm |
|
|
326
|
+
| 4 | This UserId is not active. Please activate it and try again. | live (key `X`; and an all-zero GUID on GETDATASETLIST). Also what an unactivated key would return (inferred). |
|
|
327
|
+
| 7 | Request Denied - exceeded Requests per minute quota. | guide (sent with HTTP 429) |
|
|
328
|
+
| 34 | The GetParameterValuesFiltered method has not been implemented on this dataset (coming soon). | guide (NIPA) |
|
|
329
|
+
| 40 | The dataset requested requires parameters that were missing from the request | guide. Regional also uses 40 for invalid values: detail such as "TableName entered is invalid" or "TableName entered is incompatible with the entered GeoFips, LineCode and Year", plus suggested values. |
|
|
330
|
+
| 201 | Error retrieving Fixed Assets data. (detail e.g. "Invalid table IDs were requested.", "The requested parameters did not return data.") | 2024-htm |
|
|
331
|
+
| 203 | No parameter values match the filtered list requested (Regional GetParameterValuesFiltered; detail e.g. "LineCode entered is invalid", "Values of GeoFips and LineCode are incompatible") | guide |
|
|
332
|
+
| 204 | Error retrieving GDP by Industry data. (detail e.g. "This TableID is not published quarterly: 25", "Quarterly data begin in 2005. Invalid year: 1997", "Invalid industry: 111CA", "No data exist for selected criteria") | guide |
|
|
333
|
+
| 205 | Error retrieving Input-Output data. ("No data exist for selected criteria") | guide |
|
|
334
|
+
| 206 | Error retrieving GDP by Industry data. (UnderlyingGDPbyIndustry: "Invalid frequency: Q", "Invalid year: 1996", "Invalid industry: 11") | guide |
|
|
335
|
+
|
|
336
|
+
- NIPA, ITA, IIP, MNE and IntlServ* also have error codes; the guide says only "an error will be returned". Those codes are UNVERIFIED.
|
|
337
|
+
- An unregistered key gave code 1 on some requests and code 4 on others [live], so treat both as "bad or inactive key".
|
|
338
|
+
- **Missing `UserID` returns HTTP 200 with an empty body** (Content-Length 0) [live].
|
|
339
|
+
|
|
340
|
+
---------------------------------------------------------------------------------------------------
|
|
341
|
+
## 6. Registration, terms of service, attribution
|
|
342
|
+
|
|
343
|
+
- **Registration:** https://apps.bea.gov/API/signup/ (`/api/` redirects there).
|
|
344
|
+
- The form asks for name or organization, email, a CAPTCHA, and a tick for "I agree to the Terms of Service". **A person must complete it**; the assistant must not try.
|
|
345
|
+
- BEA emails a **36-character UserID** and a link; **the key works only after the link is clicked** [guide].
|
|
346
|
+
- Disposable email addresses are refused, and such registrations may be removed without notice [guide].
|
|
347
|
+
- Contact: developers@bea.gov.
|
|
348
|
+
- **Terms of Service** (apps.bea.gov/API/_pdf/bea_api_tos.pdf). **Required attribution** for any service that uses the API, "displayed prominently": **"This product uses the Bureau of Economic Analysis (BEA) Data API but is not endorsed or certified by BEA."**
|
|
349
|
+
- You may name BEA as the source, but not in a way that implies endorsement.
|
|
350
|
+
- You may not modify or misrepresent content and still credit BEA.
|
|
351
|
+
- BEA may limit access, monitor usage, and block users who try to exceed or get around limits, temporarily or permanently.
|
|
352
|
+
- The API is provided "as is"; federal law governs.
|
|
353
|
+
- **Citation format** (bea.gov/help/guidelines-for-citing-bea): `U.S. Bureau of Economic Analysis, "Table 1.1.1. Percent Change From Preceding Period in Real Gross Domestic Product" (accessed <date>).` Include the vintage of the estimate when relevant, e.g. "second estimates for the second quarter of 2012".
|
|
354
|
+
- **Key storage:** keep the key in an environment variable or `.env` (beaapi suggests a `.env` with `beakey=…`). Never log the full URL with the key in it.
|
|
355
|
+
|
|
356
|
+
---------------------------------------------------------------------------------------------------
|
|
357
|
+
## 7. Time periods, revisions, release timing
|
|
358
|
+
|
|
359
|
+
- **TimePeriod formats:**
|
|
360
|
+
- Annual: `YYYY`
|
|
361
|
+
- Quarterly: `YYYYQn` (e.g. `2015Q1`)
|
|
362
|
+
- Monthly: `YYYYMx` per the guide ("x is the month digit"). In practice months are zero-padded, `2024M01`: this is UNVERIFIED, so parse with the regex `^(\d{4})M(\d{1,2})$`.
|
|
363
|
+
- **The Year parameter takes years only.** For Q/M data, ask for the years and you get every quarter or month in them; filter afterwards.
|
|
364
|
+
- **Frequency codes by dataset:** NIPA/NIUD `A`, `Q`, `M`; GDPbyIndustry `A`, `Q`; ITA `A`, `QSA`, `QNSA`; IIP `A`, `QNSA`. Regional chooses frequency through the table: SA* = annual, SQ* = quarterly, CA* = county annual.
|
|
365
|
+
- **Only the latest estimates.** API data update "on the same release schedule as other published sources of BEA data (e.g. Interactive Tables)" [guide]. The Interactive Tables "only display the most recently released data" and do not identify vintage [citing guidelines].
|
|
366
|
+
- **There is no vintage or as-of parameter.**
|
|
367
|
+
- To spot a revision, use Regional `UTCProductionTime` and "Last updated" notes, or APIDatasetMetaData `ReleaseDate`/`NextReleaseDate`.
|
|
368
|
+
- Past vintages: BEA Data Archive https://apps.bea.gov/histdata/ (not through the API). Third-party vintage sources such as ALFRED are UNVERIFIED here.
|
|
369
|
+
- **Release schedule:** https://www.bea.gov/news/schedule. Machine-readable: **https://apps.bea.gov/API/signup/release_dates.json** (keys are release names, each with `release_dates[]` as ISO-8601 UTC strings, e.g. "Gross Domestic Product", "Personal Income and Outlays", "GDP by County and Personal Income by County"; there is also a `file_last_updated` key). An ICS feed is at /news/schedule/ics/online-calendar-subscription.ics.
|
|
370
|
+
- **Upcoming releases (as of today):** GDP advance estimate for 2026Q3 and Personal Income and Outlays for Sept 2026, both 2026-10-29 at 8:30 ET. Releases come out at 8:30 AM ET.
|
|
371
|
+
- **Annual cycles:** FixedAssets, late August to early October. IntlServTrade, July. IntlServSTA, October.
|
|
372
|
+
|
|
373
|
+
---------------------------------------------------------------------------------------------------
|
|
374
|
+
## 8. Common table codes
|
|
375
|
+
|
|
376
|
+
**NIPA TableName** (titles checked against TablesRegister.txt, apps.bea.gov/national/Release/TXT/TablesRegister.txt, CSV `TableId,TableTitle`, 318 tables including U*, GFS*, OECD*, Rf*). Frequencies follow BEA convention: Q tables also have A, and monthly tables are named. Confirm with GetParameterValues.
|
|
377
|
+
|
|
378
|
+
| TableName | title |
|
|
379
|
+
|---|---|
|
|
380
|
+
| T10101 | 1.1.1 Percent Change From Preceding Period in Real GDP (line 1 = GDP, series A191RL) |
|
|
381
|
+
| T10102 | 1.1.2 Contributions to Percent Change in Real GDP |
|
|
382
|
+
| T10103 | 1.1.3 Real GDP, Quantity Indexes |
|
|
383
|
+
| T10104 | 1.1.4 Price Indexes for GDP |
|
|
384
|
+
| T10105 | 1.1.5 Gross Domestic Product (nominal) |
|
|
385
|
+
| T10106 | 1.1.6 Real GDP, Chained Dollars |
|
|
386
|
+
| T10107 | 1.1.7 Percent Change From Preceding Period in Prices for GDP |
|
|
387
|
+
| T10109 | 1.1.9 Implicit Price Deflators for GDP |
|
|
388
|
+
| T10111 | 1.1.11 Real GDP: Percent Change From Quarter One Year Ago |
|
|
389
|
+
| T10204 / T10205 / T10206 | 1.2.x GDP by Major Type of Product (prices / nominal / real) |
|
|
390
|
+
| T10501–T10506 | 1.5.x GDP, Expanded Detail |
|
|
391
|
+
| T10604 | 1.6.4 Price Indexes for Gross Domestic Purchases |
|
|
392
|
+
| T11000 | 1.10 Gross Domestic Income by Type of Income |
|
|
393
|
+
| T11200 | 1.12 National Income by Type of Income |
|
|
394
|
+
| T11706 | 1.17.6 Real GDP, Real GDI, and Other Major NIPA Aggregates, Chained Dollars |
|
|
395
|
+
| T20100 | 2.1 Personal Income and Its Disposition |
|
|
396
|
+
| T20301 / T20304 / T20305 / T20306 | 2.3.x PCE by Major Type of Product: real % change / price indexes / nominal / real |
|
|
397
|
+
| T20600 | 2.6 Personal Income and Its Disposition, Monthly |
|
|
398
|
+
| T20801–T20807 | 2.8.x PCE by Major Type of Product, Monthly. T20804 = **PCE price indexes, monthly** (PCE and core PCE); T20805 = nominal; T20806 = real; T20807 = % change in prices. |
|
|
399
|
+
| T30100 / T30200 / T30300 | 3.1 / 3.2 / 3.3 Government (total / federal / state and local) current receipts and expenditures |
|
|
400
|
+
| T40100 | 4.1 Foreign Transactions in the NIPAs |
|
|
401
|
+
| T50100 | 5.1 Saving and Investment by Sector |
|
|
402
|
+
| T61600D | 6.16D Corporate Profits by Industry |
|
|
403
|
+
| T70100 | 7.1 Selected Per Capita Product and Income Series |
|
|
404
|
+
| U20304/U20305/U20306, U20404/U20405/U20406 | NIUnderlyingDetail PCE detail: by type and function / by type of product |
|
|
405
|
+
| U70205S | Auto and Truck Unit Sales, Production, Inventories, Expenditures, and Price |
|
|
406
|
+
| U90100 | Reconciliation of Percent Change in the CPI with Percent Change in the PCE Price Index |
|
|
407
|
+
|
|
408
|
+
- Line numbers within a table are not fixed across comprehensive revisions. Pick series by `SeriesCode` + `LineDescription`, not by LineNumber alone.
|
|
409
|
+
- Discontinued 2025-09-25: T20700A (2.7A), T31400 (3.14), and the 6.xA/B/C historical industry tables. T6xxxxD tables are still listed.
|
|
410
|
+
|
|
411
|
+
**Regional TableName** (App. N list). Inside a table, LineCode picks the statistic; `Code` = `TABLE-LINE`.
|
|
412
|
+
|
|
413
|
+
| TableName | content | LineCode convention |
|
|
414
|
+
|---|---|---|
|
|
415
|
+
| SAINC1 / SQINC1 / CAINC1 | personal income summary: state annual 1929→, state quarterly 1948→, county 1969→ | 1 = personal income (thousands of $ for county, millions for state), 2 = population, 3 = per-capita PI ($) [guide] |
|
|
416
|
+
| SAINC4 / SQINC4 / CAINC4 | personal income (and employment) by major component | 10 = personal income, 20 = population, 30 = per-capita PI (the guide's examples use CAINC4 lines 10 and 30); other lines are components (UNVERIFIED) |
|
|
417
|
+
| SAINC5N / CAINC5N, SAINC6N / CAINC6N, SAINC7N | earnings / compensation / wages by NAICS industry | industry line codes; list them with GetParameterValuesFiltered |
|
|
418
|
+
| SAINC30 / CAINC30 | economic profile | see the cuts in §2 |
|
|
419
|
+
| SAINC35, SAINC40, SAINC50, SAINC51 | transfers, property income, taxes, disposable PI | – |
|
|
420
|
+
| SASUMMARY | state annual income and product summary (1998→) | – |
|
|
421
|
+
| SAGDP1–SAGDP11 (also written SAGDP2N, SAGDP9N…) | annual state GDP: 2 = current $ by industry, 3 = taxes less subsidies, 4 = compensation, 8 = quantity index, 9 = real (chained) GDP, 11 = contributions | industry lines. Line 1 = all-industry total (verified in the SAGDP9 bulk file: line 1 "All industry total", line 2 "Private industries"). The guide's SAGDP9N "Real GDP" example uses LineCode=2. |
|
|
422
|
+
| SQGDP1, SQGDP2, SQGDP8, SQGDP9, SQGDP11 | quarterly state GDP (2005→) | same as SAGDP |
|
|
423
|
+
| CAGDP1, CAGDP2, CAGDP8, CAGDP9, CAGDP11 | county GDP (2001→; MSA rows dropped Feb 2026) | industry lines |
|
|
424
|
+
| SARPP / MARPP / PARPP | regional price parities: state / MSA / portion (2008→) | e.g. 1 = all items RPP (UNVERIFIED) |
|
|
425
|
+
| SAPCE1–SAPCE4 | PCE by state (1997→) | – |
|
|
426
|
+
| SAACArts* / SAAC* | arts and culture satellite account by state (2001→); the program is "no longer regularly produced" (2026-02-10) | – |
|
|
427
|
+
| TASUMMARY(1), TASUMMARY2; PRGDP*-* | U.S. territories; Puerto Rico GDP (GeoFips=72000) | – |
|
|
428
|
+
|
|
429
|
+
**Table-name inconsistency:** the 2026 App. N list writes `SAGDP2`, `SAGDP9`, `TASUMMARY`, but its own example and RegionalApi.pdf use `SAGDP9N`/`SAGDP2N`, and the guide's GetParameterValues sample shows `TASUMMARY1`. **Always resolve names with `GetParameterValues(DatasetName=Regional, ParameterName=TableName)`** before calling GetData.
|
|
430
|
+
|
|
431
|
+
---------------------------------------------------------------------------------------------------
|
|
432
|
+
## 9. Implementation checklist
|
|
433
|
+
1. Read the key from the environment, check it is 36 characters, and redact it in logs.
|
|
434
|
+
2. Use metadata calls (cached) to check TableName, LineCode, Frequency and Year before calling GetData.
|
|
435
|
+
3. Request `ResultFormat=JSON`. Parse defensively:
|
|
436
|
+
- unwrap a list-valued `Results`
|
|
437
|
+
- look for `Error` at both `BEAAPI` and `Results`
|
|
438
|
+
- handle `BEAAPI.Data` (IIP) and single-object `Data`
|
|
439
|
+
- treat an empty body or HTML as a server failure
|
|
440
|
+
4. Raise errors with APIErrorCode, description and ErrorDetail. Do not retry on codes 1, 3, 4, 40 or 2xx. On HTTP 429 or code 7, sleep for `Retry-After` (or 60 s), and if the block continues assume up to 1 hour.
|
|
441
|
+
5. Throttle on the client to at most about 90 requests/min, a running byte budget under 100 MB/min, and an error budget under 30/min, all single-threaded.
|
|
442
|
+
6. Parse values: strip commas, map suppression codes to NaN while keeping the raw flag, apply UNIT_MULT, parse TimePeriod (`Y`, `YQn`, `YMmm`), and join Notes through NoteRef.
|
|
443
|
+
7. Show the ToS attribution sentence in outputs and record `UTCProductionTime` or the date retrieved as the vintage.
|
|
444
|
+
|
|
445
|
+
---------------------------------------------------------------------------------------------------
|
|
446
|
+
## URLs opened
|
|
447
|
+
- https://apps.bea.gov/api/_pdf/bea_web_service_api_user_guide.pdf (pypdf, 69 pp.)
|
|
448
|
+
- https://apps.bea.gov/API/signup/ and https://apps.bea.gov/api/ (redirect to signup), https://apps.bea.gov/developers/ (redirect)
|
|
449
|
+
- https://apps.bea.gov/API/_pdf/bea_api_tos.pdf
|
|
450
|
+
- https://apps.bea.gov/API/swagger/index.htm and https://apps.bea.gov/api/swagger/swagger.json
|
|
451
|
+
- https://apps.bea.gov/API/docs/index.htm; https://apps.bea.gov/api/bea_web_service_api_user_guide.htm (now 404)
|
|
452
|
+
- https://web.archive.org/web/20240316125212/https://apps.bea.gov/API/bea_web_service_api_user_guide.htm
|
|
453
|
+
- https://apps.bea.gov/api/data?… (invalid-key test calls, 7 requests)
|
|
454
|
+
- https://apps.bea.gov/national/Release/TXT/TablesRegister.txt
|
|
455
|
+
- https://apps.bea.gov/regional/pdf/RegionalApi.pdf; https://apps.bea.gov/regional/definitions/
|
|
456
|
+
- https://www.bea.gov/data/discontinued-or-delayed-statistics; https://www.bea.gov/itable/discontinued-data-tables
|
|
457
|
+
- https://www.bea.gov/help/guidelines-for-citing-bea; https://www.bea.gov/resources/for-developers; https://apps.bea.gov/developers/r-index.htm
|
|
458
|
+
- https://www.bea.gov/news/schedule; https://apps.bea.gov/API/signup/release_dates.json; https://apps.bea.gov/histdata/
|
|
459
|
+
- https://api.github.com/orgs/us-bea/repos; github.com/us-bea/beaapi (README.md, CHANGELOG.md, beaapi/{__init__, api_request, response_to_dict, response_to_table, throttling_caller, get_data, get_row_data_value, beaapi_error, update_metadata}.py, docs/example_tables.ipynb)
|
|
460
|
+
- https://raw.githubusercontent.com/us-bea/bea_geo_aggregator/HEAD/README.md
|
|
461
|
+
- https://reaproject.org/united-states-sub/analysis/personal-income-ca05n/ (no symbol definitions found)
|