Quick Start Guide#

Get started with FedFred, a modern Python client for the FRED® API. This guide shows you how to install, initialize, fetch time series data, handle async operations, and work with DataFrame and geographic data.

—

Getting Started#

First, obtain a free FRED API key from the official website: FRED API Key Request

Install FedFred using pip or conda (see Installing FedFred for more options).

—

import fedfred as fd

fred = fd.FredAPI(api_key="your_api_key_here")

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

Default output is a DataFrame (Pandas).

import asyncio
import fedfred as fd

async def main():
    fred = fd.FredAPI(api_key="your_api_key_here").Async

    data = await fred.get_series_observations("GDPC1")
    print(data.head())

    # Concurrent fetch
    tasks = [
        fred.get_series_observations("UNRATE"),
        fred.get_series_observations("CPIAUCSL"),
        fred.get_series_observations("DGS10"),
    ]
    results = await asyncio.gather(*tasks)

    for series in results:
        print(series.head())

asyncio.run(main())

See Advanced Usage Examples for bulk concurrent requests.

—

Working with DataFrames#

FedFred supports multiple backends.

data = fred.get_series_observations("GDPC1")

data = fred.get_series_observations("GDPC1", dataframe_method="polars")

data = fred.get_series_observations("GDPC1", dataframe_method="dask")

You can also customize the request:

Customizing Queries
inflation = fred.get_series_observations(
    series_id="CPIAUCSL",
    observation_start="2020-01-01",
    observation_end="2022-12-31",
    units="pc1",
    frequency="q",
    sort_order="asc"
)

Learn more about optional backends in Installing FedFred.

—

Exploring Metadata#

Browse FRED’s structured categories and tags.

Categories
categories = fred.get_category_children(category_id=0)
API Reference
Tags
gdp_tags = fred.get_series_tags("GDPC1")
API Reference

—

Searching for Series#

FedFred simplifies search operations:

# Keyword Search
results = fred.get_series_search("unemployment rate", limit=5)

# Category Search
results = fred.get_category_series(category_id=32991)

# Tag Search
results = fred.get_tags_series(tag_names="inflation")

—

Caching and Rate Limiting#

FedFred automatically respects rate limits (~120 calls/minute). You can enable local caching to boost performance:

fred = fd.FredAPI(
    api_key="your_api_key_here",
    cache_mode=True,
    cache_size=1000
)

See details in Advanced Usage Examples.

—

Geographic Data (MapsAPI)#

Access regional economic indicators easily.

fred_maps = fd.FredAPI(api_key="your_api_key_here").Maps

unemployment_by_state = fred_maps.get_regional_data(
    series_group="unemployment",
    region_type="state",
    date="2023-01-01",
    season="nsa",
    units="percent"
)

Result is a GeoDataFrame ready for plotting. See Data Visualization Examples for mapping examples.

—

Fetching Common Economic Indicators#

Quick examples:

gdp = fred.get_series_observations("GDPC1")
unemployment = fred.get_series_observations("UNRATE")
inflation = fred.get_series_observations("CPIAUCSL")
fed_funds = fred.get_series_observations("DFF")
treasury_10y = fred.get_series_observations("DGS10")

Perfect for dashboards and models.

—

What’s Next?#

Full API Reference

Explore every available method and object.

API Index
Advanced Usage

Learn about async, caching, custom queries, error handling.

Advanced Usage Examples
Data Visualization

Build charts, plots, and heatmaps from FRED data.

Data Visualization Examples
Parameter Handling Notes

Understand how FedFred transforms and validates your parameters.

Parameter Conversion and Validation Notes