finagg.bea package

Submodules

finagg.bea.api module

An implementation of the Bureau of Economic Analysis (BEA) API.

The BEA API provides methods for retrieving a subset of economic statistical data as published by the BEA along with metadata that describes that economic statistical data.

A BEA API key is required to use this API. You can register for a BEA API key at the BEA API signup page. You can pass your BEA API key directly to the implemented API getters, or you can set the BEA_API_KEY environment variable to have the BEA API key be passed to the implemented API getters for you.

Alternatively, running finagg bea install (or the broader finagg install) will prompt you where to aquire a BEA API key and will automatically store it in an .env file in your current working directory. The environment variables set in that .env file will be loaded into your shell upon using finagg (whether that be through the Python interface or through the CLI tools).

See the official BEA API user guide for more info on the BEA API.

Note

This was the first API implementation in this project, but has since lost priority in favor of the FRED API as the FRED API provides data that’s found through the BEA API in addition to a plethora of other data. This BEA API implementation is still maintained and supported, but other features such as data installation are not and will never be supported.

class finagg.bea.api.API[source]

Bases: ABC

Interface for BEA Dataset APIs.

name: ClassVar[str]

Request API URL.

abstract classmethod get(*args: Any, **kwargs: Any) → DataFrame[source]

Main dataset API method.

classmethod get_parameter_list(*, api_key: None | str = None) → DataFrame[source]

Return the list of parameters associated with the dataset API.

classmethod get_parameter_values(param: str, /, *, api_key: None | str = None) → DataFrame[source]

Return all possible parameter values associated with the dataset API.

class finagg.bea.api.FixedAssets[source]

Bases: API

US fixed assets (assets for long-term use).

name: ClassVar[str] = 'FixedAssets'

Request API URL.

classmethod get(table_id: str | Sequence[str] = 'ALL', year: int | str | Sequence[int | str] = 'ALL', *, api_key: None | str = None) → DataFrame[source]

Get US fixed assets by asset and year.

Parameters:

  • table_id – IDs associated with assets of concern. Use get_parameter_values() to see possible values.

  • year – Years to return.

Returns:

Dataframe with normalized column names and true dtypes.

class finagg.bea.api.GDPByIndustry[source]

Bases: API

GDP (a single summary statistic) for each industry.

The module variable finagg.bea.api.gdp_by_industry is an instance of this API implementation and is the most popular interface for querying this API.

Data provided by this API is considered coarse/high-level. See InputOutput for more granular/low-level industry data.

Examples

List the GDP by industry API parameters.

>>> finagg.bea.api.gdp_by_industry.get_parameter_list()  
  ParameterName ParameterDataType                               ParameterDescription ... AllValue
