foryourhealth111-pixel/Vibe-Skills / bundled/skills/fred-economic-data
fred-economic-data
VerifiedQuery 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.9 KB |
| references/api_basics.md | markdown | 4.5 KB |
| references/categories.md | markdown | 10.5 KB |
| references/geofred.md | markdown | 13.7 KB |
| references/releases.md | markdown | 15.6 KB |
| references/series.md | markdown | 14.1 KB |
| references/sources.md | markdown | 10.4 KB |
| references/tags.md | markdown | 11.1 KB |
| scripts/fred_examples.py | script | 10.1 KB |
| scripts/fred_query.py | script | 18.5 KB |
references/categories.md
View on GitHub# FRED Categories Endpoints
Categories endpoints provide access to the hierarchical organization of economic data series.
## Table of Contents
1. [fred/category](#fredcategory) - Get a category
2. [fred/category/children](#fredcategorychildren) - Get child categories
3. [fred/category/related](#fredcategoryrelated) - Get related categories
4. [fred/category/series](#fredcategoryseries) - Get series in category
5. [fred/category/tags](#fredcategorytags) - Get category tags
6. [fred/category/related_tags](#fredcategoryrelated_tags) - Get related tags
## Category Hierarchy
FRED organizes data in a hierarchical category structure. The root category has `category_id=0`.
**Top-level categories (children of root):**
- Money, Banking, & Finance (32991)
- Population, Employment, & Labor Markets (10)
- National Accounts (32992)
- Production & Business Activity (32455)
- Prices (32455)
- International Data (32263)
- U.S. Regional Data (3008)
- Academic Data (33060)
---
## fred/category
Get a category.
**URL:** `https://api.stlouisfed.org/fred/category`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
### Optional Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `category_id` | integer | 0 | Category ID; 0 = root |
| `file_type` | string | xml | xml or json |
### Example
```python
# Get root category
response = requests.get(
"https://api.stlouisfed.org/fred/category",
params={
"api_key": API_KEY,
"category_id": 0,
"file_type": "json"
}
)
# Get Trade Balance category
response = requests.get(
"https://api.stlouisfed.org/fred/category",
params={
"api_key": API_KEY,
"category_id": 125,
"file_type": "json"
}
)
```
### Response
```json
{
"categories": [
{
"id": 125,
"name": "Trade Balance",
"parent_id": 13
}
]
}
```
---
## fred/category/children
Get child categories for a category.
**URL:** `https://api.stlouisfed.org/fred/category/children`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
### Optional Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `category_id` | integer | 0 | Parent category ID |
| `file_type` | string | xml | xml or json |
| `realtime_start` | date | today | YYYY-MM-DD |
| `realtime_end` | date | today | YYYY-MM-DD |
### Example
```python
# Get children of International Trade category (13)
response = requests.get(
"https://api.stlouisfed.org/fred/category/children",
params={
"api_key": API_KEY,
"category_id": 13,
"file_type": "json"
}
)
```
### Response
```json
{
"categories": [
{"id": 16, "name": "Exports", "parent_id": 13},
{"id": 17, "name": "Imports", "parent_id": 13},
{"id": 3000, "name": "Income Payments & Receipts", "parent_id": 13},
{"id": 125, "name": "Trade Balance", "parent_id": 13},
{"id": 127, "name": "U.S. International Finance", "parent_id": 13}
]
}
```
---
## fred/category/related
Get related categories for a category.
**URL:** `https://api.stlouisfed.org/fred/category/related`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `category_id` | integer | Category ID |
### 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 |
**Note:** Related categories represent one-way relationships that exist outside the standard parent-child hierarchy. Most categories do not have related categories.
### Example
```python
response = requests.get(
"https://api.stlouisfed.org/fred/category/related",
params={
"api_key": API_KEY,
"category_id": 32073,
"file_type": "json"
}
)
```
### Response
```json
{
"categories": [
{"id": 149, "name": "Arkansas", "parent_id": 27281},
{"id": 150, "name": "Illinois", "parent_id": 27281}
]
}
```
---
## fred/category/series
Get the series in a category.
**URL:** `https://api.stlouisfed.org/fred/category/series`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `category_id` | integer | Category ID |
### 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 |
| `limit` | integer | 1000 | 1-1000 |
| `offset` | integer | 0 | Pagination offset |
| `order_by` | string | series_id | Sort field |
| `sort_order` | string | asc | asc or desc |
| `filter_variable` | string | - | frequency, units, seasonal_adjustment |
| `filter_value` | string | - | Filter value |
| `tag_names` | string | - | Semicolon-delimited tags |
| `exclude_tag_names` | string | - | Tags to exclude |
### Order By Options
- `series_id`
- `title`
- `units`
- `frequency`
- `seasonal_adjustment`
- `realtime_start`
- `realtime_end`
- `last_updated`
- `observation_start`
- `observation_end`
- `popularity`
- `group_popularity`
### Example
```python
# Get series in Trade Balance category with monthly frequency
response = requests.get(
"https://api.stlouisfed.org/fred/category/series",
params={
"api_key": API_KEY,
"category_id": 125,
"file_type": "json",
"filter_variable": "frequency",
"filter_value": "Monthly",
"order_by": "popularity",
"sort_order": "desc",
"limit": 10
}
)
```
### Response
```json
{
"count": 156,
"offset": 0,
"limit": 10,
"seriess": [
{
"id": "BOPGSTB",
"title": "Trade Balance: Goods and Services, Balance of Payments Basis",
"observation_start": "1992-01-01",
"observation_end": "2023-06-01",
"frequency": "Monthly",
"units": "Millions of Dollars",
"seasonal_adjustment": "Seasonally Adjusted",
"popularity": 78
}
]
}
```
---
## fred/category/tags
Get the tags for a category.
**URL:** `https://api.stlouisfed.org/fred/category/tags`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `category_id` | integer | Category ID |
### 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 |
| `tag_names` | string | - | Semicolon-delimited tags |
| `tag_group_id` | string | - | freq, gen, geo, geot, rls, seas, src |
| `search_text` | string | - | Search tag names |
| `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 |
### Tag Group IDs
| ID | Description |
|----|-------------|
| freq | Frequency |
| gen | General |
| geo | Geography |
| geot | Geography Type |
| rls | Release |
| seas | Seasonal Adjustment |
| src | Source |
### Example
```python
# Get frequency tags for Trade Balance category
response = requests.get(
"https://api.stlouisfed.org/fred/category/tags",
params={
"api_key": API_KEY,
"category_id": 125,
"file_type": "json",
"tag_group_id": "freq"
}
)
```
### Response
```json
{
"tags": [
{"name": "monthly", "group_id": "freq", "series_count": 100},
{"name": "quarterly", "group_id": "freq", "series_count": 45},
{"name": "annual", "group_id": "freq", "series_count": 30}
]
}
```
---
## fred/category/related_tags
Get related tags for a category.
**URL:** `https://api.stlouisfed.org/fred/category/related_tags`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `category_id` | integer | Category ID |
| `tag_names` | string | Semicolon-delimited tag names |
### 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 |
| `exclude_tag_names` | string | - | Tags to exclude |
| `tag_group_id` | string | - | freq, gen, geo, geot, rls, seas, src |
| `search_text` | string | - | Search tag names |
| `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
# Get tags related to 'services' and 'quarterly' in Trade Balance category
response = requests.get(
"https://api.stlouisfed.org/fred/category/related_tags",
params={
"api_key": API_KEY,
"category_id": 125,
"tag_names": "services;quarterly",
"file_type": "json"
}
)
```
---
## Common Category IDs
| ID | Name |
|----|------|
| 0 | Root (all categories) |
| 32991 | Money, Banking, & Finance |
| 10 | Population, Employment, & Labor Markets |
| 32992 | National Accounts |
| 1 | Production & Business Activity |
| 32455 | Prices |
| 32263 | International Data |
| 3008 | U.S. Regional Data |
| 33060 | Academic Data |
| 53 | Gross Domestic Product |
| 33490 | Interest Rates |
| 32145 | Exchange Rates |
| 12 | Consumer Price Indexes (CPI) |
| 2 | Unemployment |
## Navigating Categories
```python
def get_category_tree(api_key, category_id=0, depth=0, max_depth=2):
"""Recursively get category tree."""
if depth > max_depth:
return None
# Get children
response = requests.get(
"https://api.stlouisfed.org/fred/category/children",
params={
"api_key": api_key,
"category_id": category_id,
"file_type": "json"
}
)
data = response.json()
tree = []
for cat in data.get("categories", []):
node = {
"id": cat["id"],
"name": cat["name"],
"children": get_category_tree(api_key, cat["id"], depth + 1, max_depth)
}
tree.append(node)
return tree
# Get first 2 levels of category tree
tree = get_category_tree(API_KEY, depth=0, max_depth=1)
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 115k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| 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: 115k | Updated | Claude CodeCodex | Verified | Install |
| 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: 115k | Updated | Claude CodeCodex | Verified | Install |