Introduction

The Bureau of Economic Analysis (BEA) publishes economic statistics in a variety of formats. This document describes the BEA Data Retrieval Application Programming Interface (API) – including detailed instructions for retrieving data and meta-data published by BEA using the pyBEA package.

The pyBEA pacakge provides a simple interface to the BEA API and includes methods for retrieving a subset of BEA statistical data, including any meta-data describing it, and loading the results into a Pandas DataFrame object for further analysis.

Data Return Format

The BEA API returns data in one of two formats: JSON or XML (with JSON being the default). Currently the pyBEA package only supports JSON requests.


In [ ]:
import pybea

Meta-Data API Methods

The BEA API contains three methods for retrieving meta-data as follows:

  1. GetDataSetList: retrieves a list of the datasets currently offered.
  2. GetParameterList: retrieves a list of the parameters (required and optional) for a particular dataset.
  3. GetParameterValues: retrieves a list of the valid values for a particular parameter.

Each of these methods has a corresponding function in the pybea package.


In [ ]:
pybea.get_data_set_list?

In [ ]:
pybea.get_parameter_list?

In [ ]:
pybea.get_parameter_values?

Example Usage


In [ ]:
# replace this with your BEA data API key!
USER_ID = ???

In [ ]:
# access the BEA data API...
available_datasets = pybea.get_data_set_list(USER_ID)
available_datasets

In [ ]:
request = pybea.api.DataSetListRequest(USER_ID,
                                       ResultFormat="JSON")
request.data_set_list

In [ ]:
regional_income_params = pybea.get_parameter_list(USER_ID,
                                                  DataSetName='RegionalIncome',
                                                  ResultFormat="XML")
regional_income_params

In [ ]:
request = pybea.api.ParameterListRequest(USER_ID,
                                         DataSetName='RegionalIncome',
                                         ResultFormat="JSON")
request.parameter_list

In [ ]:
regional_income_geofips = pybea.get_parameter_values(USER_ID,
                                                     DataSetName='RegionalIncome',
                                                     ParameterName='GeoFips')
regional_income_geofips

In [ ]:
request = pybea.api.ParameterValuesRequest(USER_ID,
                                           DataSetName='RegionalIncome',
                                           ParameterName='GeoFips')
request.parameter_values

Data Retrieval API Method

The BEA API has one method for retrieving data: GetData. This method has its own function in the pybea package.


In [ ]:
pybea.get_data?

NIPA (National Income and Product Accounts)

This dataset contains data from the National Income and Product Accounts which include measures of the value and composition of U.S.production and the incomes generated in producing it. NIPA data is provided on a table basis; individual tables contain between fewer than 10 to more than 200 distinct data series.

Example Usage

Percent change in Real Gross Domestic Product, Annually and Quarterly for all years.


In [ ]:
data = pybea.get_data(USER_ID,
                      DataSetName='NIPA',
                      TableName='T10101',
                      Frequency=['A', 'Q'],
                      Year='ALL',
                      ResultFormat="XML"
                      )

In [ ]:
data.head()

In [ ]:
data.tail()

Example Usage

Personal Income, Monthly, for 2015 and 2016.


In [ ]:
request = pybea.api.NIPARequest(USER_ID,
                                TableName='T20600',
                                Frequency='M',
                                Year=['2015', '2016'],
                                ResultFormat='JSON')

In [ ]:
request.data.head()

In [ ]:
data.tail()

NIUnderlyingDetail (National Income and Product Accounts)

The DataSetName is NIUnderlyingDetail. This dataset contains underlying detail data from the National Income and Product Accounts which include measures of the value and composition of U.S.production and the incomes generated in producing it. NIPA Underlying Detail data is provided on a table basis; individual tables contain between fewer than 10 to more than 200 distinct data series.

Example Usage

Personal Consumption Expenditures, Current Dollars, Annually, Quarterly and Monthly for all years.


In [ ]:
data = pybea.get_data(USER_ID,
                      DataSetName='NIUnderlyingDetail',
                      TableName='U20305',
                      Frequency=['A', 'Q'],
                      Year='ALL',
                      ResultFormat='XML')

In [ ]:
data.head()

In [ ]:
data.tail()

Example Usage

