FRED API Basics

FRED API Basics

Base URL

https://api.stlouisfed.org/fred/

For GeoFRED endpoints:

https://api.stlouisfed.org/geofred/

Authentication

All requests require an API key passed as a query parameter:

api_key=YOUR_32_CHARACTER_KEY

Obtaining an API Key

1. Create account at https://fredaccount.stlouisfed.org
2. Log in and request an API key
3. Key is a 32-character lowercase alphanumeric string

Rate Limits

• API implements rate limiting
• HTTP 429 (Too Many Requests) when exceeded
• Contact FRED team for higher limits if needed

Response Formats

All endpoints support multiple formats via file_type parameter:

Some observation endpoints also support:

• csv - Comma-separated values
• xlsx - Excel format

Common Parameters

These parameters are available on most endpoints:

Real-Time Periods (ALFRED)

FRED supports historical (vintage) data access through real-time parameters:

• realtime_start: Beginning of the real-time period
• realtime_end: End of the real-time period
• Format: YYYY-MM-DD

This allows you to see data as it appeared at specific points in time:

# Get GDP as it was reported on Jan 1, 2020
params = {
    "series_id": "GDP",
    "realtime_start": "2020-01-01",
    "realtime_end": "2020-01-01"
}

FRED vs ALFRED

• FRED: Shows current/most recent data values
• ALFRED: Shows historical vintages and revisions of data

Use real-time parameters to access ALFRED data through the same API endpoints.

Pagination

Many endpoints support pagination:

Example:

# First page
params = {"limit": 100, "offset": 0}

# Second page
params = {"limit": 100, "offset": 100}

Sorting

Many endpoints support sorting:

Error Responses

HTTP Status Codes

Error Response Format

XML:

<error code="400" message="Bad Request. Variable api_key has not been set."/>

JSON:

{
    "error_code": 400,
    "error_message": "Bad Request. The value for variable api_key is not registered..."
}

Data Types

Date Format

All dates use YYYY-MM-DD format:

• Valid: 2023-01-15
• Invalid: 01/15/2023, Jan 15, 2023

Missing Values

In observation data, missing values are represented as a period:

{"date": "2020-01-01", "value": "."}

Always check for this when parsing values:

value = obs["value"]
if value != ".":
    numeric_value = float(value)

Tag Groups

Tags are organized into groups:

Example API Call

import requests

response = requests.get(
    "https://api.stlouisfed.org/fred/series/observations",
    params={
        "api_key": "YOUR_KEY",
        "series_id": "GDP",
        "file_type": "json",
        "observation_start": "2020-01-01",
        "units": "pch"
    }
)

data = response.json()
print(data)

Python Setup

Install required packages:

uv pip install requests pandas

Environment variable setup:

export FRED_API_KEY="your_32_character_key"

import os
api_key = os.environ.get("FRED_API_KEY")