fred-economic-data

# 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:

```bash
export FRED_API_KEY="your_32_character_key_here"
```

Or in Python:
```python
import os
os.environ["FRED_API_KEY"] = "your_key_here"
```

## Quick Start

### Using the FREDQuery Class

```python
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

```python
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

```python
# 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

```python
# 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

```python
# 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.

```python
# 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.).

```python
# 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.

```python
# 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 | Description |
|-------|-------------|
| `lin` | Levels (no transformation) |
| `chg` | Change from previous period |
| `ch1` | Change from year ago |
| `pch` | Percent change from previous period |
| `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 |

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

## Frequency Aggregation

Aggregate data to different frequencies:

| Code | Frequency |
|------|-----------|
| `d` | Daily |
| `w` | Weekly |
| `m` | Monthly |
| `q` | Quarterly |
| `a` | Annual |

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

```python
# 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:

```python
# 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

```python
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

```python
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

```python
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

```python
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

```python
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:
```bash
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/