Alterlab Fred

FRED Economic Data Access

Overview

Access comprehensive economic data through FRED (Federal Reserve Economic Data), a database maintained by the Federal Reserve Bank of St. Louis containing over 800,000 economic time series from over 100 sources.

Key capabilities:

• Query economic time series data (GDP, unemployment, inflation, interest rates)
• Search and discover series by keywords, tags, and categories
• Access historical data and vintage (revision) data via ALFRED
• Retrieve release schedules and data publication dates
• Map regional economic data with GeoFRED
• Apply data transformations (percent change, log, etc.)

API Key Setup

Required: All FRED API requests require an API key.

1. Create an account at https://fredaccount.stlouisfed.org
2. Log in and request an API key through the account portal
3. Set as environment variable:

export FRED_API_KEY="your_32_character_key_here"

Or in Python:

import os
os.environ["FRED_API_KEY"] = "your_key_here"

Quick Start

Using the FREDQuery Class

from scripts.fred_query import FREDQuery

# Initialize with API key
fred = FREDQuery(api_key="YOUR_KEY")  # or uses FRED_API_KEY env var

# get_series returns METADATA (title, units, frequency) under "seriess".
# For the actual data values, use get_observations (returns "observations").
meta = fred.get_series("GDP")
print(meta["seriess"][0]["title"])  # "Gross Domestic Product"

# Get the latest GDP value
gdp = fred.get_observations("GDP", limit=1, sort_order="desc")
print(f"Latest GDP: {gdp['observations'][0]}")

# Get unemployment rate observations
unemployment = fred.get_observations("UNRATE", limit=12)
for obs in unemployment["observations"]:
    print(f"{obs['date']}: {obs['value']}%")

# Search for inflation series
inflation_series = fred.search_series("consumer price index")
for s in inflation_series["seriess"][:5]:
    print(f"{s['id']}: {s['title']}")

Direct API Calls

import requests
import os

API_KEY = os.environ.get("FRED_API_KEY")
BASE_URL = "https://api.stlouisfed.org/fred"

# Get series observations
response = requests.get(
    f"{BASE_URL}/series/observations",
    params={
        "api_key": API_KEY,
        "series_id": "GDP",
        "file_type": "json"
    }
)
data = response.json()

Popular Economic Series

API Endpoint Categories

Series Endpoints

Get economic data series metadata and observations.

Key endpoints:

• fred/series - Get series metadata
• fred/series/observations - Get data values (most commonly used)
• fred/series/search - Search for series by keywords
• fred/series/updates - Get recently updated series

# Get observations with transformations
obs = fred.get_observations(
    series_id="GDP",
    units="pch",  # percent change
    frequency="q",  # quarterly
    observation_start="2020-01-01"
)

# Search with filters
results = fred.search_series(
    "unemployment",
    filter_variable="frequency",
    filter_value="Monthly"
)

Reference: See references/series.md for all 10 series endpoints

Categories Endpoints

Navigate the hierarchical organization of economic data.

Key endpoints:

• fred/category - Get a category
• fred/category/children - Get subcategories
• fred/category/series - Get series in a category

# Get root categories (category_id=0)
root = fred.get_category()

# Get Money Banking & Finance category and its series
category = fred.get_category(32991)
series = fred.get_category_series(32991)

Reference: See references/categories.md for all 6 category endpoints

Releases Endpoints

Access data release schedules and publication information.

Key endpoints:

• fred/releases - Get all releases
• fred/releases/dates - Get upcoming release dates
• fred/release/series - Get series in a release

# Get upcoming release dates
upcoming = fred.get_release_dates()

# Get GDP release info
gdp_release = fred.get_release(53)

Reference: See references/releases.md for all 9 release endpoints

Tags Endpoints

Discover and filter series using FRED tags.

# Find series with multiple tags
series = fred.get_series_by_tags(["gdp", "quarterly", "usa"])

# Get related tags
related = fred.get_related_tags("inflation")

Reference: See references/tags.md for all 3 tag endpoints

Sources Endpoints

Get information about data sources (BLS, BEA, Census, etc.).

# Get all sources
sources = fred.get_sources()

# Get Federal Reserve releases
fed_releases = fred.get_source_releases(source_id=1)

Reference: See references/sources.md for all 3 source endpoints

GeoFRED Endpoints

Access geographic/regional economic data for mapping.

# Get state unemployment data
regional = fred.get_regional_data(
    series_group="1220",  # Unemployment rate
    region_type="state",
    date="2023-01-01",
    units="Percent",
    season="NSA"
)

