skills/claude-scientific-skills
1
0
Fork 0
mirror of https://github.com/K-Dense-AI/claude-scientific-skills.git synced 2026-03-27 07:09:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add support for economic data form the Federal Reserve using FRED

Browse Source
This commit is contained in:
Timothy Kassis
2026-01-27 10:41:40 -08:00
parent a31cf4dd97
commit d17d74dc5d
12 changed files with 4756 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

212
scientific-skills/fred-economic-data/references/api_basics.md Normal file
View File

@@ -0,0 +1,212 @@
# FRED API Basics
## Base URL
```
https://api.stlouisfed.org/fred/
```
For GeoFRED endpoints:
```
https://api.stlouisfed.org/geofred/
```
## Authentication
All requests require an API key passed as a query parameter:
```
api_key=YOUR_32_CHARACTER_KEY
```
### Obtaining an API Key
1. Create account at https://fredaccount.stlouisfed.org
2. Log in and request an API key
3. Key is a 32-character lowercase alphanumeric string
### Rate Limits
- API implements rate limiting
- HTTP 429 (Too Many Requests) when exceeded
- Contact FRED team for higher limits if needed
## Response Formats
All endpoints support multiple formats via `file_type` parameter:
| Format | Content-Type |
|--------|--------------|
| `xml` | text/xml (default) |
| `json` | application/json |
Some observation endpoints also support:
- `csv` - Comma-separated values
- `xlsx` - Excel format
## Common Parameters
These parameters are available on most endpoints:
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `api_key` | string | required | 32-character API key |
| `file_type` | string | xml | Response format: xml, json |
| `realtime_start` | date | today | Start of real-time period (YYYY-MM-DD) |
| `realtime_end` | date | today | End of real-time period (YYYY-MM-DD) |
## Real-Time Periods (ALFRED)
FRED supports historical (vintage) data access through real-time parameters:
- `realtime_start`: Beginning of the real-time period
- `realtime_end`: End of the real-time period
- Format: YYYY-MM-DD
This allows you to see data as it appeared at specific points in time:
```python
# Get GDP as it was reported on Jan 1, 2020
params = {
"series_id": "GDP",
"realtime_start": "2020-01-01",
"realtime_end": "2020-01-01"
}
```
### FRED vs ALFRED
- **FRED**: Shows current/most recent data values
- **ALFRED**: Shows historical vintages and revisions of data
Use real-time parameters to access ALFRED data through the same API endpoints.
## Pagination
Many endpoints support pagination:
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | integer | varies | Maximum results (typically 1000) |
| `offset` | integer | 0 | Number of results to skip |
Example:
```python
# First page
params = {"limit": 100, "offset": 0}
# Second page
params = {"limit": 100, "offset": 100}
```
## Sorting
Many endpoints support sorting:
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `order_by` | string | varies | Field to sort by |
| `sort_order` | string | asc | Sort direction: asc, desc |
## Error Responses
### HTTP Status Codes
| Code | Description |
|------|-------------|
| 200 | Success |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid/missing API key |
| 404 | Not Found - Invalid endpoint or resource |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |
### Error Response Format
**XML:**
```xml
<error code="400" message="Bad Request. Variable api_key has not been set."/>
```
**JSON:**
```json
{
"error_code": 400,
"error_message": "Bad Request. The value for variable api_key is not registered..."
}
```
## Data Types
### Date Format
All dates use YYYY-MM-DD format:
- Valid: `2023-01-15`
- Invalid: `01/15/2023`, `Jan 15, 2023`
### Missing Values
In observation data, missing values are represented as a period:
```json
{"date": "2020-01-01", "value": "."}
```
Always check for this when parsing values:
```python
value = obs["value"]
if value != ".":
numeric_value = float(value)
```
## Tag Groups
Tags are organized into groups:
| Group ID | Description |
|----------|-------------|
| freq | Frequency (monthly, quarterly, etc.) |
| gen | General/topic tags |
| geo | Geography (usa, california, etc.) |
| geot | Geography type (nation, state, etc.) |
| rls | Release |
| seas | Seasonal adjustment |
| src | Source |
| cc | Citation/Copyright |
## Example API Call
```python
import requests
response = requests.get(
"https://api.stlouisfed.org/fred/series/observations",
params={
"api_key": "YOUR_KEY",
"series_id": "GDP",
"file_type": "json",
"observation_start": "2020-01-01",
"units": "pch"
}
)
data = response.json()
print(data)
```
## Python Setup
Install required packages:
```bash
uv pip install requests pandas
```
Environment variable setup:
```bash
export FRED_API_KEY="your_32_character_key"
```
```python
import os
api_key = os.environ.get("FRED_API_KEY")
```