Auto and Truck Unit Sales, Production, Inventories, Expenditures and Price, Monthly, for 2015 and 2016


In [ ]:
request = pybea.api.NIUnderlyingDetailRequest(USER_ID,
                                              TableName='U70205S',
                                              Frequency='M',
                                              Year=['2015', '2016'],
                                              ResultFormat='JSON')

In [ ]:
request.data.head()

In [ ]:
request.data.tail()

Fixed Assets

The FixedAssets dataset contains data from the standard set of Fixed Assets tables as published online.


In [ ]:
data = pybea.get_data(USER_ID,
                      DataSetName='FixedAssets',
                      TableID='16',
                      Year='2012',
                      ResultFormat='XML')

In [ ]:
data.head()

In [ ]:
data.tail()

ITA (International Transactions)

This dataset contains data on U.S. international transactions. BEA's international transactions (balance of payments) accounts include all transactions between U.S. and foreign residents.

Example Usage

Balance on goods with China for 2011 and 2012.


In [ ]:
data = pybea.get_data(USER_ID,
                      DataSetName='ITA',
                      Indicator='BalGds',
                      AreaOrCountry='China',
                      Frequency='A',
                      Year=['2011', '2012'],
                      ResultFormat='XML')

In [ ]:
data.head()

Example Usage

Net U.S. acquisition of portfolio investment assets (quarterly not seasonally adjusted) for 2013.


In [ ]:
data = pybea.get_data(USER_ID,
                      DataSetName='ITA',
                      Indicator='PfInvAssets',
                      AreaOrCountry='AllCountries',
                      Frequency='QNSA',
                      Year='2013',
                      ResultFormat='XML')

In [ ]:
data.head()

RegionalIncome

Example Usage

Fetch data on personal income for 2012 and 2013 for all counties, in JSON format


In [ ]:
data = pybea.get_data(USER_ID,
                      DataSetName='RegionalIncome',
                      TableName='CA1',
                      LineCode=1,
                      GeoFips='COUNTY',
                      Year=['2012', '2013'],
                      ResultFormat='JSON')

In [ ]:
data.head()

In [ ]:
data.tail()

RegionalProduct

Example Usage

Real GDP for all years for all MSAs, in JSON format


In [ ]:
data = pybea.get_data(USER_ID,
                      DataSetName='RegionalProduct',
                      Component="RGDP_MAN",
                      IndustryId=1,
                      GeoFips="MSA",
                      Year="ALL",
                      ResultFormat='XML')

In [ ]:
data.head()

In [ ]:
data.tail()

Example Usage

GDP for 2012 and 2013 for selected Southeast states, for the Retail Trade industry.


In [ ]:
southeast_states = ["01000", "05000", "12000", "13000", "21000", "22000", 
                    "28000", "37000", "45000", "47000", "51000", "54000"]
data = pybea.get_data(USER_ID,
                      DataSetName='RegionalProduct',
                      Component="GDP_sAN",
                      IndustryId=35,
                      GeoFips=southeast_states,
                      Year=["2013", "2013"],
                      ResultFormat='XML')

In [ ]:
data.head()

In [ ]:
data.tail()

InputOutput

The Input-Output Statistics are contained within a dataset called InputOutput. BEA's industry accounts are used extensively by policymakers and businesses to understand industry interactions, productivity trends, and the changing structure of the U.S. economy. The input-output accounts provide a detailed view of the interrelationships between U.S. producers and users.

Example Usage

Data from The Use of Commodities by Industries, Before Redefinitions (Producer’s Prices) sector level table for years 2010, 2011, and 2012.


In [ ]:
data = pybea.get_data(USER_ID,
                      DataSetName='InputOutput',
                      TableID=2,
                      Year=['2010', '2011', '2012', '2013'],
                      ResultFormat='JSON')

In [ ]:
data.head()

In [ ]:
data.tail()

Example Usage

Data for 2007 from The Make of Commodities by Industries, Before Redefinitions sector and summary level tables.


In [ ]:
data = pybea.get_data(USER_ID,
                      DataSetName='InputOutput',
                      TableID=[46, 47],
                      Year='2007',
                      ResultFormat='JSON')

In [ ]:
data.head()

In [ ]:
data.tail()

In [ ]: