---
description: Access and retrieve economic data from the Federal Reserve Economic Data
  (FRED) database. Use this skill when you need U.S. economic indicators, financial
  data, GDP, inflation rates, unemployment statistics, interest rates, or any other
  macroeconomic data maintained by the Federal Reserve Bank of St. Louis. The skill
  provides programmatic access to over 800,000 economic time series from 100+ sources.
  Requires a free FRED API key (FRED_API_KEY environment variable).
metadata:
  default_prompt: Get the latest GDP growth rate and unemployment data
  display_name: FRED Economic Data
  icon_path: assets/icon.png
  short_description: Access Federal Reserve Economic Data via FRED API (requires your own free API key)
name: fred
---

# FRED Economic Data

Access comprehensive U.S. and international economic data from the Federal Reserve Economic Data (FRED) database via the FRED API.

## What This Skill Does

This skill enables you to:

- **Retrieve economic indicators**: GDP, inflation, unemployment, interest rates, stock indices, and more
- **Access time series data**: Get historical observations with custom date ranges
- **Search for series**: Find economic data by keywords or tags
- **Transform data**: Apply percent changes, year-over-year comparisons, and frequency conversions
- **Explore categories**: Browse the FRED taxonomy to discover related datasets
- **Get metadata**: Access series descriptions, sources, releases, and tags

## When To Use This Skill

Use this skill when you need:

- Current or historical economic indicators for analysis or reporting
- Macroeconomic data for financial modeling or forecasting
- Comparison of multiple economic metrics over time
- Data for charts, visualizations, or economic dashboards
- Information about economic releases, sources, or data categories

## Prerequisites

**API KEY REQUIRED**: This skill does not ship with an API key. Get a free key at https://fredaccount.stlouisfed.org/apikeys and set it as the `FRED_API_KEY` environment variable (or pass `api_key=...` to `FREDClient`). If no key is available, ask the user for one before making any call.

- The client reads `FRED_API_KEY` from the environment by default
- Alternatively, pass the key explicitly: `FREDClient(api_key='...')`
- Never hardcode or print the key

## Invocation

The user triggers this skill by mentioning economic data or FRED-related requests:

```
Get the latest GDP data
Show me unemployment rates for the past year
What's the current inflation rate?
Search FRED for housing price data
Get Federal Funds Rate history from 2020 to 2024
```

Or explicitly with FRED references:

```
/fred Get GDP growth rate
Use FRED to find consumer sentiment data
Query the Federal Reserve database for interest rates
```

## Workflow

### 1. Initialize the Client

When a FRED-related request is detected:

1. Initialize the FREDClient using the Python script in `scripts/fred_client.py`
2. The client reads the key from the `FRED_API_KEY` environment variable
3. Users may instead pass their own key explicitly

```python
from scripts.fred_client import FREDClient

# Initialize (reads FRED_API_KEY from the environment)
client = FREDClient()

# Or optionally with a custom API key
# client = FREDClient(api_key='custom_api_key')
```

### 2. Determine the Data Request

Based on the user's query, identify:

- **Specific indicator**: GDP, unemployment, inflation, etc.
- **Date range**: Start and end dates for observations
- **Data transformation**: Units (levels, percent change, year-over-year)
- **Frequency**: Daily, weekly, monthly, quarterly, annual
- **Search query**: Keywords if the user wants to find series

### 3. Retrieve Data

Use the appropriate FREDClient method:

**For specific indicators** (use helper methods):
```python
# GDP data
gdp_data = client.get_gdp(
    observation_start='2020-01-01',
    observation_end='2024-01-01',
    units='pc1'  # Percent change from year ago
)

# Unemployment rate
unemployment = client.get_unemployment_rate(
    observation_start='2023-01-01'
)

# Inflation (CPI)
inflation = client.get_inflation(
    observation_start='2023-01-01',
    units='pc1'  # Year-over-year percent change
)

# Federal Funds Rate
fed_funds = client.get_federal_funds_rate(
    observation_start='2023-01-01'
)
```

**For any series by ID**:
```python
# Get series observations by series ID
data = client.get_series_observations(
    series_id='SERIES_ID',
    observation_start='2020-01-01',
    observation_end='2024-01-01',
    units='lin',  # Linear/levels
    frequency='m'  # Monthly
)
```

**For searching series**:
```python
# Search for series
results = client.search_series(
    search_text='housing prices',
    limit=10
)
```

### 4. Process and Present Results

Extract the relevant data from the API response:

```python
# API responses contain 'observations' array
observations = data['observations']

# Each observation has 'date' and 'value'
for obs in observations:
    date = obs['date']
    value = obs['value']
```

Present the data in a clear, user-friendly format:

- **Tables**: For multiple data points
- **Charts**: For visualizations (describe or create)
- **Summary**: Latest value and key insights
- **Analysis**: Trends, changes, comparisons

### 5. Handle Multiple Indicators

When comparing multiple indicators:

```python
# Retrieve multiple series
gdp = client.get_gdp(observation_start='2023-01-01', units='pc1')
inflation = client.get_inflation(observation_start='2023-01-01', units='pc1')
unemployment = client.get_unemployment_rate(observation_start='2023-01-01')

# Combine and present
indicators = {
    'GDP Growth': gdp['observations'][-1]['value'],
    'Inflation': inflation['observations'][-1]['value'],
    'Unemployment': unemployment['observations'][-1]['value']
}
```

## Data Transformation Options

### Units Parameter

Transform data using the `units` parameter:

- `lin` - Levels (no transformation) - **DEFAULT**
- `chg` - Change
- `ch1` - Change from year ago
- `pch` - Percent change
- `pc1` - Percent change from year ago
- `pca` - Compounded annual rate of change
- `cch` - Continuously compounded rate of change
- `cca` - Continuously compounded annual rate of change
- `log` - Natural log

**Most common**:
- Use `lin` for raw values (index levels, rates)
- Use `pc1` for year-over-year percent change (growth rates)
- Use `pch` for period-over-period percent change

### Frequency Parameter

Aggregate data to different frequencies:

- `d` - Daily
- `w` - Weekly
- `bw` - Biweekly
- `m` - Monthly
- `q` - Quarterly
- `sa` - Semiannual
- `a` - Annual

## Common Series IDs

Reference the `FRED_SERIES_IDS.md` file in `references/` for a comprehensive list of frequently used series.

**Key indicators**:
- `GDP` - Gross Domestic Product
- `CPIAUCSL` - Consumer Price Index (Inflation)
- `UNRATE` - Unemployment Rate
- `DFF` - Federal Funds Effective Rate
- `SP500` - S&P 500 Index
- `DGS10` - 10-Year Treasury Rate

See `references/fred-ID-parentID-Names.csv` for the complete FRED category hierarchy and series IDs.

## Available Methods

The FREDClient provides comprehensive API access. Refer to `references/FRED_API_METHODS.md` for the complete method documentation.

**Core methods**:
- `get_series()` - Get series metadata
- `get_series_observations()` - Get data values
- `search_series()` - Search for series
- `get_series_categories()` - Get series categories
- `get_category()` - Get category information
- `get_releases()` - Get data releases
- `get_tags()` - Get and search tags

**Helper methods for common indicators**:
- `get_gdp()` - GDP data
- `get_inflation()` - CPI inflation
- `get_unemployment_rate()` - Unemployment
- `get_federal_funds_rate()` - Fed Funds Rate
- `get_sp500()` - S&P 500 Index
- `get_10year_treasury()` - 10-Year Treasury Rate
- `get_housing_starts()` - Housing Starts
- `get_retail_sales()` - Retail Sales
- `get_industrial_production()` - Industrial Production

## Error Handling

Handle common errors gracefully:

```python
try:
    data = client.get_series_observations('SERIES_ID')
except requests.exceptions.HTTPError as e:
    # Handle HTTP errors (404, 400, etc.)
    if e.response.status_code == 400:
        # Invalid series ID or parameters
        pass
except requests.exceptions.RequestException as e:
    # Handle network errors
    pass
```

**Common issues**:
- Invalid series ID: Suggest using `search_series()` to find the correct ID
- Date format errors: Ensure dates are in `YYYY-MM-DD` format
- API key issues: Verify the API key is valid
- Rate limits: FRED has rate limits; space out requests if needed

## Output Format

Present data clearly and concisely:

### For Single Indicator Queries

```
GDP Growth Rate (Year-over-Year)
Latest: Q3 2024 = 2.8%

Recent Quarters:
Q3 2024: 2.8%
Q2 2024: 3.0%
Q1 2024: 1.6%
Q4 2023: 3.2%
```

### For Multiple Indicators

```
Economic Indicators Summary (Latest Values)

GDP Growth:        2.8% (Q3 2024)
Inflation (CPI):   3.2% (Nov 2024)
Unemployment:      3.7% (Nov 2024)
Fed Funds Rate:    5.33% (Dec 2024)
```

### For Time Series Data

Create tables or describe trends:

```
Federal Funds Rate (2023-2024)

Date       | Rate
-----------|------
2023-01-01 | 4.55
2023-04-01 | 4.83
2023-07-01 | 5.12
2023-10-01 | 5.33
2024-01-01 | 5.33
```

### For Search Results

