Advanced Usage Examples¶

This section provides advanced usage examples for the fedfred library, including caching, rate limiting, concurrent requests, and working with geographic data.

Caching and Rate Limiting¶

The fedfred library includes built-in support for caching and rate limiting to optimize API usage.

import fedfred as fd

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

# Fetch a time series (cached locally for faster subsequent access)
data = fred.get_series_observations("GDPC1")
print(data.head())

# The built-in rate limiter ensures you don't exceed 120 API calls per minute
for series_id in ["UNRATE", "CPIAUCSL", "DGS10"]:
    data = fred.get_series_observations(series_id)
    print(f"Fetched data for {series_id}")

Concurrent Requests with AsyncAPI¶

You can use the AsyncAPI to make concurrent requests for improved performance.

import asyncio
import fedfred as fd

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

    # Fetch multiple series concurrently
    tasks = [
        fred.get_series_observations("UNRATE"),
        fred.get_series_observations("CPIAUCSL"),
        fred.get_series_observations("DGS10")
    ]
    results = await asyncio.gather(*tasks)

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

asyncio.run(fetch_multiple_series())

Working with Geographic Data¶

The FredMapsAPI allows you to fetch and analyze geographic data, such as unemployment rates by state.

import fedfred as fd

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

# Fetch regional data for unemployment rates by state
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"
)

# The result is a GeoPandas GeoDataFrame
print(unemployment_by_state)

Customizing API Requests¶

You can customize API requests by passing additional parameters to methods.

import fedfred as fd

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

# Fetch data with custom parameters
data = fred.get_series_observations(
    series_id="GDPC1",
    observation_start="2000-01-01",
    observation_end="2020-01-01",
    units="chg",  # Change from the previous value
    frequency="q",  # Quarterly data
    sort_order="asc"
)
print(data.head())

Exploring Categories and Tags¶

You can explore categories and tags to discover related data series.

import fedfred as fd

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

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

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

Error Handling and Validation¶

The fedfred library raises exceptions for invalid API requests or responses. You can handle these exceptions to improve the robustness of your application.

import fedfred as fd

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

try:
    # Attempt to fetch data for an invalid series ID
    data = fred.get_series_observations("INVALID_SERIES_ID")
except ValueError as e:
    print(f"Error: {e}")

try:
    # Attempt to fetch data with invalid parameters
    data = fred.get_series_observations(series_id="GDPC1", observation_start="invalid_date")
except ValueError as e:
    print(f"Error: {e}")