[API] bea.R

API & Databases R Courses

Access Bureau of Economic Analysis’ statistics through the bea.R API.

Thierry Warin https://warin.ca/aboutme.html (HEC Montréal and CIRANO (Canada))https://www.hec.ca/en/profs/thierry.warin.html
06-04-2020

Database description

The Bureau of Economic Analysis (BEA) publishes economic statistics in a variety of formats. The bea.R package includes methods for retrieving a subset of BEA statistical data, and meta-data that describes it.

BEA : https://www.bea.gov/data

API Key

You must first register for an API key from BEA by providing your name and email address. The key will be emailed to you.

Once you have received your BEA API key, save it to a variable to make it easier to use later:

beaKey   <- 'YOUR 36-DIGIT API KEY'

Functions

This package gives access to all indicators provided by the UN Comtrade database. The functions listed below allow you to search and download specific data from the UN Comtrade database.

Each of these functions are detailed in this course and some examples are provided.

beaSearch()

This method allows you to search for BEA data by keyword. For example, to find all datasets in which the term “personal consumption” appears, use the following code:

library(bea.R)

beaSearch('personal consumption', beaKey)

Please note that that beaSearch currently searches only national and regional data.

You may also specify “asHtml = TRUE” to view in-browser:

beaSearch('gross domestic', beaKey, asHtml = TRUE)

beaGet()

Once you have identified the TableID number and other information, you can use beaGet to access the data. The following code, for example, returns the NIPA table with 2015 data for TableID no. 66.

beaSpecs <- list(
  'UserID' = beaKey ,
  'Method' = 'GetData',
  'datasetname' = 'NIPA',
  'TableName' = 'T20305',
  'Frequency' = 'Q',
  'Year' = 'X',
  'ResultFormat' = 'json'
)

beaPayload <- beaGet(beaSpecs)

To retrieve a limited selection of multiple years, list all the years you want to retrieve. For example, to retrieve data for 2011-2015, use “Year”=“2011,2012,2013,2014,2015”

The API documentation includes information about the specific parameters required by beaGET.

Setting asWide = FALSE gives results closest to the way they are actually returned by the API (every column is a variable, every row is an observation):

beaLong <- beaGet(beaSpecs, asWide = FALSE) To return in a format in which each column represents a series, set iTableStyle = FALSE.

This returns columns named with a concatenation of the descriptive column values, whereas rows are populated with numeric DataValues for each TimePeriod, and has one column named “TimePeriod” filled with dates.

beaStatTab <- beaGet(beaSpecs, iTableStyle = FALSE) By default, asWide = TRUE and iTableStyle = TRUE, as this format is the most similar to our iTables; the “beaPayload” object in our first beaGet example at the beginning of this section is in the default format.

tl;dr

library(bea.R)

beaSearch('personal consumption', beaKey)

beaSearch('gross domestic', beaKey, asHtml = TRUE)

beaSpecs <- list(
  'UserID' = beaKey ,
  'Method' = 'GetData',
  'datasetname' = 'NIPA',
  'TableName' = 'T20305',
  'Frequency' = 'Q',
  'Year' = 'X',
  'ResultFormat' = 'json'
)

beaPayload <- beaGet(beaSpecs)

Code learned this week

Command Detail
beaSearch() Search for BEA statistics
beaGet() Find data by TableName

References

This course uses the bea.R package documentation


Citation

For attribution, please cite this work as

Warin (2020, June 4). www.warin.ca: [API] bea.R. Retrieved from https://warin.ca/posts/api-bea/

BibTeX citation

@misc{warin2020[api],
  author = {Warin, Thierry},
  title = {www.warin.ca: [API] bea.R},
  url = {https://warin.ca/posts/api-bea/},
  year = {2020}
}