Quick Start Guide¶

Getting Started¶

First, obtain a FRED API key from https://fred.stlouisfed.org/docs/api/api_key.html.

Basic Usage¶

import fedfred as fd

# Initialize the API client
fred = fd.FredAPI(api_key="your_api_key_here")

# Fetch a time series
data = fred.get_series_observations("GDPC1")

# Convert to pandas DataFrame
data.head()

Async Usage¶

FedFred provides native support for asynchronous requests, allowing you to efficiently fetch data in an asynchronous environment.

import asyncio
import fedfred as fd

async def main():
    # Initialize the async API client
    fred = fd.FredAPI(api_key="your_api_key_here").Async

    # Fetch a time series asynchronously
    data = await fred.get_series_observations("GDPC1")

    # Convert to pandas DataFrame
    print(data.head())

    # Fetch multiple series concurrently
    tasks = [
        fred.get_series_observations("UNRATE"),  # Unemployment Rate
        fred.get_series_observations("CPIAUCSL"),  # Consumer Price Index
        fred.get_series_observations("DGS10")  # 10-Year Treasury Rate
    ]
    results = await asyncio.gather(*tasks)

    # Process the results
    for series in results:
        print(series.head())

# Run the async function
asyncio.run(main())

Working with Data¶

FedFred supports both pandas and polars DataFrames:

# Pandas DataFrame (default)
gdp_pandas = fred.get_series_observations("GDPC1")

# Polars DataFrame
gdp_polars = fred.get_series_observations("GDPC1", dataframe_method="polars")

# Customize your query
inflation = fred.get_series_observations(
    "CPIAUCSL",
    observation_start="2020-01-01",
    observation_end="2022-12-31",
    units="pc1",  # Percent change from a year ago
    frequency="q"  # Quarterly frequency
)

Other methods return objects structured by the internal data classes:

# Get category tags
tags = fred.get_category_tags(category_id=125)

# tags is a List[Tag] object
for tag in tags:
    print(tag.name)

Searching for Series¶

Find series by searching with keywords:

# Search for unemployment series
unemployment_series = fred.get_series_search("unemployment rate", limit=5)

# Get series by category
category_series = fred.get_category_series(category_id=32991)  # GDP category

# Find series by tag
inflation_series = fred.get_tags_series(tag_names="inflation")

Categories and Tags¶

Browse and explore the FRED data hierarchy:

# Get top-level categories
categories = fred.get_category_children(category_id=0)

# Get child categories for a specific category
gdp_categories = fred.get_category_children(category_id=32991)  # GDP category

# Get tags for a series
gdp_tags = fred.get_series_tags("GDPC1")

Caching and Rate Limits¶

Enable caching to improve performance and manage API rate limits:

# Initialize client with caching enabled
fred = fd.FredAPI(
    api_key="your_api_key_here",
    cache_mode=True
)

# The library automatically handles rate limiting, but caching helps
# reduce the number of API calls for repeated queries

Geographic Data with FredMapsAPI¶

Access geographic economic data using the FredMapsAPI:

# Initialize the maps API client
fred_maps = fd.FredMapsAPI(api_key="your_api_key_here")

# Get regional data
unemployment_by_state = fred_maps.get_regional_data(
    series_group="unemployment",
    region_type="state",
    date="2023-01-01",
    season="nsa",  # Not seasonally adjusted
    units="percent"
)

# Response is already structured as a GeoDataFrame
print(unemployment_by_state)

Common Economic Indicators¶

Quick access to key economic indicators:

# Real GDP (quarterly, seasonally adjusted)
gdp = fred.get_series_observations("GDPC1")

# Unemployment Rate (monthly, seasonally adjusted)
unemployment = fred.get_series_observations("UNRATE")

# Consumer Price Index (monthly, seasonally adjusted)
cpi = fred.get_series_observations("CPIAUCSL")

# Federal Funds Effective Rate (daily)
fed_funds = fred.get_series_observations("DFF")

# 10-Year Treasury Constant Maturity Rate (daily)
treasury_10y = fred.get_series_observations("DGS10")