@synsci/cli-darwin-x64-baseline 1.1.77 → 1.1.78

package/bin/skills/fred-economic-data/references/releases.md

@@ -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
+```