0     Frequency            string                            A - Annual, Q-Quarterly ...      ALL
1      Industry            string       List of industries to retrieve (ALL for All) ...      ALL
2       TableID           integer  The unique GDP by Industry table identifier (A... ...      ALL
3          Year           integer  List of year(s) of data to retrieve (ALL for All) ...      ALL

List possible GDP by industry tables we can query.

>>> finagg.bea.api.gdp_by_industry.get_parameter_values("TableID").head(5)  
  Key                                               Desc
0   1                    Value Added by Industry (A) (Q)
1   5  Value added by Industry as a Percentage of Gro...
2   6          Components of Value Added by Industry (A)
3   7  Components of Value Added by Industry as a Per...
4   8  Chain-Type Quantity Indexes for Value Added by...
name: ClassVar[str] = 'GdpByIndustry'

Request API URL.

classmethod get(table_id: str | Sequence[str] = 'ALL', freq: Literal['A', 'Q', 'A,Q'] = 'Q', year: int | str | Sequence[int | str] = 'ALL', industry: str | Sequence[str] = 'ALL', *, api_key: None | str = None) → DataFrame[source]

Get GDP by industry.

Parameters:

  • table_id – IDs associated with GDP value type. Use get_parameter_values() to see possible values. “ALL” indicates retrieve all GDP value measurement type tables.

  • freq – Data frequency to return. “Q” for quarterly, “A” for annually, and “A,Q” for both annually and quarterly.

  • year – Years to return. “ALL” indicates retrieve data for all available years.

  • industry – IDs associated with industries. Use get_parameter_values() to see possible values.

Returns:

Dataframe with GDP by industry, separated by year and/or quarter.

Examples

Get the GDP value added by an industry for a specific year.

>>> finagg.bea.api.gdp_by_industry.get(table_id=1, freq="A", year=2020).head(5)  
   table_id freq  year quarter industry                         industry_description  value
0         1    A  2020    2020       11  Agriculture, forestry, fishing, and hunting  162.2
1         1    A  2020    2020    111CA                                        Farms  120.7
2         1    A  2020    2020    113FF    Forestry, fishing, and related activities   41.5
3         1    A  2020    2020       21                                       Mining  201.1
4         1    A  2020    2020      211                       Oil and gas extraction  110.9
class finagg.bea.api.InputOutput[source]

Bases: API

Specific input-output statistics for each industry.

Data provided by this API is considered granular/low-level. See GDPByIndustry for more coarse/high-level industry data.

Data is provided for different “rows” and “columns” where:

  • a row is an industry and

  • a column is a statistic associated with that industry

Columns are divided by column codes. Each industry of similar type has the same set of column codes that provide input-output statistics for that industry.

name: ClassVar[str] = 'InputOutput'

Request API URL.

classmethod get(table_id: str | Sequence[str] = 'ALL', year: int | str | Sequence[int | str] = 'ALL', *, api_key: None | str = None) → DataFrame[source]

Get input-output statistics by industry.

Parameters:

  • table_id – IDs associated with input-output stats. Use get_parameter_values() to see possible values. “ALL” indicates retrieve all tables for all types of input-output statistics by industry.

  • year – Years to return. “ALL” indicates retrieve data for all available years.

Returns:

Dataframe organized by table row and column codes.

class finagg.bea.api.NIPA[source]

Bases: API

National income and product accounts.

Details high-level US economic details in several metrics.

name: ClassVar[str] = 'NIPA'

Request API URL.

classmethod get(table_id: str | Sequence[str] = 'ALL', freq: Literal['A', 'Q', 'A,Q'] = 'Q', year: int | str | Sequence[int | str] = 'ALL', *, api_key: None | str = None) → DataFrame[source]

Get US income and product accounts by metric.

Parameters:

  • table_id – IDs associated with metric of concern. Use get_parameter_values() to see possible values.

  • freq – Data frequency to return. “Q” for quarterly, “A” for annually.

  • year – Years to return.

Returns:

Dataframe with normalized column names and true dtypes.

finagg.bea.api.fixed_assets

The most popular way for accessing the finagg.bea.api.FixedAssets API implementation.

finagg.bea.api.gdp_by_industry

The most popular way for accessing the finagg.bea.api.GDPByIndustry API implementation.

finagg.bea.api.input_output

The most popular way for accessing the finagg.bea.api.InputOutput API implementation.

finagg.bea.api.nipa

The most popular way for accessing the finagg.bea.api.NIPA API implementation.

finagg.bea.api.url = 'https://apps.bea.gov/api/data'

The BEA API endpoint URL. All API requests are made to this URL.

finagg.bea.api.get_dataset_list(*, api_key: None | str = None) → DataFrame[source]

Return a list of datasets provided by the BEA API.

Returns:

A dataframe describing the datasets available through the BEA API.

Examples

>>> finagg.bea.api.get_dataset_list()  
                DatasetName                    DatasetDescription
0                      NIPA                  Standard NIPA tables
1        NIUnderlyingDetail  Standard NI underlying detail tables
2                       MNE             Multinational Enterprises
3               FixedAssets          Standard Fixed Assets tables
4                       ITA   International Transactions Accounts
5                       IIP     International Investment Position
6               InputOutput                     Input-Output Data
7             IntlServTrade          International Services Trade
8             GDPbyIndustry                       GDP by Industry
9                  Regional                    Regional data sets
10  UnderlyingGDPbyIndustry            Underlying GDP by Industry
11       APIDatasetMetaData     Metadata about other API datasets
exception finagg.bea.api.BEAAPIError(*args, **kwargs)[source]

Bases: RequestException

An error raised in response to BEA API request errors.

finagg.bea.sql module

BEA SQLAlchemy interfaces.

finagg.bea.sql.metadata

The metadata associated with all SQL tables defined in this module.

finagg.bea.sql.fixed_assets

SQL table for storing raw data as returned by finagg.bea.api.fixed_assets (an alias for finagg.bea.api.FixedAssets).

finagg.bea.sql.gdp_by_industry

SQL table for storing raw data as returned by finagg.bea.api.gdp_by_industry (an alias for finagg.bea.api.GDPByIndustry).

finagg.bea.sql.input_output

SQL table for storing raw data as returned by finagg.bea.api.input_output (an alias for finagg.bea.api.InputOutput).

finagg.bea.sql.nipa

SQL table for storing raw data as returned by finagg.bea.api.nipa (an alias for finagg.bea.api.NIPA).

Module contents

BEA top-level interface.