| Title: | Bureau of Economic Analysis API |
|---|---|
| Description: | Provides an R interface for the Bureau of Economic Analysis (BEA) API (see <http://www.bea.gov/API/bea_web_service_api_user_guide.htm> for more information) that serves two core purposes - 1. To Extract/Transform/Load data [beaGet()] from the BEA API as R-friendly formats in the user's work space [transformation done by default in beaGet() can be modified using optional parameters; see, too, bea2List(), bea2Tab()]. 2. To enable the search of descriptive meta data [beaSearch()]. Other features of the library exist mainly as intermediate methods or are in early stages of development. Important Note - You must have an API key to use this library. Register for a key at <http://www.bea.gov/API/signup/index.cfm>. As a note regarding the license: Software code created by U.S. Government employees is not subject to copyright in the United States (17 U.S.C. ยง105). The United States/ Department of Commerce reserve all rights to seek and obtain copyright protection in countries other than the United States for Software authored in its entirety by the Department of Commerce. To this end, the Department of Commerce hereby grants to Recipient a royalty-free, nonexclusive license to freely use, copy, distribute, and create derivative works of the Software outside of the United States. The CC0 1.0 Universal License should be taken to apply to this work inside and outside of the United States. |
| Authors: | Andrea Batch [aut, cre], Jeff Chen [ctb], Walt Kampas [ctb] |
| Maintainer: | Andrea Batch <[email protected]> |
| License: | CC0 |
| Version: | 1.1.0 |
| Built: | 2026-05-18 05:54:23 UTC |
| Source: | https://github.com/us-bea/bea.r |
Convert BEA API httr response payload to list
bea2List(beaPayload, isMeta = FALSE)bea2List(beaPayload, isMeta = FALSE)
beaPayload |
An object with httr class 'response' from call to BEA API |
isMeta |
Special parameter meant to interact with metadata functions (default: FALSE) |
An object of class 'list' of several dimensions. View list structure using 'str(yourList)'.
userSpecList <- list('UserID' = Sys.getenv("BEA_API_KEY"), 'Method' = 'GetData', 'datasetname' = 'NIPA', 'Frequency' = 'A', 'TableName' = 'T20405', 'Year' = 'X') resp <- beaGet(userSpecList, asTable = FALSE) BL <- bea2List(resp)userSpecList <- list('UserID' = Sys.getenv("BEA_API_KEY"), 'Method' = 'GetData', 'datasetname' = 'NIPA', 'Frequency' = 'A', 'TableName' = 'T20405', 'Year' = 'X') resp <- beaGet(userSpecList, asTable = FALSE) BL <- bea2List(resp)
Convert BEA API httr response or list payload to data.table. Also, converts LONG data frame (default API format - see bea2List results) to WIDE data (with years as columns) by default
bea2Tab(beaPayload, asWide = TRUE, iTableStyle = TRUE)bea2Tab(beaPayload, asWide = TRUE, iTableStyle = TRUE)
beaPayload |
An object of class 'list' or httr 'response' returned from beaGet() call to BEA API |
asWide |
Return data.table in wide format (default: TRUE) |
iTableStyle |
If "asWide = TRUE", setting "iTableStyle = TRUE" will return data.table in same format as shown on BEA website, with dates and attributes as column headers and series as rows; otherwise, results have series codes as column headers (default: TRUE) |
An object of class 'data.table' containing data from beaGet(...) with custom attributes(BDT)$params.
userSpecList <- list('UserID' = Sys.getenv("BEA_API_KEY"), 'Method' = 'GetData', 'datasetname' = 'NIPA', 'Frequency' = 'A', 'TableName' = 'T20405', 'Year' = 'X') resp <- beaGet(userSpecList) BDT <- bea2Tab(resp)userSpecList <- list('UserID' = Sys.getenv("BEA_API_KEY"), 'Method' = 'GetData', 'datasetname' = 'NIPA', 'Frequency' = 'A', 'TableName' = 'T20405', 'Year' = 'X') resp <- beaGet(userSpecList) BDT <- bea2Tab(resp)
Pass list of user specifications (including API key) to return data from BEA API.
beaGet( beaSpec, asString = FALSE, asList = FALSE, asTable = TRUE, asWide = TRUE, isMeta = FALSE, iTableStyle = TRUE )beaGet( beaSpec, asString = FALSE, asList = FALSE, asTable = TRUE, asWide = TRUE, isMeta = FALSE, iTableStyle = TRUE )
beaSpec |
A list of user specifications (required). In this example, 'GetData' specifies that we want data values (rather than metadata), 'NIPA' specifies the dataset, 'A' specifies that we want annual data, 'TableID' = '68' gets a specific table, and 'X' gets all years. See BEA API documentation or use metadata methods for complete lists of parameters. |
asString |
Return result body as a string (default: FALSE) |
asList |
Return result body as a list (default: FALSE) |
asTable |
Return result body as a data.table (default: TRUE) |
asWide |
Return data.table in wide format (default: TRUE) |
isMeta |
Special parameter meant to interact with metadata functions (default: FALSE) |
iTableStyle |
If "asWide = TRUE", setting "iTableStyle = TRUE" will return data.table in same format as shown on BEA website, with dates and attributes as column headers and series as rows; otherwise, results have series codes as column headers (default: TRUE) |
By default, an object of class 'list' of several dimensions. View list structure using 'str(yourList)'.
userSpecList <- list('UserID' = Sys.getenv("BEA_API_KEY"), 'Method' = 'GetData', 'datasetname' = 'NIPA', 'Frequency' = 'A', 'TableName' = 'T20405', 'Year' = 'X') BDT <- beaGet(userSpecList, asTable = TRUE)userSpecList <- list('UserID' = Sys.getenv("BEA_API_KEY"), 'Method' = 'GetData', 'datasetname' = 'NIPA', 'Frequency' = 'A', 'TableName' = 'T20405', 'Year' = 'X') BDT <- beaGet(userSpecList, asTable = TRUE)
Gives list of parameters possible for a given dataset
beaParams(beaKey, setName)beaParams(beaKey, setName)
beaKey |
Your API key |
setName |
Name of BEA dataset (e.g., 'NIPA') |
A metadata object of class 'list' of several dimensions. View list structure using 'str(yourList)'.
beaParams(Sys.getenv("BEA_API_KEY"), 'NIPA')beaParams(Sys.getenv("BEA_API_KEY"), 'NIPA')
Gives list of values possible for a given dataset's parameters
beaParamVals(beaKey, setName, paramName)beaParamVals(beaKey, setName, paramName)
beaKey |
Your API key |
setName |
Name of BEA dataset (e.g., NIPA) |
paramName |
Name of BEA dataset parameter (e.g., TableName) |
A metadata object of class 'list' of several dimensions. View list structure using 'str(yourList)'.
beaParamVals(Sys.getenv("BEA_API_KEY"), 'NIPA', 'TableName')beaParamVals(Sys.getenv("BEA_API_KEY"), 'NIPA', 'TableName')
Searches indexed dataset table name, label, and series codes. CAUTION: Currently only searches within NATIONAL datasets (NIPA, NIUnderlyingDetail, FixedAssets).
beaSearch(searchTerm, beaKey = NULL, asHtml = FALSE)beaSearch(searchTerm, beaKey = NULL, asHtml = FALSE)
searchTerm |
A word or phrase of class 'character' to be found in BEA datasets |
beaKey |
Character string representation of user API key. Necessary for first time use and updates; recommended for anything beyond one-off searches from the console. |
asHtml |
Option to return results as DT markup, viewable in browser. Allows search WITHIN YOUR ALREADY-FILTERED RESULTS ONLY. Requires package 'DT' to be installed. |
An object of class 'data.table' with information about all indexed sets in which the search term was found.
beaSearch('gross domestic product', beaKey = Sys.getenv("BEA_API_KEY"), asHtml = TRUE)beaSearch('gross domestic product', beaKey = Sys.getenv("BEA_API_KEY"), asHtml = TRUE)
Returns a list of all datasets
beaSets(beaKey)beaSets(beaKey)
beaKey |
Your API key |
A metadata object of class 'list' of several dimensions. View list structure using 'str(yourList)'.
beaSets(Sys.getenv("BEA_API_KEY"))beaSets(Sys.getenv("BEA_API_KEY"))
Download BEA metadata into library/data folder if needed
beaUpdateMetadata(datasetList, beaKey)beaUpdateMetadata(datasetList, beaKey)
datasetList |
list of BEA datasets to update local metadata file for (e.g., list('NIPA', 'FixedAssets')) |
beaKey |
Your API key |
Nothing. This updates local .RData files to be used in beaSearch.
beaUpdateMetadata(list('NIUnderlyingDetail', 'NIPA'), beaKey = Sys.getenv("BEA_API_KEY"))beaUpdateMetadata(list('NIUnderlyingDetail', 'NIPA'), beaKey = Sys.getenv("BEA_API_KEY"))