# Get GeoJSON shapes
shapes = fred.get_shapes("state")

Reference: See references/geofred.md for all 4 GeoFRED endpoints

Data Transformations

Apply transformations when fetching observations:

# Get GDP percent change from year ago
gdp_growth = fred.get_observations("GDP", units="pc1")

Frequency Aggregation

Aggregate data to different frequencies:

Aggregation methods: avg (average), sum, eop (end of period)

# Convert daily to monthly average
monthly = fred.get_observations(
    "DGS10",
    frequency="m",
    aggregation_method="avg"
)

Real-Time (Vintage) Data

Access historical vintages of data via ALFRED:

# Get GDP as it was reported on a specific date
vintage_gdp = fred.get_observations(
    "GDP",
    realtime_start="2020-01-01",
    realtime_end="2020-01-01"
)

# Get all vintage dates for a series
vintages = fred.get_vintage_dates("GDP")

Common Patterns

Pattern 1: Economic Dashboard

def get_economic_snapshot(fred):
    """Get current values of key indicators."""
    indicators = ["GDP", "UNRATE", "CPIAUCSL", "FEDFUNDS", "DGS10"]
    snapshot = {}

    for series_id in indicators:
        obs = fred.get_observations(series_id, limit=1, sort_order="desc")
        if obs.get("observations"):
            latest = obs["observations"][0]
            snapshot[series_id] = {
                "value": latest["value"],
                "date": latest["date"]
            }

    return snapshot

Pattern 2: Time Series Comparison

def compare_series(fred, series_ids, start_date):
    """Compare multiple series over time."""
    import pandas as pd

    data = {}
    for sid in series_ids:
        obs = fred.get_observations(
            sid,
            observation_start=start_date,
            units="pc1"  # Normalize as percent change
        )
        data[sid] = {
            o["date"]: float(o["value"])
            for o in obs["observations"]
            if o["value"] != "."
        }

    return pd.DataFrame(data)

Pattern 3: Release Calendar

def get_upcoming_releases(fred, days=7):
    """Get data releases in next N days."""
    from datetime import datetime, timedelta

    end_date = datetime.now() + timedelta(days=days)

    releases = fred.get_release_dates(
        realtime_start=datetime.now().strftime("%Y-%m-%d"),
        realtime_end=end_date.strftime("%Y-%m-%d"),
        include_release_dates_with_no_data="true"
    )

    return releases

Pattern 4: Regional Analysis

def map_state_unemployment(fred, date):
    """Get unemployment by state for mapping."""
    data = fred.get_regional_data(
        series_group="1220",
        region_type="state",
        date=date,
        units="Percent",
        frequency="a",
        season="NSA"
    )

    # Get GeoJSON for mapping
    shapes = fred.get_shapes("state")

    return data, shapes

Error Handling

result = fred.get_observations("INVALID_SERIES")

if "error" in result:
    print(f"Error {result['error']['code']}: {result['error']['message']}")
elif not result.get("observations"):
    print("No data available")
else:
    # Process data
    for obs in result["observations"]:
        if obs["value"] != ".":  # Handle missing values
            print(f"{obs['date']}: {obs['value']}")

Rate Limits

• API implements rate limiting
• HTTP 429 returned when exceeded
• Use caching for frequently accessed data
• The FREDQuery class includes automatic retry with backoff

Reference Documentation

For detailed endpoint documentation:

• Series endpoints - See references/series.md
• Categories endpoints - See references/categories.md
• Releases endpoints - See references/releases.md
• Tags endpoints - See references/tags.md
• Sources endpoints - See references/sources.md
• GeoFRED endpoints - See references/geofred.md
• API basics - See references/api_basics.md

Scripts

scripts/fred_query.py

Main query module with FREDQuery class providing:

• Unified interface to all FRED endpoints
• Automatic rate limiting and caching
• Error handling and retry logic
• Type hints and documentation

scripts/fred_examples.py

Comprehensive examples demonstrating:

• Economic indicator retrieval
• Time series analysis
• Release calendar monitoring
• Regional data mapping
• Data transformation and aggregation

Run examples:

uv run python scripts/fred_examples.py

Additional Resources

• FRED Homepage: https://fred.stlouisfed.org/
• API Documentation: https://fred.stlouisfed.org/docs/api/fred/
• GeoFRED Maps: https://geofred.stlouisfed.org/
• ALFRED (Vintage Data): https://alfred.stlouisfed.org/
• Terms of Use: https://fred.stlouisfed.org/legal/