Welcome to the bears library

A Rust wrapper around the Bureau of Economic Analysis (BEA) REST API.

Project Goals

This library is similar to the beaapi Python package. Our aim is to provide the same convenience and accessibility to economic data for users of the Rust Programming Language.

A major goal of this project is to improve the discoverability of BEA data by leveraging the strong typing and exhaustive enum matching in the Rust language. Dates and times map to the jiff::civil::Date type. Dollar values will consider the unit multiplier when mapping to a currency type, so you can never confuse units in millions with thousands or single dollars.

Request parameter values with reasonable scopes map to enums, such as Dataset, ParameterName, State, and DirectionOfInvestment. Larger scopes, such as Country and Region codes, Geofips and LineCodes read from cached responses of the corresponding GetParameterValues method BEA API call.

Improving Discoverability

Practitioners of the dismal science should be able to enjoy nice things. If the parameter values submitted by the user would result in an error, or a "dataset not implemented" response, this will trigger a warning for the user. The active_subset method filters out invalid requests, so the user can quickly obtain the complete range of valid requests.

The bears library determines valid requests by iterating through the full range of possible requests, given the valid ranges of parameter values for the dataset, and recording the result of the request. By consuming structured logs, the library constructs a history of successes and failures, used to inform the active_subset method.

Features

• Async load and download API
• Datasets can generate iterators of valid requests options
  • The full request queue will download the complete dataset
  • Filter request queues to target areas of interest

Roadmap

This project is currently under active development. Initial goals are to provide feature parity with the Python package. In the future, we hope to provide integration with the polars library to facilitate data analysis for users.

Dataset Coverage

Usage

Requires a BEA issued API key.

The bears library reads the user API key from the API_KEY environmental variable set in the project .env file:

API_KEY = "your_BEA_issued_key"
BEA_DATA = "path_to_download_dir"

You can also specify the directory to store downloaded data in the BEA_DATA variable.

The current status of the library is immature, or not yet ready for use. Feel free to experiment and offer feedback, we would appreciate hearing from you.