```
Series matching "housing prices":

1. CSUSHPISA - S&P/Case-Shiller U.S. National Home Price Index
   Frequency: Monthly | Units: Index

2. MSPUS - Median Sales Price of Houses Sold for the U.S.
   Frequency: Quarterly | Units: Dollars

3. HOSMEDUSM052N - Monthly Supply of Houses in the U.S.
   Frequency: Monthly | Units: Months' Supply
```

## Best Practices

1. **Date Ranges**: Default to the most relevant recent period unless specified
2. **Data Freshness**: Mention the observation date to show data currency
3. **Context**: Provide brief context about what the indicator measures
4. **Comparisons**: When appropriate, compare to historical values or benchmarks
5. **Visualizations**: Suggest or create charts for time series data
6. **Sources**: Credit FRED and cite the series ID for transparency

## Constraints

- **API Key Required**: Cannot function without a valid FRED API key
- **Data Availability**: Some series have limited historical data
- **Release Schedules**: Data is updated on specific schedules; latest values may be preliminary
- **Rate Limits**: Be mindful of API rate limits for bulk requests
- **Internet Required**: Requires active internet connection to access FRED API

## Examples

### Example 1: Latest GDP Growth

**User**: "What's the latest GDP growth rate?"

**Process**:
1. Initialize client with API key
2. Call `client.get_gdp(units='pc1', limit=4)` for latest quarters
3. Extract and present the most recent value with context

**Output**:
```
GDP Growth Rate (Latest)

Q3 2024: 2.8% (year-over-year)

The U.S. economy grew at an annual rate of 2.8% in the third quarter of 2024.

Recent Trend:
Q3 2024: 2.8%
Q2 2024: 3.0%
Q1 2024: 1.6%
Q4 2023: 3.2%
```

### Example 2: Economic Dashboard

**User**: "Create an economic dashboard with key indicators"

**Process**:
1. Retrieve multiple indicators: GDP, inflation, unemployment, Fed Funds, S&P 500
2. Get latest values for each
3. Present in a dashboard format

**Output**:
```
Economic Dashboard - December 2024

GDP Growth:        2.8%  (Q3 2024, year-over-year)
Inflation (CPI):   3.2%  (Nov 2024, year-over-year)
Unemployment:      3.7%  (Nov 2024)
Fed Funds Rate:    5.33% (effective rate)
S&P 500:          4,783  (latest close)
10-Year Treasury:  4.23% (yield)
```

### Example 3: Historical Analysis

**User**: "Show me unemployment rates from 2020 to 2024"

**Process**:
1. Call `client.get_unemployment_rate(observation_start='2020-01-01', observation_end='2024-12-31')`
2. Process monthly data
3. Highlight key trends (COVID impact, recovery)

**Output**:
```
Unemployment Rate (2020-2024)

Peak during COVID-19:
Apr 2020: 14.8% (pandemic peak)

Recent Values (2024):
Nov 2024: 3.7%
Oct 2024: 3.7%
Sep 2024: 3.8%

The unemployment rate has stabilized near historic lows after the sharp increase during the COVID-19 pandemic in 2020.
```

### Example 4: Data Search

**User**: "Find housing market data on FRED"

**Process**:
1. Call `client.search_series('housing market', limit=10)`
2. Present relevant series with descriptions
3. Offer to retrieve specific series data

**Output**:
```
Housing Market Data Series on FRED:

1. HOUST - Housing Starts: Total New Privately Owned
   Frequency: Monthly | Units: Thousands

2. CSUSHPISA - S&P/Case-Shiller U.S. National Home Price Index
   Frequency: Monthly | Units: Index (Jan 2000 = 100)

3. MORTGAGE30US - 30-Year Fixed Rate Mortgage Average
   Frequency: Weekly | Units: Percent

4. MSPUS - Median Sales Price of Houses Sold for the U.S.
   Frequency: Quarterly | Units: Dollars

5. PERMIT - New Private Housing Units Authorized by Building Permits
   Frequency: Monthly | Units: Thousands

Would you like to retrieve data from any of these series?
```

## Additional Resources

- FRED Website: https://fred.stlouisfed.org/
- API Documentation: https://fred.stlouisfed.org/docs/api/fred/
- Get API Key: https://fredaccount.stlouisfed.org/apikeys
- Popular Series: https://fred.stlouisfed.org/tags/series?t=nation

## Files in This Skill

- `SKILL.md` - This documentation
- `scripts/fred_client.py` - FRED API Python client
- `references/FRED_API_METHODS.md` - Complete method documentation
- `references/FRED_SERIES_IDS.md` - Common series IDs
- `references/fred-ID-parentID-Names.csv` - FRED category hierarchy
- `assets/icon.png` - Skill icon