API documentation

exception beaapi.BEAAPIError(message)

Parent class for errors generated by the API (either invalid query or a problem in processing it) or process the response.

Parameters:

message (str) – Error message

exception beaapi.BEAAPIFailure(message)

Custom error class for when there is an error in processing the query (e.g., db time-out). The query could be valid.

Parameters:

message (str) – Error message

exception beaapi.BEAAPIPkgException(message, response_size)

Error in package in processing the reponse to an API request

Parameters:

  • message (str) – Error message

  • response_size (int) – Query response size (int)

exception beaapi.BEAAPIResponseError(message, response_size)

Custom error for when the query results in an error from the API. We strip outer whitespace from the message. It may contain a string as the APIErrorCode attribute. If multiple errors are returned, the message is generic and check the messages attribute.

Parameters:

  • message (str) – Error message

  • response_size (int) – Query response size (int)

beaapi.api_request(beaspec, as_string=False, as_dict=False, as_table=True, is_meta=False, throttle=True, **kwargs)

This is a low-level function (and subject to change). Please use the higher-level get_*() functions!

Pass dict of user specifications (including API key) to return data from BEA API.

Parameters:

  • beaspec (Dict[str, str]) – A dict of user specifications (required). See the example below for general idea. See BEA API documentation or use metadata methods for complete lists of parameters.

  • as_string (bool) – Return result body as a string. Supersedes as_dict and as_table optional parameters.

  • as_dict (bool) – Return response as json.loads('[response content]') dict. Supersedes as_table optional parameter.

  • as_table (bool) – Return response as pd.DataFrame with pd.DataFrame(...).attrs metadata

  • is_meta (bool) – Is this a metadata request from get_data_set_list(), get_parameter_list(), or get_parameter_values()? If so, data will be returned with only partial transformation

  • throttle (bool) –

  • kwargs (Dict[str, Any]) –

Returns:

The response from a query of BEA’s API. If as_string, as_dict, and as_table are all False, returns http.client.HTTPResponse. If as_string=True, returns string of response content. If as_dict=True, returns slightly transformed dict results of json.loads() of response content. If as_table, An object of class pd.DataFrame containing data from beaapi.api_request(...) with metadata stored as an attribute in pd.DataFrame(...).attrs.

Return type:

http.client.HTTPResponse, str, dict, pd.DataFrame

Examples

>>> import beaapi
>>> beaspecs = {
>>>     'UserID': beakey ,
>>>     'Method': 'GetData',
>>>     'datasetname': 'NIPA',
>>>     'TableName': 'T20305',
>>>     'Frequency': 'Q',
>>>     'Year': 'X',
>>> }
>>> beaPayload = beaapi.api_request(beaspecs)
beaapi.get_data(userid, datasetname, do_checks=False, throttle=True, **kwargs)

Returns a data table.

Parameters:

  • userid (str) – Your API key

  • datasetname (str) – Name of BEA dataset

  • **kwargs – Other named parameters as key-value pairs

  • do_checks (bool) –

  • throttle (bool) –

Returns:

A table with data. The ‘DataValue’ col will try to be converted to a numeric using pd.to_numeric(). ‘’, ‘(NA)’, and ‘(NM)’/’(D)’ (when accompanied by the same in the NoteRef col) will be converted to np.nan.

Attribute (.attr) dictionary keys:

  • params (dict) – The user-defined query parameters.

  • response_size (int) – The length of the API response.

  • index_cols (list[str]) – The columns that uniquely define the key (depending on query, might include unnecessary cols). There may be other columns that 1:1 map to some of the index key (e.g. “rowCode” and “rowDescription”). Also, for ITA, IIP, IntlServTrade, ‘TimeSeriesId’ unique identifies the time_invariant_keys. For IIP [‘TimePeriod’] = [‘Frequency’, ‘Year’].

  • time_invariant_keys, time_invariant_vars, time_variant_keys, time_variant_vars, time_variant_only_vars (list[str]) – These partition the columns into whether they are keys or other variables and how they interact with the time variable

  • detail (dict) – Has extended info depending on the dataset. It contains a ‘Dimensions’ table with columns ‘Name’, ‘DataType’, ‘IsValue’ describing the columns of the main data. It may contain a ‘Notes’ table with extra info referenced from the main data.

Return type:

pd.DataFrame

Examples

>>> import beaapi
>>> beaapi.get_dataset('yourAPIkey', 'NIPA', TableName='T20305', Frequency='Q',
>>>                    Year='X')
beaapi.get_data_set_list(userid, throttle=True)

Returns a table of all datasets.

Parameters:

  • userid (str) – Your API key

  • throttle (bool) –

Returns:

A DataFrame with variables ‘DatasetName’ and ‘DatasetDescription’.

Attribute (.attr) dictionary keys:

  • params (dict) – The user-defined query parameters.

  • response_size (int) – The length of the API response.

Return type:

pd.DataFrame

Examples

>>> import beaapi
>>> beaapi.get_data_set_list('yourAPIkey')
beaapi.get_parameter_list(userid, datasetname, throttle=True)

Gives list of parameters possible for a given dataset.

Parameters:

  • userid (str) – Your API key

  • datasetname (str) – Name of BEA dataset

  • throttle (bool) –

Returns:

A DataFrame with the variables: ‘ParameterName’, ‘ParameterDataType’, ‘ParameterDescription’, ‘ParameterIsRequiredFlag’, ‘ParameterDefaultValue’, ‘MultipleAcceptedFlag’, ‘AllValue’.

Attribute (.attr) dictionary keys:

  • params (dict) – The user-defined query parameters.

  • response_size (int) – The length of the API response.

Return type:

