Initial commit for fred-economic-data
This commit is contained in:
dfty
442
references/categories.md
Normal file
442
references/categories.md
Normal file
@@ -0,0 +1,442 @@
|
||||
# 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)
|
||||
```
|
||||
Reference in New Issue
Block a user