/fred-economic-data

name: fred-economic-data
description: Query FRED (Federal Reserve Economic Data) API for 800,000+ economic time series from 100+ sources. Access GDP, unemployment, inflation, interest rates, exchange rates, housing, and regional data. Use for macroeconomic analysis, financial research, policy studies, economic forecasting, and academic research requiring U.S. and international economic indicators.
license: Unknown
metadata:
    skill-author: K-Dense Inc.

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 GDP data
gdp = fred.get_series("GDP")
print(f"Latest GDP: {gdp['observations'][-1]}")

# 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

| Series ID | Description | Frequency | |-----------|-------------|-----------| | GDP | Gross Domestic Product | Quarterly | | GDPC1 | Real Gross Domestic Product | Quarterly | | UNRATE | Unemployment Rate | Monthly | | CPIAUCSL | Consumer Price Index (All Urban) | Monthly | | FEDFUNDS | Federal Funds Effective Rate | Monthly | | DGS10 | 10-Year Treasury Constant Maturity | Daily | | HOUST | Housing Starts | Monthly | | PAYEMS | Total Nonfarm Payrolls | Monthly | | INDPRO | Industrial Production Index | Monthly | | M2SL | M2 Money Stock | Monthly | | UMCSENT | Consumer Sentiment | Monthly | | SP500 | S&P 500 | Daily |

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:

| Value |