pd.DataFrame

Examples

>>> import beaapi
>>> beaapi.get_parameter_list('yourAPIkey', 'RegionalData')
beaapi.get_parameter_values(userid, datasetname, parametername, throttle=True)

Gives table of parameter values possible for a given dataset’s given parametername.

Parameters:

  • userid (str) – Your API key

  • datasetname (str) – Name of BEA dataset

  • parametername (str) – Name of BEA dataset’s parameter

  • throttle (bool) –

Returns:

A DataFrame with the results. Typically there are two columns with possible values and descriptions, though the exactly names vary by dataset and parametername. When querying for ‘Year’ in NIPA, NIUnderlyingDetail, or FixedAssets the columns will be [‘TableName’, ‘FirstAnnualYear’, ‘LastAnnualYear’, ‘FirstQuarterlyYear’, ‘LastQuarterlyYear’, ‘FirstMonthlyYear’, ‘LastMonthlyYear’].

Attribute (.attr) dictionary keys:

  • params (dict) – The user-defined query parameters.

  • response_size (int) – The length of the API response.

Return type:

pd.DataFrame

Examples

>>> import beaapi
>>> beaapi.get_parameter_values('yourAPIkey', 'RegionalData', 'keycode')
beaapi.get_parameter_values_filtered(userid, datasetname, targetparameter, throttle=True, **kwargs)

Gives table of parameter values possible for a given dataset’s given parameters.

Parameters:

  • userid (str) – Your API key

  • datasetname (str) – Name of BEA dataset. Currently not implimented for ‘NIPA’, ‘NIUnderlyingDetail’,’MNE’, ‘FixedAssets’, and ‘APIDatasetMetaData’.

  • targetparameter (str) – Name of BEA dataset’s parameter

  • **kwargs – Other parameter-value pairs.

  • throttle (bool) –

Returns:

A DataFrame with variables ‘Key’ and ‘Desc’ showing the possible options.

Attribute (.attr) dictionary keys:

  • params (dict) – The user-defined query parameters.

  • response_size (int) – The length of the API response.

Return type:

pd.DataFrame

Examples

>>> import beaapi
>>> beaapi.get_parameter_values_filtered(beakey, 'Regional', 'Year',
>>>                                      TableName='CAINC5N', GeoFips='01001')
beaapi.search_metadata(search_term, userid=None, metadata_store='beaapi_data', fuzzy=False, throttle=True)

Searches metadata for datasets. Currently works with datasets ‘nipa’, ‘niunderlyingdetail’, and ‘fixedassets’.

If userid is provided, an API request is made to see to see if new metadata is available, and if so update_metadata() will be called.

Searching without the userid is not advised. If you would like to retain metadata for posterity, please copy it from the “beaapi_data” area of your directory to elsewhere on your machine; this will help prevent accidental overwrite, and will not interfere with the “freshness” of your searches.

Parameters:

  • search_term (str) – String to search for

  • userid (Optional[str]) – Your API key. Optional if metadata already stored locally.

  • metadata_store (str) – Directory path of where to store the files. Defaults to subdirectory of current working directory.

  • fuzzy (bool) – Try to use fuzzy string matching via the fuzzywuzzy module (must be installed).

  • throttle (bool) –

Returns:

A DataFrame with relevant results.

Attribute (.attr) dictionary keys:

  • response_size (int) – The length of the API response (0 if none).

Return type:

pd.DataFrame

Examples

>>> import beaapi
>>> beaapi.search_metadata('Gross Domestic', 'yourAPIkey')
beaapi.to_wide_vars_in_cols(bea_tbl)

Returns a wide-format data frame with variables as columns (and time dimension as rows). This is the typical format for DataFrames in analysis. Utilizes the column info in bea_tbl.attrs.

Parameters:

bea_tbl – Long-format table (e.g., from the API)

Returns:

A table in a wide format.

Return type:

pd.DataFrame

Examples

>>> import beaapi
>>> tbl = beaapi.get_dataset(...)
>>> wide_tbl = beaapi.to_wide_vars_in_cols(tbl)
beaapi.to_wide_vars_in_rows(bea_tbl)

Returns a wide-format data frame with variables as rows (and time dimension as columns). This is the way iTables presents data. Utilizes the column info in bea_tbl.attrs.

Parameters:

bea_tbl – Long-format table (e.g., from the API)

Returns:

A table in a wide format.

Return type:

pd.DataFrame

Examples

>>> import beaapi
>>> tbl = beaapi.get_dataset(...)
>>> wide_tbl = beaapi.to_wide_vars_in_rows(tbl)
beaapi.update_metadata(userid, dataset_list=None, metadata_store='beaapi_data', throttle=True)

Updates local store of metadata. Currently only for datasets ‘nipa’, ‘niunderlyingdetail’, and ‘fixedassets’.

Parameters:

  • userid (str) – Your API key.

  • dataset_list (Optional[list]) – list of datasets to update. None will update all known datasets.

  • metadata_store (str) – Directory path of where to store the files. Defaults to subdirectory of current working directory.

  • throttle (bool) –

Returns:

The response size from the API query.

Return type:

int

Examples

>>> import beaapi
>>> beaapi.update_metadata('yourAPIkey')

Constants

beaapi.MAX_DATA_PER_MINUTE = 102400000

Max lenght of API responses per minute before throttling happens

beaapi.MAX_REQUESTS_PER_MINUTE = 100

Max number of API requests per minute before throttling happens

beaapi.MAX_ERRORS_PER_MINUTE = 30

Max number of API errors per minute before throttling happens

beaapi.BACKOFF_SECS = 3600

Max number of API requests per minute before throttling happens