Skip to content

foryourhealth111-pixel/Vibe-Skills / bundled/skills/fred-economic-data

fred-economic-data

Verified

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.

FileKindSize
SKILL.mdskill md10.9 KB
references/api_basics.mdmarkdown4.5 KB
references/categories.mdmarkdown10.5 KB
references/geofred.mdmarkdown13.7 KB
references/releases.mdmarkdown15.6 KB
references/series.mdmarkdown14.1 KB
references/sources.mdmarkdown10.4 KB
references/tags.mdmarkdown11.1 KB
scripts/fred_examples.pyscript10.1 KB
scripts/fred_query.pyscript18.5 KB

references/series.md

View on GitHub
# FRED Series Endpoints

Series endpoints provide access to economic data series metadata and observations.

## Table of Contents

1. [fred/series](#fredseries) - Get series metadata
2. [fred/series/observations](#fredseriesobservations) - Get data values
3. [fred/series/categories](#fredseriescategories) - Get series categories
4. [fred/series/release](#fredseriesrelease) - Get series release
5. [fred/series/search](#fredseriessearch) - Search for series
6. [fred/series/tags](#fredseriestags) - Get series tags
7. [fred/series/updates](#fredseriesupdates) - Get recently updated series
8. [fred/series/vintagedates](#fredseriesvintagedates) - Get vintage dates
9. [fred/series/search/tags](#fredseriessearchtags) - Get tags for search
10. [fred/series/search/related_tags](#fredseriessearchrelated_tags) - Get related tags for search

---

## fred/series

Get metadata for an economic data series.

**URL:** `https://api.stlouisfed.org/fred/series`

### Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `series_id` | string | Series identifier (e.g., "GDP", "UNRATE") |

### Optional Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `file_type` | string | xml | xml or json |
| `realtime_start` | date | today | YYYY-MM-DD |
| `realtime_end` | date | today | YYYY-MM-DD |

### Response Fields

| Field | Description |
|-------|-------------|
| `id` | Series identifier |
| `title` | Series title |
| `observation_start` | First observation date |
| `observation_end` | Last observation date |
| `frequency` | Data frequency |
| `units` | Units of measurement |
| `seasonal_adjustment` | Seasonal adjustment status |
| `last_updated` | Last update timestamp |
| `popularity` | Popularity ranking (0-100) |
| `notes` | Series description/notes |

### Example

```python
response = requests.get(
    "https://api.stlouisfed.org/fred/series",
    params={
        "api_key": API_KEY,
        "series_id": "GNPCA",
        "file_type": "json"
    }
)
```

### Response

```json
{
  "seriess": [
    {
      "id": "GNPCA",
      "title": "Real Gross National Product",
      "observation_start": "1929-01-01",
      "observation_end": "2022-01-01",
      "frequency": "Annual",
      "units": "Billions of Chained 2017 Dollars",
      "seasonal_adjustment": "Not Seasonally Adjusted",
      "last_updated": "2023-03-30 07:52:02-05",
      "popularity": 39,
      "notes": "BEA Account Code: A001RX..."
    }
  ]
}
```

---

## fred/series/observations

Get observations (data values) for an economic data series. **Most commonly used endpoint.**

**URL:** `https://api.stlouisfed.org/fred/series/observations`

### Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `series_id` | string | Series identifier |

### Optional Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `file_type` | string | xml | xml, json, xlsx, csv |
| `realtime_start` | date | today | YYYY-MM-DD |
| `realtime_end` | date | today | YYYY-MM-DD |
| `limit` | integer | 100000 | 1-100000 |
| `offset` | integer | 0 | Pagination offset |
| `sort_order` | string | asc | asc, desc |
| `observation_start` | date | 1776-07-04 | Filter start date |
| `observation_end` | date | 9999-12-31 | Filter end date |
| `units` | string | lin | Data transformation |
| `frequency` | string | none | Frequency aggregation |
| `aggregation_method` | string | avg | avg, sum, eop |
| `output_type` | integer | 1 | Output format type |
| `vintage_dates` | string | none | Comma-separated dates |

### Units Transformation Options

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

### Frequency Codes

| Code | Frequency |
|------|-----------|
| `d` | Daily |
| `w` | Weekly |
| `bw` | Biweekly |
| `m` | Monthly |
| `q` | Quarterly |
| `sa` | Semiannual |
| `a` | Annual |
| `wef` | Weekly, Ending Friday |
| `weth` | Weekly, Ending Thursday |
| `wew` | Weekly, Ending Wednesday |
| `wetu` | Weekly, Ending Tuesday |
| `wem` | Weekly, Ending Monday |
| `wesu` | Weekly, Ending Sunday |
| `wesa` | Weekly, Ending Saturday |
| `bwew` | Biweekly, Ending Wednesday |
| `bwem` | Biweekly, Ending Monday |

### Example

```python
# Get quarterly GDP with percent change transformation
response = requests.get(
    "https://api.stlouisfed.org/fred/series/observations",
    params={
        "api_key": API_KEY,
        "series_id": "GDP",
        "file_type": "json",
        "observation_start": "2020-01-01",
        "units": "pch"
    }
)
```

### Response

```json
{
  "realtime_start": "2023-08-14",
  "realtime_end": "2023-08-14",
  "observation_start": "2020-01-01",
  "observation_end": "9999-12-31",
  "units": "Percent Change",
  "output_type": 1,
  "file_type": "json",
  "order_by": "observation_date",
  "sort_order": "asc",
  "count": 14,
  "offset": 0,
  "limit": 100000,
  "observations": [
    {
      "realtime_start": "2023-08-14",
      "realtime_end": "2023-08-14",
      "date": "2020-01-01",
      "value": "1.1"
    },
    {
      "realtime_start": "2023-08-14",
      "realtime_end": "2023-08-14",
      "date": "2020-04-01",
      "value": "-8.3"
    }
  ]
}
```

---

## fred/series/categories

Get the categories for an economic data series.

**URL:** `https://api.stlouisfed.org/fred/series/categories`

### Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `series_id` | string | Series identifier |

### Example

```python
response = requests.get(
    "https://api.stlouisfed.org/fred/series/categories",
    params={
        "api_key": API_KEY,
        "series_id": "EXJPUS",
        "file_type": "json"
    }
)
```

### Response

```json
{
  "categories": [
    {"id": 95, "name": "Monthly Rates", "parent_id": 15},
    {"id": 275, "name": "Japan", "parent_id": 158}
  ]
}
```

---

## fred/series/release

Get the release for an economic data series.

**URL:** `https://api.stlouisfed.org/fred/series/release`

### Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `series_id` | string | Series identifier |

### Example

```python
response = requests.get(
    "https://api.stlouisfed.org/fred/series/release",
    params={
        "api_key": API_KEY,
        "series_id": "GDP",
        "file_type": "json"
    }
)
```

### Response

```json
{
  "releases": [
    {
      "id": 53,
      "name": "Gross Domestic Product",
      "press_release": true,
      "link": "http://www.bea.gov/national/index.htm"
    }
  ]
}
```

---

## fred/series/search

Search for economic data series by keywords.

**URL:** `https://api.stlouisfed.org/fred/series/search`

### Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |

### Optional Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `search_text` | string | - | Keywords to search |
| `file_type` | string | xml | xml or json |
| `search_type` | string | full_text | full_text or series_id |
| `limit` | integer | 1000 | 1-1000 |
| `offset` | integer | 0 | Pagination offset |
| `order_by` | string | varies | Ordering field |
| `sort_order` | string | varies | asc or desc |
| `filter_variable` | string | - | frequency, units, seasonal_adjustment |
| `filter_value` | string | - | Value for filter |
| `tag_names` | string | - | Semicolon-delimited tags |
| `exclude_tag_names` | string | - | Tags to exclude |

### Order By Options

- `search_rank` (default for full_text)
- `series_id` (default for series_id)
- `title`
- `units`
- `frequency`
- `seasonal_adjustment`
- `realtime_start`
- `realtime_end`
- `last_updated`
- `observation_start`
- `observation_end`
- `popularity`
- `group_popularity`

### Example

```python
# Search for inflation-related series
response = requests.get(
    "https://api.stlouisfed.org/fred/series/search",
    params={
        "api_key": API_KEY,
        "search_text": "consumer price index",
        "file_type": "json",
        "limit": 10,
        "filter_variable": "frequency",
        "filter_value": "Monthly"
    }
)
```

### Response

```json
{
  "count": 1234,
  "offset": 0,
  "limit": 10,
  "seriess": [
    {
      "id": "CPIAUCSL",
      "title": "Consumer Price Index for All Urban Consumers: All Items in U.S. City Average",
      "observation_start": "1947-01-01",
      "observation_end": "2023-07-01",
      "frequency": "Monthly",
      "units": "Index 1982-1984=100",
      "seasonal_adjustment": "Seasonally Adjusted",
      "popularity": 95
    }
  ]
}
```

---

## fred/series/tags

Get the FRED tags for a series.

**URL:** `https://api.stlouisfed.org/fred/series/tags`

### Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `series_id` | string | Series identifier |

### Optional Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `file_type` | string | xml | xml or json |
| `order_by` | string | series_count | series_count, popularity, created, name, group_id |
| `sort_order` | string | asc | asc or desc |

### Example

```python
response = requests.get(
    "https://api.stlouisfed.org/fred/series/tags",
    params={
        "api_key": API_KEY,
        "series_id": "GDP",
        "file_type": "json"
    }
)
```

### Response

```json
{
  "tags": [
    {"name": "gdp", "group_id": "gen", "series_count": 21862},
    {"name": "quarterly", "group_id": "freq", "series_count": 180000},
    {"name": "usa", "group_id": "geo", "series_count": 400000}
  ]
}
```

---

## fred/series/updates

Get economic data series sorted by when observations were updated.

**URL:** `https://api.stlouisfed.org/fred/series/updates`

### Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |

### Optional Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `file_type` | string | xml | xml or json |
| `limit` | integer | 1000 | 1-1000 |
| `offset` | integer | 0 | Pagination offset |
| `filter_value` | string | all | macro, regional, or all |
| `start_time` | string | - | YYYYMMDDHhmm format |
| `end_time` | string | - | YYYYMMDDHhmm format |

**Note:** Results are restricted to series updated within the last two weeks.

### Example

```python
response = requests.get(
    "https://api.stlouisfed.org/fred/series/updates",
    params={
        "api_key": API_KEY,
        "file_type": "json",
        "filter_value": "macro",
        "limit": 10
    }
)
```

---

## fred/series/vintagedates

Get the vintage dates for a series (dates when data was revised).

**URL:** `https://api.stlouisfed.org/fred/series/vintagedates`

### Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `series_id` | string | Series identifier |

### Optional Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `file_type` | string | xml | xml or json |
| `realtime_start` | date | 1776-07-04 | YYYY-MM-DD |
| `realtime_end` | date | 9999-12-31 | YYYY-MM-DD |
| `limit` | integer | 10000 | 1-10000 |
| `offset` | integer | 0 | Pagination offset |
| `sort_order` | string | asc | asc or desc |

### Example

```python
response = requests.get(
    "https://api.stlouisfed.org/fred/series/vintagedates",
    params={
        "api_key": API_KEY,
        "series_id": "GDP",
        "file_type": "json"
    }
)
```

### Response

```json
{
  "count": 250,
  "vintage_dates": [
    "1991-12-04",
    "1992-01-29",
    "1992-02-28"
  ]
}
```

---

## fred/series/search/tags

Get the tags for a series search.

**URL:** `https://api.stlouisfed.org/fred/series/search/tags`

### Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `series_search_text` | string | Search text |

### Optional Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `file_type` | string | xml | xml or json |
| `tag_names` | string | - | Semicolon-delimited tags |
| `tag_group_id` | string | - | freq, gen, geo, geot, rls, seas, src |
| `tag_search_text` | string | - | Filter tags by text |
| `limit` | integer | 1000 | 1-1000 |
| `offset` | integer | 0 | Pagination offset |
| `order_by` | string | series_count | series_count, popularity, created, name, group_id |
| `sort_order` | string | asc | asc or desc |

---

## fred/series/search/related_tags

Get related tags for a series search.

**URL:** `https://api.stlouisfed.org/fred/series/search/related_tags`

### Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `series_search_text` | string | Search text |
| `tag_names` | string | Semicolon-delimited tags |

### Optional Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `file_type` | string | xml | xml or json |
| `exclude_tag_names` | string | - | Tags to exclude |
| `tag_group_id` | string | - | freq, gen, geo, geot, rls, seas, src |
| `tag_search_text` | string | - | Filter tags |
| `limit` | integer | 1000 | 1-1000 |
| `offset` | integer | 0 | Pagination offset |
| `order_by` | string | series_count | Ordering field |
| `sort_order` | string | asc | asc or desc |

### Example

```python
response = requests.get(
    "https://api.stlouisfed.org/fred/series/search/related_tags",
    params={
        "api_key": API_KEY,
        "series_search_text": "mortgage rate",
        "tag_names": "30-year;frb",
        "file_type": "json"
    }
)
```
add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.Stars: 115kUpdated Claude CodeCodexVerifiedInstall