442
scientific-skills/fred-economic-data/references/categories.md Normal file
View 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)
```

588
scientific-skills/fred-economic-data/references/geofred.md Normal file
View File

@@ -0,0 +1,588 @@
# FRED GeoFRED Endpoints
GeoFRED endpoints provide access to geographic/regional economic data and shape files for mapping.
## Table of Contents
1. [geofred/shapes/file](#geofredshapesfile) - Get geographic shape files
2. [geofred/series/group](#geofredseriesgroup) - Get series group metadata
3. [geofred/series/data](#geofredseriesdata) - Get regional series data
4. [geofred/regional/data](#geofredregionaldata) - Get regional data by group
## Base URL
```
https://api.stlouisfed.org/geofred/
```
## About GeoFRED
GeoFRED provides regional economic data for mapping and geographic analysis:
- State-level data (unemployment, income, GDP)
- County-level data
- Metropolitan Statistical Area (MSA) data
- Federal Reserve district data
- International country data
---
## geofred/shapes/file
Get geographic shape files in GeoJSON format for mapping.
**URL:** `https://api.stlouisfed.org/geofred/shapes/file`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
### Optional Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `shape` | string | Geographic shape type |
### Shape Types
| Value | Description |
|-------|-------------|
| `bea` | Bureau of Economic Analysis regions |
| `msa` | Metropolitan Statistical Areas |
| `frb` | Federal Reserve Bank districts |
| `necta` | New England City and Town Areas |
| `state` | US states |
| `country` | Countries |
| `county` | US counties |
| `censusregion` | Census regions |
| `censusdivision` | Census divisions |
### Example
```python
# Get US state boundaries
response = requests.get(
"https://api.stlouisfed.org/geofred/shapes/file",
params={
"api_key": API_KEY,
"shape": "state"
}
)
geojson = response.json()
```
### Response (GeoJSON FeatureCollection)
```json
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"name": "California",
"fips": "06"
},
"geometry": {
"type": "MultiPolygon",
"coordinates": [[[...]]]
}
},
{
"type": "Feature",
"properties": {
"name": "Texas",
"fips": "48"
},
"geometry": {
"type": "MultiPolygon",
"coordinates": [[[...]]]
}
}
]
}
```
### Mapping Example with Plotly
```python
import plotly.express as px
# Get shapes
shapes = requests.get(
"https://api.stlouisfed.org/geofred/shapes/file",
params={"api_key": API_KEY, "shape": "state"}
).json()
# Get unemployment data
data = requests.get(
"https://api.stlouisfed.org/geofred/regional/data",
params={
"api_key": API_KEY,
"series_group": "1220",
"region_type": "state",
"date": "2023-01-01",
"units": "Percent",
"frequency": "a",
"season": "NSA",
"file_type": "json"
}
).json()
# Create choropleth
fig = px.choropleth(
data["data"]["2023-01-01"],
geojson=shapes,
locations="code",
featureidkey="properties.fips",
color="value",
scope="usa",
title="Unemployment Rate by State"
)
fig.show()
```
---
## geofred/series/group
Get meta information for a regional data series.
**URL:** `https://api.stlouisfed.org/geofred/series/group`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `series_id` | string | FRED series ID with geographic data |
### Optional Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `file_type` | string | xml | xml or json |
### Example
```python
# Get info about Texas employment series
response = requests.get(
"https://api.stlouisfed.org/geofred/series/group",
params={
"api_key": API_KEY,
"series_id": "TXNA",
"file_type": "json"
}
)
```
### Response
```json
{
"series_group": {
"title": "All Employees: Total Nonfarm",
"region_type": "state",
"series_group": "1223",
"season": "NSA",
"units": "Thousands of Persons",
"frequency": "Annual",
"min_date": "1990-01-01",
"max_date": "2023-01-01"
}
}
```
### Response Fields
| Field | Description |
|-------|-------------|
| `title` | Series title |
| `region_type` | Geographic region type |
| `series_group` | Group identifier for related series |
| `season` | Seasonality (NSA, SA, etc.) |
| `units` | Units of measurement |
| `frequency` | Data frequency |
| `min_date` | Earliest available date |
| `max_date` | Latest available date |
**Note:** This endpoint only works with FRED series that have associated geographic data.
---
## geofred/series/data
Get regional data for a specific series.
**URL:** `https://api.stlouisfed.org/geofred/series/data`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `series_id` | string | FRED series ID with geographic data |
### Optional Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `file_type` | string | xml | xml or json |
| `date` | string | most recent | YYYY-MM-DD |
| `start_date` | string | - | YYYY-MM-DD |
**Note:** XML format is unavailable for county-level data.
### Example
```python
# Get Wisconsin per capita income data
response = requests.get(
"https://api.stlouisfed.org/geofred/series/data",
params={
"api_key": API_KEY,
"series_id": "WIPCPI",
"file_type": "json",
"date": "2022-01-01"
}
)
```
### Response
```json
{
"meta": {
"title": "Per Capita Personal Income",
"region": "state",
"seasonality": "Not Seasonally Adjusted",
"units": "Dollars",
"frequency": "Annual",
"date": "2022-01-01"
},
"data": {
"2022-01-01": [
{
"region": "Alabama",
"code": "01",
"value": "48000",
"series_id": "ALPCPI"
},
{
"region": "Alaska",
"code": "02",
"value": "62000",
"series_id": "AKPCPI"
}
]
}
}
```
---
## geofred/regional/data
Get regional data using a series group ID. This is the most flexible endpoint for regional data.
**URL:** `https://api.stlouisfed.org/geofred/regional/data`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `series_group` | string | Series group ID |
| `region_type` | string | Geographic region type |
| `date` | string | Target date (YYYY-MM-DD) |
| `season` | string | Seasonality code |
| `units` | string | Units of measurement |
### Optional Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `file_type` | string | xml | xml or json |
| `start_date` | string | - | YYYY-MM-DD |
| `frequency` | string | - | Data frequency |
| `transformation` | string | lin | Data transformation |
| `aggregation_method` | string | avg | avg, sum, eop |
### Region Types
| Value | Description |
|-------|-------------|
| `bea` | Bureau of Economic Analysis regions |
| `msa` | Metropolitan Statistical Areas |
| `frb` | Federal Reserve Bank districts |
| `necta` | New England City and Town Areas |
| `state` | US states |
| `country` | Countries |
| `county` | US counties |
| `censusregion` | Census regions |
### Seasonality Codes
| Code | Description |
|------|-------------|
| SA | Seasonally Adjusted |
| NSA | Not Seasonally Adjusted |
| SSA | Smoothed Seasonally Adjusted |
| SAAR | Seasonally Adjusted Annual Rate |
| NSAAR | Not Seasonally Adjusted Annual Rate |
### Example: State Unemployment Rates
```python
response = requests.get(
"https://api.stlouisfed.org/geofred/regional/data",
params={
"api_key": API_KEY,
"series_group": "1220", # Unemployment rate
"region_type": "state",
"date": "2023-01-01",
"units": "Percent",
"frequency": "a",
"season": "NSA",
"file_type": "json"
}
)
```
### Response
```json
{
"meta": {
"title": "Unemployment Rate",
"region": "state",
"seasonality": "Not Seasonally Adjusted",
"units": "Percent",
"frequency": "Annual"
},
"data": {
"2023-01-01": [
{
"region": "Alabama",
"code": "01",
"value": "2.8",
"series_id": "ALUR"
},
{
"region": "California",
"code": "06",
"value": "4.3",
"series_id": "CAUR"
}
]
}
}
```
### Example: Per Capita Income by County
```python
response = requests.get(
"https://api.stlouisfed.org/geofred/regional/data",
params={
"api_key": API_KEY,
"series_group": "882", # Per capita income
"region_type": "county",
"date": "2021-01-01",
"units": "Dollars",
"frequency": "a",
"season": "NSA",
"file_type": "json"
}
)
```
### Example: GDP by Metro Area
```python
response = requests.get(
"https://api.stlouisfed.org/geofred/regional/data",
params={
"api_key": API_KEY,
"series_group": "1282", # Real GDP
"region_type": "msa",
"date": "2022-01-01",
"units": "Millions of Chained 2017 Dollars",
"frequency": "a",
"season": "NSA",
"file_type": "json"
}
)
```
---
## Common Series Groups
| Group ID | Description | Region Types |
|----------|-------------|--------------|
| 882 | Per Capita Personal Income | state, county, msa |
| 1220 | Unemployment Rate | state, county, msa |
| 1223 | Total Nonfarm Employment | state, msa |
| 1282 | Real GDP | state, msa |
| 1253 | House Price Index | state, msa |
| 1005 | Population | state, county |
---
## Building a Regional Dashboard
```python
def get_state_dashboard(api_key, state_code, date):
"""Get key economic indicators for a state."""
indicators = {
"unemployment": {"group": "1220", "units": "Percent"},
"income": {"group": "882", "units": "Dollars"},
"employment": {"group": "1223", "units": "Thousands of Persons"}
}
dashboard = {}
for name, params in indicators.items():
response = requests.get(
"https://api.stlouisfed.org/geofred/regional/data",
params={
"api_key": api_key,
"series_group": params["group"],
"region_type": "state",
"date": date,
"units": params["units"],
"frequency": "a",
"season": "NSA",
"file_type": "json"
}
)
data = response.json()
# Find state data
for region in data.get("data", {}).get(date, []):
if region["code"] == state_code:
dashboard[name] = {
"value": region["value"],
"units": params["units"],
"series_id": region["series_id"]
}
break
return dashboard
# Get California dashboard
ca_data = get_state_dashboard(API_KEY, "06", "2023-01-01")
```
## Creating Choropleth Maps
```python
import pandas as pd
import plotly.express as px
def create_state_map(api_key, series_group, date, title):
"""Create a choropleth map of state-level data."""
# Get shapes
shapes = requests.get(
f"https://api.stlouisfed.org/geofred/shapes/file",
params={"api_key": api_key, "shape": "state"}
).json()
# Get data
response = requests.get(
"https://api.stlouisfed.org/geofred/regional/data",
params={
"api_key": api_key,
"series_group": series_group,
"region_type": "state",
"date": date,
"units": "Percent",
"frequency": "a",
"season": "NSA",
"file_type": "json"
}
)
data = response.json()
# Convert to DataFrame
df = pd.DataFrame(data["data"][date])
df["value"] = pd.to_numeric(df["value"], errors="coerce")
# Create map
fig = px.choropleth(
df,
geojson=shapes,
locations="code",
featureidkey="properties.fips",
color="value",
hover_name="region",
scope="usa",
title=title,
color_continuous_scale="RdYlGn_r"
)
return fig
# Create unemployment map
map_fig = create_state_map(
API_KEY,
series_group="1220",
date="2023-01-01",
title="Unemployment Rate by State (2023)"
)
map_fig.show()
```
## Time Series by Region
```python
def get_regional_time_series(api_key, series_group, region_type, start_date, end_date):
"""Get time series data for all regions."""
from datetime import datetime
# Generate dates (annual)
start = datetime.strptime(start_date, "%Y-%m-%d")
end = datetime.strptime(end_date, "%Y-%m-%d")
all_data = {}
for year in range(start.year, end.year + 1):
date = f"{year}-01-01"
response = requests.get(
"https://api.stlouisfed.org/geofred/regional/data",
params={
"api_key": api_key,
"series_group": series_group,
"region_type": region_type,
"date": date,
"units": "Percent",
"frequency": "a",
"season": "NSA",
"file_type": "json"
}
)
data = response.json()
for region in data.get("data", {}).get(date, []):
region_name = region["region"]
if region_name not in all_data:
all_data[region_name] = {}
all_data[region_name][date] = region["value"]
return all_data
# Get 5-year unemployment trends by state
trends = get_regional_time_series(
API_KEY,
series_group="1220",
region_type="state",
start_date="2019-01-01",
end_date="2023-01-01"
)
```

