fredapi

Economic data series often undergo revisions. fredapi leverages ALFRED (Archival Federal Reserve Economic Data) to handle point-in-time data.

Each observation in ALFRED is associated with three dates:

• date: The actual date the value refers to.
• realtime_start: The first date the value was valid.
• realtime_end: The last date the value was valid.

For example, a single GDP value for '2014-01-01' might have multiple entries with different realtime_start and realtime_end values, representing how the data was revised over time.

Install the fredapi package using pip to access Federal Reserve Economic Data (FRED) via Python.

pip install fredapi

To use fredapi, you must first obtain a free API key from the FRED website. You can provide the key to the Fred class in one of three ways:

1. Set the FRED_API_KEY environment variable.
2. Pass the path to a file containing the key using the api_key_file parameter.
3. Pass the key directly using the api_key parameter.

All data returned by fredapi is provided as a pandas Series or DataFrame.

from fredapi import Fred
fred = Fred(api_key='insert api key here')

# Example: Get a series
data = fred.get_series('SP500')

Use get_series_as_of_date(series_id, date_string) to perform point-in-time analysis. This returns a DataFrame containing the observations that were valid on the provided date.

# Returns a DataFrame with columns: date, realtime_start, value
fred.get_series_as_of_date('GDP', '6/1/2014')

Use get_series_latest_release(series_id) to get the most recent version of the data. This is functionally equivalent to calling get_series(series_id).

data = fred.get_series_latest_release('GDP')

Use get_series_first_release(series_id) to get the very first version of each data point, effectively ignoring all subsequent revisions.

# Returns a pandas Series of the original releases
data = fred.get_series_first_release('GDP')

You can search for economic data series programmatically using the search() method for full-text searches, or use specific ID-based searches.

• Full-text search: search(text) returns a DataFrame of results.
• Search by release ID: search_by_release(release_id).
• Search by category ID: search_by_category(category_id, limit=None, order_by=None, sort_order=None).

# Full-text search
fred.search('potential gdp')

# Search by release ID
df1 = fred.search_by_release(11)

# Search by category ID with options
df2 = fred.search_by_category(101, limit=10, order_by='popularity', sort_order='desc')

The search(query) method performs a full-text search and returns a pandas DataFrame containing matching series and their metadata (e.g., id, title, frequency, units).

# Returns a DataFrame of search results
results = fred.search('potential gdp')

fred.search('potential gdp').T

Use get_series(series_id) to retrieve the standard time series for a given ID. This returns the latest available data.

from fredapi import Fred
fred = Fred(api_key='insert api key here')
# Retrieve S&P 500 data
data = fred.get_series('SP500')

To explore the full history of revisions for a series, use these methods:

• get_series_all_releases(series_id): Returns a DataFrame containing all historical versions (vintages) of the data, including date, realtime_start, and value.
• get_series_vintage_dates(series_id): Returns a list of all dates on which data was released.

# Get all historical revisions as a DataFrame
df = fred.get_series_all_releases('GDP')

# Get all release dates
vintage_dates = fred.get_series_vintage_dates('GDP')