Edit on GitHub

BeaData.jl

Installation

At the Julia REPL:

    (@v1.x) pkg> add BeaData

Preliminaries

A valid User ID key is required to use the BEA's API. A User ID can be obtained by registering at the BEA website: https://apps.bea.gov/API/signup/index.cfm.

All metadata and data retrieval functions require your User ID key as a keyword argument. If you plan to use the package frequently, the most convenient option is store your User ID key in a file named .beadatarc in your home directory. The package will look for this file on startup and will assign the key to the global variable USER_ID if it is present.

Supported Datasets

This package currently only works with the following BEA datasets (descriptions are taken from the BEA website):

  • NIPA: National Income and Product Accounts, which "provide a comprehensive picture of the U.S. economy and feature many macroeconomic statistics."
  • NIUnderlyingDetail: "[D]etailed estimates of underlying NIPA series that appear regularly in the national income and product account (NIPA) tables[.]"
  • FixedAssets: "[S]tatistics on both fixed assets, which are used continuously in processes of production for an extended period of time, and consumer durables, which are generally defined as tangible products that can be stored or inventoried and that have an average life of at least three years."

API Request Limits

The BEA imposes the following limits on calls to the API:

  • a maximum of 100 requests per minute, and/or
  • a maximum of 100 MB retrieved per minute (100 MB), and/or
  • a maximum of 30 errors per minute.

If you exceed these limits you will be blocked from accessing the API for 1 hour. This package does not provide any warning if you're approaching these limits; it is up to the user to monitor their usage.

Retrieving a Table

BeaData.bea_table — Function
bea_table(dataset::String, TableName::String, frequency::String,
    startyear::Int, endyear::Int; user_id = USER_ID) -> BeaTable

Return a BeaTable with data and metadata for TableName. Pass integer value 0 for both startyear and endyear to retrieve all available years for the table. The data values are returned in a DataFrame accessed through the data_values field of the BeaTable struct.

The TableName argument refers to the API TableName parameter value for the requested table. These can be found using the bea_parametervalues method.

Example: to get Table 1.1.6 in the NIPA dataset, quarterly, from 2015 to 2018.

# User ID stored in ~/.beadatarc
julia> nipa116 = bea_table("NIPA", "T10106", "Q", 2015, 2018)
BEA Table
Dataset:   NIPA
Table No.: 1.1.6
Title:     Real Gross Domestic Product, Chained Dollars
Metric:    Chained Dollars
Units:     Billions of chained (2012) dollars
Frequency: Q
Dates:     2015 - 2018
Revised:   August 29, 2019
source
BeaData.BeaTable — Type
struct BeaTable

A BEA table with data and metadata returned from a bea_table call.

Fields

  • dataset: dataset the table was retrieved from
  • table_number: the non-API table number
  • table_description: description of the data contained in the table
  • metric: measurement metric for the data, e.g. index, dollars, etc.
  • units: billions, millions, etc.
  • line_descriptions: DataFrame containing line number descriptions
  • table_notes: DataFrame containing any notes for the table
  • frequency: (M)onthly, (Q)uarterly, or (A)nnual
  • data_startyear: first year of data returned (may differ from what was requested)
  • data_endyear: last year of data returned (may differ from what was requested)
  • api_tablename: TableName parameter value for the table
  • last_revised: date the table was last revised
  • data_values: DataFrame containing the table data values
source

Metadata Methods

BeaData.bea_datasets — Function
bea_datasets(;user_id::String = USER_ID) -> DataFrame

Return a DataFrame of names and descriptions for datasets accessible through the BEA data API.

Example:

# User ID stored in ~/.beadatarc
julia> bea_datsets();

julia> show(ans[1:3, :])
3×2 DataFrames.DataFrame
│ Row │ DatasetName        │ Description                          │
│     │ String             │ String                               │
├─────┼────────────────────┼──────────────────────────────────────┤
│ 1   │ NIPA               │ Standard NIPA tables                 │
│ 2   │ NIUnderlyingDetail │ Standard NI underlying detail tables │
│ 3   │ MNE                │ Multinational Enterprises            │
source
BeaData.bea_parameterlist — Function
bea_parameterlist(dataset::String; user_id = USER_ID) -> DataFrame

Return a DataFrame of parameter names and attributes for dataset.

Example:

# User ID stored in ~/.beadatarc
julia> bea_parameterlist("NIPA")
5×3 DataFrames.DataFrame. Omitted printing of 1 columns
│ Row │ ParameterName │ ParameterDescription                                           │
│     │ String        │ String                                                         │
├─────┼───────────────┼────────────────────────────────────────────────────────────────┤
│ 1   │ Frequency     │ A - Annual, Q-Quarterly, M-Monthly                             │
│ 2   │ ShowMillions  │ A flag indicating that million-dollar data should be returned. │
│ 3   │ TableID       │ The standard NIPA table identifier                             │
│ 4   │ TableName     │ The new NIPA table identifier                                  │
│ 5   │ Year          │ List of year(s) of data to retrieve (X for All)                │
source
BeaData.bea_parametervalues — Function
bea_parametervalues(dataset::String, param_name:: String;
    user_id = USER_ID) -> DataFrame

Return a DataFrame of permissible values for param_name, with descriptions.

Example:

# User ID stored in ~/.beadatarc
julia> bea_parametervalues("NIPA", "TableName");

julia> show(ans[1:3, :])
3×2 DataFrame
│ Row │ Value  │ Description                                                                              │
│     │ String │ String                                                                                   │
├─────┼────────┼──────────────────────────────────────────────────────────────────────────────────────────┤
│ 1   │ T10101 │ Table 1.1.1. Percent Change From Preceding Period in Real Gross Domestic Product (A) (Q) │
│ 2   │ T10102 │ Table 1.1.2. Contributions to Percent Change in Real Gross Domestic Product (A) (Q)      │
│ 3   │ T10103 │ Table 1.1.3. Real Gross Domestic Product, Quantity Indexes (A) (Q)                       │
source