642
scientific-skills/fred-economic-data/references/releases.md Normal file
View File

@@ -0,0 +1,642 @@
# FRED Releases Endpoints
Releases endpoints provide access to economic data releases and their publication schedules.
## Table of Contents
1. [fred/releases](#fredreleases) - Get all releases
2. [fred/releases/dates](#fredreleasesdates) - Get release dates for all releases
3. [fred/release](#fredrelease) - Get a specific release
4. [fred/release/dates](#fredreleasedates) - Get dates for a release
5. [fred/release/series](#fredreleaseseries) - Get series in a release
6. [fred/release/sources](#fredreleasesources) - Get sources for a release
7. [fred/release/tags](#fredreleasetags) - Get tags for a release
8. [fred/release/related_tags](#fredreleaserelated_tags) - Get related tags
9. [fred/release/tables](#fredreleasetables) - Get release table structure
## About Releases
A "release" in FRED represents a publication of economic data, such as:
- Gross Domestic Product (release_id=53)
- Employment Situation (release_id=50)
- Consumer Price Index (release_id=10)
- Industrial Production and Capacity Utilization (release_id=13)
Releases have scheduled publication dates and may contain multiple related series.
---
## fred/releases
Get all releases of economic data.
**URL:** `https://api.stlouisfed.org/fred/releases`
### 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 |
| `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 | release_id | release_id, name, press_release, realtime_start, realtime_end |
| `sort_order` | string | asc | asc or desc |
### Example
```python
response = requests.get(
"https://api.stlouisfed.org/fred/releases",
params={
"api_key": API_KEY,
"file_type": "json",
"order_by": "name"
}
)
```
### Response
```json
{
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"count": 300,
"offset": 0,
"limit": 1000,
"releases": [
{
"id": 9,
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"name": "Advance Monthly Sales for Retail and Food Services",
"press_release": true,
"link": "http://www.census.gov/retail/"
},
{
"id": 53,
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"name": "Gross Domestic Product",
"press_release": true,
"link": "http://www.bea.gov/national/index.htm"
}
]
}
```
---
## fred/releases/dates
Get release dates for all releases of economic data.
**URL:** `https://api.stlouisfed.org/fred/releases/dates`
### 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 |
| `realtime_start` | date | current year start | YYYY-MM-DD |
| `realtime_end` | date | 9999-12-31 | YYYY-MM-DD |
| `limit` | integer | 1000 | 1-1000 |
| `offset` | integer | 0 | Pagination offset |
| `order_by` | string | release_date | release_date, release_id, release_name |
| `sort_order` | string | desc | asc or desc |
| `include_release_dates_with_no_data` | string | false | true or false |
**Note:** These dates reflect when data sources publish information, not necessarily when data becomes available on FRED.
### Example
```python
from datetime import datetime, timedelta
# Get releases in next 7 days
today = datetime.now().strftime("%Y-%m-%d")
next_week = (datetime.now() + timedelta(days=7)).strftime("%Y-%m-%d")
response = requests.get(
"https://api.stlouisfed.org/fred/releases/dates",
params={
"api_key": API_KEY,
"file_type": "json",
"realtime_start": today,
"realtime_end": next_week,
"order_by": "release_date",
"sort_order": "asc",
"include_release_dates_with_no_data": "true"
}
)
```
### Response
```json
{
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-21",
"count": 50,
"release_dates": [
{
"release_id": 21,
"release_name": "H.6 Money Stock Measures",
"date": "2023-08-15"
},
{
"release_id": 10,
"release_name": "Consumer Price Index",
"date": "2023-08-16"
}
]
}
```
---
## fred/release
Get a specific release of economic data.
**URL:** `https://api.stlouisfed.org/fred/release`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `release_id` | integer | Release identifier |
### 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 |
### Example
```python
# Get GDP release info
response = requests.get(
"https://api.stlouisfed.org/fred/release",
params={
"api_key": API_KEY,
"release_id": 53,
"file_type": "json"
}
)
```
### Response
```json
{
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"releases": [
{
"id": 53,
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"name": "Gross Domestic Product",
"press_release": true,
"link": "http://www.bea.gov/national/index.htm"
}
]
}
```
---
## fred/release/dates
Get release dates for a specific release.
**URL:** `https://api.stlouisfed.org/fred/release/dates`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `release_id` | integer | Release 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 |
| `include_release_dates_with_no_data` | string | false | true or false |
### Example
```python
# Get historical GDP release dates
response = requests.get(
"https://api.stlouisfed.org/fred/release/dates",
params={
"api_key": API_KEY,
"release_id": 53,
"file_type": "json",
"sort_order": "desc",
"limit": 20
}
)
```
### Response
```json
{
"realtime_start": "1776-07-04",
"realtime_end": "9999-12-31",
"count": 250,
"offset": 0,
"limit": 20,
"release_dates": [
{"release_id": 53, "date": "2023-07-27"},
{"release_id": 53, "date": "2023-06-29"},
{"release_id": 53, "date": "2023-05-25"}
]
}
```
---
## fred/release/series
Get the series on a release.
**URL:** `https://api.stlouisfed.org/fred/release/series`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `release_id` | integer | Release identifier |
### 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 quarterly series from GDP release
response = requests.get(
"https://api.stlouisfed.org/fred/release/series",
params={
"api_key": API_KEY,
"release_id": 53,
"file_type": "json",
"filter_variable": "frequency",
"filter_value": "Quarterly",
"order_by": "popularity",
"sort_order": "desc",
"limit": 10
}
)
```
### Response
```json
{
"count": 500,
"offset": 0,
"limit": 10,
"seriess": [
{
"id": "GDP",
"title": "Gross Domestic Product",
"observation_start": "1947-01-01",
"observation_end": "2023-04-01",
"frequency": "Quarterly",
"units": "Billions of Dollars",
"seasonal_adjustment": "Seasonally Adjusted Annual Rate",
"popularity": 95
},
{
"id": "GDPC1",
"title": "Real Gross Domestic Product",
"observation_start": "1947-01-01",
"observation_end": "2023-04-01",
"frequency": "Quarterly",
"units": "Billions of Chained 2017 Dollars",
"seasonal_adjustment": "Seasonally Adjusted Annual Rate",
"popularity": 90
}
]
}
```
---
## fred/release/sources
Get the sources for a release.
**URL:** `https://api.stlouisfed.org/fred/release/sources`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `release_id` | integer | Release identifier |
### 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 |
### Example
```python
response = requests.get(
"https://api.stlouisfed.org/fred/release/sources",
params={
"api_key": API_KEY,
"release_id": 51,
"file_type": "json"
}
)
```
### Response
```json
{
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"sources": [
{
"id": 18,
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"name": "U.S. Department of Commerce: Bureau of Economic Analysis",
"link": "http://www.bea.gov/"
},
{
"id": 19,
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"name": "U.S. Department of Commerce: Census Bureau",
"link": "http://www.census.gov/"
}
]
}
```
---
## fred/release/tags
Get the tags for a release.
**URL:** `https://api.stlouisfed.org/fred/release/tags`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `release_id` | integer | Release identifier |
### 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 |
### Example
```python
response = requests.get(
"https://api.stlouisfed.org/fred/release/tags",
params={
"api_key": API_KEY,
"release_id": 53,
"file_type": "json",
"tag_group_id": "gen"
}
)
```
---
## fred/release/related_tags
Get related tags for a release.
**URL:** `https://api.stlouisfed.org/fred/release/related_tags`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `release_id` | integer | Release identifier |
| `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 |
| `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 |
---
## fred/release/tables
Get release table trees for a release.
**URL:** `https://api.stlouisfed.org/fred/release/tables`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `release_id` | integer | Release identifier |
### Optional Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `file_type` | string | xml | xml or json |
| `element_id` | integer | root | Specific table element |
| `include_observation_values` | string | false | true or false |
| `observation_date` | string | 9999-12-31 | YYYY-MM-DD |
### Response Fields
| Field | Description |
|-------|-------------|
| `element_id` | Unique identifier for table element |
| `release_id` | Associated release |
| `series_id` | Economic data series reference |
| `name` | Element description |
| `level` | Hierarchical depth |
| `children` | Nested sub-elements |
### Example
```python
# Get GDP release table structure
response = requests.get(
"https://api.stlouisfed.org/fred/release/tables",
params={
"api_key": API_KEY,
"release_id": 53,
"file_type": "json"
}
)
```
### Response
```json
{
"name": "Gross Domestic Product",
"element_id": 12886,
"release_id": "53",
"elements": {
"12886": {
"element_id": 12886,
"release_id": 53,
"series_id": "GDP",
"parent_id": null,
"line": "1",
"type": "series",
"name": "Gross domestic product",
"level": "0",
"children": [12887, 12888]
}
}
}
```
---
## Common Release IDs
| ID | Name |
|----|------|
| 53 | Gross Domestic Product |
| 50 | Employment Situation |
| 10 | Consumer Price Index |
| 13 | G.17 Industrial Production and Capacity Utilization |
| 21 | H.6 Money Stock Measures |
| 18 | H.3 Aggregate Reserves of Depository Institutions |
| 19 | H.4.1 Factors Affecting Reserve Balances |
| 51 | International Transactions |
| 9 | Advance Monthly Sales for Retail and Food Services |
| 86 | Commercial Paper |
## Building a Release Calendar
```python
from datetime import datetime, timedelta
def get_release_calendar(api_key, days_ahead=14):
"""Get upcoming data releases."""
today = datetime.now()
end_date = today + timedelta(days=days_ahead)
response = requests.get(
"https://api.stlouisfed.org/fred/releases/dates",
params={
"api_key": api_key,
"file_type": "json",
"realtime_start": today.strftime("%Y-%m-%d"),
"realtime_end": end_date.strftime("%Y-%m-%d"),
"order_by": "release_date",
"sort_order": "asc",
"include_release_dates_with_no_data": "true"
}
)
data = response.json()
calendar = {}
for item in data.get("release_dates", []):
date = item["date"]
if date not in calendar:
calendar[date] = []
calendar[date].append({
"release_id": item["release_id"],
"name": item["release_name"]
})
return calendar
```

584
scientific-skills/fred-economic-data/references/series.md Normal file
View File

@@ -0,0 +1,584 @@
# 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"
}
)
```

423
scientific-skills/fred-economic-data/references/sources.md Normal file
View File

@@ -0,0 +1,423 @@
# FRED Sources Endpoints
Sources endpoints provide access to information about the data sources used in FRED.
## Table of Contents
1. [fred/sources](#fredsources) - Get all sources
2. [fred/source](#fredsource) - Get a specific source
3. [fred/source/releases](#fredsourcereleases) - Get releases for a source
## About Sources
Sources in FRED represent the organizations that produce economic data. Examples include:
- Bureau of Labor Statistics (BLS)
- Bureau of Economic Analysis (BEA)
- Federal Reserve Board
- U.S. Census Bureau
- International Monetary Fund (IMF)
- World Bank
---
## fred/sources
Get all sources of economic data.
**URL:** `https://api.stlouisfed.org/fred/sources`
### 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 |
| `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 | source_id | source_id, name, realtime_start, realtime_end |
| `sort_order` | string | asc | asc or desc |
### Example
```python
response = requests.get(
"https://api.stlouisfed.org/fred/sources",
params={
"api_key": API_KEY,
"file_type": "json",
"order_by": "name"
}
)
```
### Response
```json
{
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"count": 100,
"offset": 0,
"limit": 1000,
"sources": [
{
"id": 1,
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"name": "Board of Governors of the Federal Reserve System (US)",
"link": "http://www.federalreserve.gov/"
},
{
"id": 3,
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"name": "Federal Reserve Bank of Philadelphia",
"link": "http://www.philadelphiafed.org/"
},
{
"id": 18,
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"name": "U.S. Department of Commerce: Bureau of Economic Analysis",
"link": "http://www.bea.gov/"
},
{
"id": 22,
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"name": "U.S. Bureau of Labor Statistics",
"link": "http://www.bls.gov/"
}
]
}
```
---
## fred/source
Get a specific source of economic data.
**URL:** `https://api.stlouisfed.org/fred/source`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `source_id` | integer | Source identifier |
### 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 |
### Example
```python
# Get Federal Reserve Board info
response = requests.get(
"https://api.stlouisfed.org/fred/source",
params={
"api_key": API_KEY,
"source_id": 1,
"file_type": "json"
}
)
```
### Response
```json
{
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"sources": [
{
"id": 1,
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"name": "Board of Governors of the Federal Reserve System (US)",
"link": "http://www.federalreserve.gov/"
}
]
}
```
---
## fred/source/releases
Get the releases for a source.
**URL:** `https://api.stlouisfed.org/fred/source/releases`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `source_id` | integer | Source identifier |
### 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 | release_id | release_id, name, press_release, realtime_start, realtime_end |
| `sort_order` | string | asc | asc or desc |
### Example
```python
# Get releases from the Federal Reserve Board
response = requests.get(
"https://api.stlouisfed.org/fred/source/releases",
params={
"api_key": API_KEY,
"source_id": 1,
"file_type": "json",
"order_by": "name"
}
)
```
### Response
```json
{
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"count": 26,
"offset": 0,
"limit": 1000,
"releases": [
{
"id": 13,
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"name": "G.17 Industrial Production and Capacity Utilization",
"press_release": true,
"link": "http://www.federalreserve.gov/releases/g17/"
},
{
"id": 14,
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"name": "G.19 Consumer Credit",
"press_release": true,
"link": "http://www.federalreserve.gov/releases/g19/"
},
{
"id": 18,
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"name": "H.3 Aggregate Reserves of Depository Institutions",
"press_release": true,
"link": "http://www.federalreserve.gov/releases/h3/"
},
{
"id": 21,
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"name": "H.6 Money Stock Measures",
"press_release": true,
"link": "http://www.federalreserve.gov/releases/h6/"
}
]
}
```
---
## Common Source IDs
| ID | Name | Description |
|----|------|-------------|
| 1 | Board of Governors of the Federal Reserve System | Interest rates, money supply, banking data |
| 3 | Federal Reserve Bank of Philadelphia | Regional surveys, coincident indexes |
| 4 | Federal Reserve Bank of St. Louis | FRED-specific compilations |
| 6 | Federal Reserve Bank of Dallas | Regional economic data |
| 11 | Federal Reserve Bank of Kansas City | Labor market data |
| 18 | Bureau of Economic Analysis (BEA) | GDP, personal income, trade |
| 19 | U.S. Census Bureau | Population, housing, retail sales |
| 22 | Bureau of Labor Statistics (BLS) | Employment, CPI, PPI |
| 31 | National Bureau of Economic Research | Business cycle dates |
| 40 | International Monetary Fund | International financial data |
| 41 | World Bank | Global development indicators |
| 47 | Organisation for Economic Co-operation and Development (OECD) | International economic data |
| 57 | S&P Dow Jones Indices | Stock market indexes |
---
## Use Cases
### Find All Data from a Specific Agency
```python
def get_agency_data(api_key, source_id):
"""Get all releases and their series from a source."""
# Get source info
source_info = requests.get(
"https://api.stlouisfed.org/fred/source",
params={
"api_key": api_key,
"source_id": source_id,
"file_type": "json"
}
).json()
# Get all releases from this source
releases = requests.get(
"https://api.stlouisfed.org/fred/source/releases",
params={
"api_key": api_key,
"source_id": source_id,
"file_type": "json"
}
).json()
return {
"source": source_info.get("sources", [{}])[0],
"releases": releases.get("releases", [])
}
# Get all BLS data
bls_data = get_agency_data(API_KEY, source_id=22)
```
### Compare Data Availability Across Sources
```python
def compare_sources(api_key, source_ids):
"""Compare release counts across sources."""
comparison = {}
for sid in source_ids:
response = requests.get(
"https://api.stlouisfed.org/fred/source/releases",
params={
"api_key": api_key,
"source_id": sid,
"file_type": "json"
}
)
data = response.json()
# Get source name
source_resp = requests.get(
"https://api.stlouisfed.org/fred/source",
params={
"api_key": api_key,
"source_id": sid,
"file_type": "json"
}
)
source_name = source_resp.json().get("sources", [{}])[0].get("name", "Unknown")
comparison[source_name] = {
"source_id": sid,
"release_count": data.get("count", 0),
"releases": [r["name"] for r in data.get("releases", [])[:5]]
}
return comparison
# Compare Federal Reserve and BLS
comparison = compare_sources(API_KEY, [1, 22])
```
### Build a Source Directory
```python
def build_source_directory(api_key):
"""Build a directory of all FRED sources."""
response = requests.get(
"https://api.stlouisfed.org/fred/sources",
params={
"api_key": api_key,
"file_type": "json",
"order_by": "name"
}
)
sources = response.json().get("sources", [])
directory = []
for source in sources:
# Get releases for each source
releases_resp = requests.get(
"https://api.stlouisfed.org/fred/source/releases",
params={
"api_key": api_key,
"source_id": source["id"],
"file_type": "json"
}
)
release_count = releases_resp.json().get("count", 0)
directory.append({
"id": source["id"],
"name": source["name"],
"link": source.get("link", ""),
"release_count": release_count
})
return directory
```
---
## Source Categories
### U.S. Government Agencies
| ID | Name |
|----|------|
| 18 | Bureau of Economic Analysis |
| 19 | U.S. Census Bureau |
| 22 | Bureau of Labor Statistics |
| 60 | Congressional Budget Office |
| 61 | Office of Management and Budget |
### Federal Reserve System
| ID | Name |
|----|------|
| 1 | Board of Governors |
| 3 | Philadelphia Fed |
| 4 | St. Louis Fed |
| 6 | Dallas Fed |
| 11 | Kansas City Fed |
### International Organizations
| ID | Name |
|----|------|
| 40 | International Monetary Fund |
| 41 | World Bank |
| 47 | OECD |
| 69 | Bank for International Settlements |
### Private Sector
| ID | Name |
|----|------|
| 31 | NBER |
| 57 | S&P Dow Jones Indices |
| 44 | University of Michigan |

485
scientific-skills/fred-economic-data/references/tags.md Normal file
View File

@@ -0,0 +1,485 @@
# FRED Tags Endpoints
Tags endpoints provide access to FRED tags, which are attributes assigned to series for organization and discovery.
## Table of Contents
1. [fred/tags](#fredtags) - Get all FRED tags
2. [fred/related_tags](#fredrelated_tags) - Get related tags
3. [fred/tags/series](#fredtagsseries) - Get series matching tags
## About Tags
Tags are attributes assigned to series that help categorize and discover data. Tags are organized into groups:
| Group ID | Description | Examples |
|----------|-------------|----------|
| freq | Frequency | monthly, quarterly, annual |
| gen | General/Topic | gdp, inflation, employment |
| geo | Geography | usa, california, japan |
| geot | Geography Type | nation, state, county, msa |
| rls | Release | employment situation, gdp |
| seas | Seasonal Adjustment | sa, nsa |
| src | Source | bls, bea, census |
| cc | Citation/Copyright | public domain, copyrighted |
---
## fred/tags
Get FRED tags with optional filtering.
**URL:** `https://api.stlouisfed.org/fred/tags`
### 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 |
| `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, cc |
| `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 |
### Example: Get All Tags
```python
response = requests.get(
"https://api.stlouisfed.org/fred/tags",
params={
"api_key": API_KEY,
"file_type": "json",
"order_by": "popularity",
"sort_order": "desc",
"limit": 20
}
)
```
### Response
```json
{
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"count": 5000,
"offset": 0,
"limit": 20,
"tags": [
{
"name": "nation",
"group_id": "geot",
"notes": "",
"created": "2012-02-27 10:18:19-06",
"popularity": 100,
"series_count": 150000
},
{
"name": "usa",
"group_id": "geo",
"notes": "United States of America",
"created": "2012-02-27 10:18:19-06",
"popularity": 100,
"series_count": 450000
},
{
"name": "gdp",
"group_id": "gen",
"notes": "Gross Domestic Product",
"created": "2012-02-27 10:18:19-06",
"popularity": 85,
"series_count": 22000
}
]
}
```
### Example: Get Geography Tags Only
```python
response = requests.get(
"https://api.stlouisfed.org/fred/tags",
params={
"api_key": API_KEY,
"file_type": "json",
"tag_group_id": "geo",
"order_by": "series_count",
"sort_order": "desc"
}
)
```
### Example: Search for Tags
```python
# Find tags related to inflation
response = requests.get(
"https://api.stlouisfed.org/fred/tags",
params={
"api_key": API_KEY,
"file_type": "json",
"search_text": "inflation",
"order_by": "series_count",
"sort_order": "desc"
}
)
```
---
## fred/related_tags
Get related FRED tags for one or more specified tags.
**URL:** `https://api.stlouisfed.org/fred/related_tags`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `tag_names` | string | Semicolon-delimited tags |
### 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 | - | Filter 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 |
### Example: Find Tags Related to GDP
```python
response = requests.get(
"https://api.stlouisfed.org/fred/related_tags",
params={
"api_key": API_KEY,
"tag_names": "gdp",
"file_type": "json",
"order_by": "series_count",
"sort_order": "desc",
"limit": 20
}
)
```
### Response
```json
{
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"count": 500,
"offset": 0,
"limit": 20,
"tags": [
{
"name": "quarterly",
"group_id": "freq",
"notes": "",
"created": "2012-02-27 10:18:19-06",
"popularity": 95,
"series_count": 18000
},
{
"name": "annual",
"group_id": "freq",
"series_count": 15000
},
{
"name": "real",
"group_id": "gen",
"series_count": 12000
}
]
}
```
### Example: Find Geographic Tags Related to Unemployment
```python
response = requests.get(
"https://api.stlouisfed.org/fred/related_tags",
params={
"api_key": API_KEY,
"tag_names": "unemployment rate",
"file_type": "json",
"tag_group_id": "geo",
"order_by": "series_count",
"sort_order": "desc"
}
)
```
---
## fred/tags/series
Get the series matching all specified tags.
**URL:** `https://api.stlouisfed.org/fred/tags/series`
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `api_key` | string | 32-character API key |
| `tag_names` | string | Semicolon-delimited tags (series must match ALL) |
### Optional Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `file_type` | string | xml | xml or json |
| `exclude_tag_names` | string | - | Tags to exclude |
| `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 |
### Order By Options
- `series_id`
- `title`
- `units`
- `frequency`
- `seasonal_adjustment`
- `realtime_start`
- `realtime_end`
- `last_updated`
- `observation_start`
- `observation_end`
- `popularity`
- `group_popularity`
### Example: Find Quarterly GDP Series for USA
```python
response = requests.get(
"https://api.stlouisfed.org/fred/tags/series",
params={
"api_key": API_KEY,
"tag_names": "gdp;quarterly;usa",
"file_type": "json",
"order_by": "popularity",
"sort_order": "desc"
}
)
```
### Response
```json
{
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"count": 150,
"offset": 0,
"limit": 1000,
"seriess": [
{
"id": "GDP",
"realtime_start": "2023-08-14",
"realtime_end": "2023-08-14",
"title": "Gross Domestic Product",
"observation_start": "1947-01-01",
"observation_end": "2023-04-01",
"frequency": "Quarterly",
"units": "Billions of Dollars",
"seasonal_adjustment": "Seasonally Adjusted Annual Rate",
"last_updated": "2023-06-29 07:44:02-05",
"popularity": 95
},
{
"id": "GDPC1",
"title": "Real Gross Domestic Product",
"frequency": "Quarterly",
"units": "Billions of Chained 2017 Dollars",
"popularity": 90
}
]
}
```
### Example: Find Monthly Unemployment Rates by State
```python
response = requests.get(
"https://api.stlouisfed.org/fred/tags/series",
params={
"api_key": API_KEY,
"tag_names": "unemployment rate;monthly;state",
"file_type": "json",
"exclude_tag_names": "discontinued",
"order_by": "title",
"limit": 100
}
)
```
### Example: Find Inflation-Related Series Excluding NSA
```python
response = requests.get(
"https://api.stlouisfed.org/fred/tags/series",
params={
"api_key": API_KEY,
"tag_names": "inflation;monthly;usa",
"file_type": "json",
"exclude_tag_names": "nsa", # Exclude not seasonally adjusted
"order_by": "popularity",
"sort_order": "desc"
}
)
```
---
## Common Tag Combinations
### Macroeconomic Indicators
```python
# GDP
tags = "gdp;quarterly;usa"
# Unemployment
tags = "unemployment rate;monthly;nation"
# Inflation (CPI)
tags = "cpi;monthly;usa;sa"
# Interest Rates
tags = "interest rate;daily;treasury"
```
### Regional Data
```python
# State unemployment
tags = "unemployment rate;state;monthly"
# County population
tags = "population;county;annual"
# MSA employment
tags = "employment;msa;monthly"
```
### International
```python
# OECD countries GDP
tags = "gdp;oecd;annual"
# Exchange rates
tags = "exchange rate;daily;nation"
# International trade
tags = "trade;monthly;usa"
```
---
## Tag Discovery Pattern
```python
def discover_tags_for_topic(api_key, topic):
"""Find relevant tags for a research topic."""
# Step 1: Find tags matching the topic
response = requests.get(
"https://api.stlouisfed.org/fred/tags",
params={
"api_key": api_key,
"file_type": "json",
"search_text": topic,
"order_by": "popularity",
"sort_order": "desc",
"limit": 10
}
)
initial_tags = response.json().get("tags", [])
if not initial_tags:
return []
# Step 2: Find related tags
top_tag = initial_tags[0]["name"]
response = requests.get(
"https://api.stlouisfed.org/fred/related_tags",
params={
"api_key": api_key,
"tag_names": top_tag,
"file_type": "json",
"order_by": "series_count",
"sort_order": "desc",
"limit": 20
}
)
related = response.json().get("tags", [])
return {
"primary_tags": initial_tags,
"related_tags": related
}
# Example: Discover inflation-related tags
tags = discover_tags_for_topic(API_KEY, "inflation")
```
## Building Filtered Series Lists
```python
def get_filtered_series(api_key, topic_tags, geo_tags=None, freq_tag=None):
"""Get series matching topic with optional filters."""
all_tags = topic_tags.copy()
if geo_tags:
all_tags.extend(geo_tags)
if freq_tag:
all_tags.append(freq_tag)
response = requests.get(
"https://api.stlouisfed.org/fred/tags/series",
params={
"api_key": api_key,
"tag_names": ";".join(all_tags),
"file_type": "json",
"order_by": "popularity",
"sort_order": "desc",
"limit": 50
}
)
return response.json().get("seriess", [])
# Example: Monthly US inflation series
series = get_filtered_series(
API_KEY,
topic_tags=["inflation", "cpi"],
geo_tags=["usa"],
freq_tag="monthly"
)
```