skills/fred-economic-data
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
fred-economic-data/references/releases.md
dfty e99c3e1ec9 Initial commit for fred-economic-data
2026-01-28 12:43:41 +08:00

643 lines
16 KiB
Markdown
Raw Permalink Blame History

# 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
```
Reference in New Issue View Git Blame Copy Permalink