Advanced Usage Examples#

FedFred enables high-performance, resilient FRED® data pipelines. This page covers caching, rate limiting, async concurrent requests, geo-data access, custom queries, and error handling.

—

Advanced Client Features#

Caching and Rate Limiting

Automatically cache responses and throttle API requests to optimize performance.

Caching and rate limiting documentation
Async Concurrent Requests

Fetch multiple series in parallel with AsyncAPI to greatly improve speed.

Asynchronous requests using AsyncAPI
Geographic Data Access

Retrieve regional economic data as GeoDataFrames using MapsAPI.

Geographic data handling
Custom API Queries

Control frequency, date range, aggregation, and sorting easily.

Customizing API queries
Browsing Categories and Tags

Navigate the FRED database using categories and metadata tags.

FRED hierarchy exploration
Error Handling

Handle API errors gracefully with automatic validation.

Handling errors and validation failures

—

Caching and Rate Limiting#

See Example
import fedfred as fd

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

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

for series_id in ["UNRATE", "CPIAUCSL", "DGS10"]:
    data = fred.get_series_observations(series_id)
    print(f"Fetched data for {series_id}")

FedFred automatically enforces FRED’s 120 calls/minute API limit.

—

Concurrent Requests with AsyncAPI#

See Example
import asyncio
import fedfred as fd

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

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

    for series, series_id in zip(results, ["UNRATE", "CPIAUCSL", "DGS10"]):
        print(f"Data for {series_id}:")
        print(series.head())

asyncio.run(fetch_multiple_series())

AsyncAPI dramatically improves throughput for bulk data retrieval.

—

Working with Geographic Data#

FedFred supports GeoPandas, Polars-ST, and Dask-GeoPandas for geographic outputs.

See Examples
import fedfred as fd

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",
    geodataframe_method="geopandas"  # Default
)

print(unemployment_by_state)

import fedfred as fd

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",
    geodataframe_method="polars"  # Use Polars-ST
)

print(unemployment_by_state)

import fedfred as fd

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",
    geodataframe_method="dask"  # Use Dask-GeoPandas
)

print(unemployment_by_state)

Regional economic data is always returned as a GeoDataFrame-compatible object, ready for mapping, GIS, or dashboard visualization.

—

Customizing API Requests#

See Example
import fedfred as fd

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

data = fred.get_series_observations(
    series_id="GDPC1",
    observation_start="2000-01-01",
    observation_end="2020-01-01",
    units="chg",
    frequency="q",
    sort_order="asc"
)
print(data.head())

Easily control time ranges, frequencies, and unit transformations.

—

Exploring Categories and Tags#

See Example
import fedfred as fd

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

categories = fred.get_category_children(category_id=0)
for category in categories:
    print(f"Category: {category.name} (ID: {category.id})")

tags = fred.get_category_tags(category_id=125)
for tag in tags:
    print(f"Tag: {tag.name}")

Explore the hierarchical FRED structure and discover datasets by topic.

—

Error Handling and Validation#

See Example
import fedfred as fd

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

try:
    data = fred.get_series_observations("INVALID_SERIES_ID")
except ValueError as e:
    print(f"Error: {e}")

try:
    data = fred.get_series_observations(series_id="GDPC1", observation_start="invalid_date")
except ValueError as e:
    print(f"Error: {e}")

FedFred validates parameters and raises descriptive errors to help debug mistakes quickly.

—