alterlab-fred

FRED 经济数据访问

概述

通过 FRED（Federal Reserve Economic Data，联邦储备经济数据）访问全面的经济数据。该数据库由圣路易斯联邦储备银行维护，包含来自 100 多个来源的 80 多万条经济时间序列。

主要功能：

• 查询经济时间序列数据（GDP、失业率、通货膨胀、利率）
• 按关键字、标签和类别搜索并发现时间序列
• 通过 ALFRED 访问历史数据和实时版本（修订）数据
• 获取发布日期安排和数据发布日期
• 使用 GeoFRED 映射区域经济数据
• 应用数据转换（百分比变化、对数等）
• 批量下载某次发布中的所有时间序列（API v2）

何时使用此技能

• 按 FRED 时间序列 ID（GDPC1、UNRATE、CPIAUCSL、DGS10 等）获取美国或国际宏观／金融时间序列
• 在分析前进行服务器端转换（pc1、pch、log）或频率聚合
• 从 ALFRED 获取实时版本数据，避免预测研究中的前视偏差
• 获取发布日期日历、按关键字／标签／类别发现时间序列，以及用于地图的州／县数据

不适用情形

场景	请改用
股票／ETF 价格、OHLCV 柱状数据或技术指标（RSI、MACD）	alterlab-alpha-vantage
来自财政部的 Debt to the Penny、Daily/Monthly Treasury Statements 或拍卖结果	alterlab-usfiscaldata
SEC 文件中的公司级财务报表	alterlab-edgartools
按地理区域划分的公共统计数据（人口统计、健康、非 FRED 全球指标）	alterlab-datacommons
对已下载的时间序列进行计量经济建模（ARIMA、VAR、回归）	alterlab-statsmodels

API 密钥设置

**必需：**所有 FRED API 请求都需要 API 密钥。

1. 在 https://fredaccount.stlouisfed.org 创建账户
2. 登录并通过账户门户申请 API 密钥
3. 将其设置为环境变量：

export FRED_API_KEY="your_32_character_key_here"

或在 Python 中设置：

import os
os.environ["FRED_API_KEY"] = "your_key_here"

快速入门

使用 FREDQuery 类

from scripts.fred_query import FREDQuery

# Initialize with API key
fred = FREDQuery(api_key="YOUR_KEY")  # or uses FRED_API_KEY env var

# get_series returns METADATA (title, units, frequency) under "seriess".
# For the actual data values, use get_observations (returns "observations").
meta = fred.get_series("GDP")
print(meta["seriess"][0]["title"])  # "Gross Domestic Product"

# Get the latest GDP value
gdp = fred.get_observations("GDP", limit=1, sort_order="desc")
print(f"Latest GDP: {gdp['observations'][0]}")

# Get unemployment rate observations
unemployment = fred.get_observations("UNRATE", limit=12)
for obs in unemployment["observations"]:
    print(f"{obs['date']}: {obs['value']}%")

# Search for inflation series
inflation_series = fred.search_series("consumer price index")
for s in inflation_series["seriess"][:5]:
    print(f"{s['id']}: {s['title']}")

直接调用 API

import requests
import os

API_KEY = os.environ.get("FRED_API_KEY")
BASE_URL = "https://api.stlouisfed.org/fred"

# Get series observations
response = requests.get(
    f"{BASE_URL}/series/observations",
    params={
        "api_key": API_KEY,
        "series_id": "GDP",
        "file_type": "json"
    }
)
data = response.json()

常用经济时间序列

时间序列 ID	描述	频率
GDP	国内生产总值	季度
GDPC1	实际国内生产总值	季度
UNRATE	失业率	月度
CPIAUCSL	消费者价格指数（所有城市消费者）	月度
FEDFUNDS	联邦基金有效利率	月度
DGS10	10 年期美国国债恒定期限收益率	每日
HOUST	新屋开工数	月度
PAYEMS	非农就业总人数	月度
INDPRO	工业生产指数	月度
M2SL	M2 货币存量	月度
UMCSENT	消费者信心	月度
SP500	S&P 500	每日

API 端点类别

时间序列端点

获取经济数据时间序列的元数据和观测值。

主要端点：

• fred/series - 获取时间序列元数据
• fred/series/observations - 获取数据值（最常用）
• fred/series/search - 按关键字搜索时间序列
• fred/series/updates - 获取最近更新的时间序列

# Get observations with transformations
obs = fred.get_observations(
    series_id="GDP",
    units="pch",  # percent change
    frequency="q",  # quarterly
    observation_start="2020-01-01"
)

# Search with filters
results = fred.search_series(
    "unemployment",
    filter_variable="frequency",
    filter_value="Monthly"
)

**参考：**请参阅 references/series.md，了解全部 10 个时间序列端点

类别端点

浏览经济数据的层级组织结构。

主要端点：

• fred/category - 获取类别
• fred/category/children - 获取子类别
• fred/category/series - 获取某类别中的时间序列

# Get root categories (category_id=0)
root = fred.get_category()

# Get Money Banking & Finance category and its series
category = fred.get_category(32991)
series = fred.get_category_series(32991)

**参考：**请参阅 references/categories.md，了解全部 6 个类别端点

发布端点

访问数据发布日期安排和发布信息。

主要端点：

• fred/releases - 获取所有发布
• fred/releases/dates - 获取即将发布的日期
• fred/release/series - 获取某次发布中的时间序列

# Get upcoming release dates
upcoming = fred.get_release_dates()

# Get GDP release info
gdp_release = fred.get_release(53)

**参考：**请参阅 references/releases.md，了解全部 9 个发布端点

标签端点

使用 FRED 标签发现和筛选时间序列。

# Find series with multiple tags
series = fred.get_series_by_tags(["gdp", "quarterly", "usa"])

# Get related tags
related = fred.get_related_tags("inflation")

**参考：**请参阅 references/tags.md，了解全部 3 个标签端点

来源端点

获取数据来源（BLS、BEA、Census 等）的信息。

# Get all sources
sources = fred.get_sources()

# Get Federal Reserve releases
fed_releases = fred.get_source_releases(source_id=1)

**参考：**所有 3 个来源端点请参阅 references/sources.md

GeoFRED 端点

访问用于制图的地理／区域经济数据。

# Get state unemployment data
regional = fred.get_regional_data(
    series_group="1220",  # Unemployment rate
    region_type="state",
    date="2023-01-01",
    units="Percent",
    season="NSA"
)

# Get GeoJSON shapes
shapes = fred.get_shapes("state")

**参考：**所有 4 个 GeoFRED 端点请参阅 references/geofred.md

批量发布数据下载（API v2）

FRED API v2 有一个端点 fred/v2/release/observations，可通过一次分页调用返回某个发布中的所有序列（全部历史数据）。与 v1 不同，它通过请求头传入密钥：

import os
import requests

url = "https://api.stlouisfed.org/fred/v2/release/observations"
headers = {"Authorization": f"Bearer {os.environ['FRED_API_KEY']}"}
params = {"release_id": 53, "limit": 500000}  # 53 = GDP release; limit max 500,000 observations
series = []
while True:
    page = requests.get(url, headers=headers, params=params, timeout=120).json()
    series.extend(page["series"])  # each series carries its observations
    if not page.get("has_more"):
        break
    params["next_cursor"] = page["next_cursor"]  # omit on the first request

数据转换

获取观测值时应用转换：

值	描述
lin	水平值（不转换）
chg	与上一期相比的变化
ch1	与一年前相比的变化
pch	与上一期相比的百分比变化
pc1	与一年前相比的百分比变化
pca	复合年变化率
cch	连续复利变化率
cca	连续复利年变化率
log	自然对数

# Get GDP percent change from year ago
gdp_growth = fred.get_observations("GDP", units="pc1")

频率聚合

将数据聚合到不同频率：

代码	频率
d	每日
w	每周
m	每月
q	每季度
a	每年

聚合方法：avg（平均值）、sum、eop（期末）

# Convert daily to monthly average
monthly = fred.get_observations(
    "DGS10",
    frequency="m",
    aggregation_method="avg"
)

实时（版本）数据

通过 ALFRED 访问历史数据版本：

# Get GDP as it was reported on a specific date
vintage_gdp = fred.get_observations(
    "GDP",
    realtime_start="2020-01-01",
    realtime_end="2020-01-01"
)

# Get all vintage dates for a series
vintages = fred.get_vintage_dates("GDP")

常见模式

模式 1：经济仪表板

def get_economic_snapshot(fred):
    """Get current values of key indicators."""
    indicators = ["GDP", "UNRATE", "CPIAUCSL", "FEDFUNDS", "DGS10"]
    snapshot = {}

    for series_id in indicators:
        obs = fred.get_observations(series_id, limit=1, sort_order="desc")
        if obs.get("observations"):
            latest = obs["observations"][0]
            snapshot[series_id] = {
                "value": latest["value"],
                "date": latest["date"]
            }

    return snapshot

模式 2：时间序列比较

def compare_series(fred, series_ids, start_date):
    """Compare multiple series over time."""
    import pandas as pd

    data = {}
    for sid in series_ids:
        obs = fred.get_observations(
            sid,
            observation_start=start_date,
            units="pc1"  # Normalize as percent change
        )
        data[sid] = {
            o["date"]: float(o["value"])
            for o in obs["observations"]
            if o["value"] != "."
        }

    return pd.DataFrame(data)

模式 3：发布日历

def get_upcoming_releases(fred, days=7):
    """Get data releases in next N days."""
    from datetime import datetime, timedelta

    end_date = datetime.now() + timedelta(days=days)

    releases = fred.get_release_dates(
        realtime_start=datetime.now().strftime("%Y-%m-%d"),
        realtime_end=end_date.strftime("%Y-%m-%d"),
        include_release_dates_with_no_data="true"
    )

    return releases

模式 4：区域分析

def map_state_unemployment(fred, date):
    """Get unemployment by state for mapping."""
    data = fred.get_regional_data(
        series_group="1220",
        region_type="state",
        date=date,
        units="Percent",
        frequency="a",
        season="NSA"
    )

    # Get GeoJSON for mapping
    shapes = fred.get_shapes("state")

    return data, shapes

错误处理

result = fred.get_observations("INVALID_SERIES")

if "error" in result:
    print(f"Error {result['error']['code']}: {result['error']['message']}")
elif not result.get("observations"):
    print("No data available")
else:
    # Process data
    for obs in result["observations"]:
        if obs["value"] != ".":  # Handle missing values
            print(f"{obs['date']}: {obs['value']}")

速率限制

• FRED 每个密钥每分钟最多允许 120 次请求；超过限制时会返回 HTTP 429，忽略限流可能导致密钥被暂时封禁。
• 缓存重复查询（FREDQuery 使用内存缓存，默认 TTL 为 1 小时），并优先使用一次 v2 发布数据下载，而不是数百次逐序列调用。
• FREDQuery 会通过指数退避重试 429／5xx 响应，并将其他错误立即作为 {"error": {"code": ..., "message": ...}} 返回（FRED 自身的 error_code／error_message）。

参考文档

端点详细文档：

• 序列端点 - 请参阅 references/series.md
• 类别端点 - 请参阅 references/categories.md
• 发布端点 - 请参阅 references/releases.md
• 标签端点 - 请参阅 references/tags.md
• 来源端点 - 请参阅 references/sources.md
• GeoFRED 端点 - 请参阅 references/geofred.md
• API 基础知识 - 请参阅 references/api_basics.md

脚本

scripts/fred_query.py

主查询模块，包含 FREDQuery 类，提供：

• 统一接口，用于访问 v1 FRED 和 GeoFRED（Maps API）端点
• 内存响应缓存
• 对 429／5xx 进行退避重试；其他故障会显示 FRED 错误消息
• 类型提示和文档

社区维护的 fredapi 包（uv pip install fredapi；Fred(api_key=...).get_series("GDP") 会返回 pandas Series）是获取普通序列的轻量替代方案；自 0.5.2 版（2024-05）以来未发布新版本。

scripts/fred_examples.py

全面示例，演示：

• 获取经济指标
• 时间序列分析
• 发布日历监控
• 区域数据制图
• 数据转换与聚合

运行示例：

uv run python scripts/fred_examples.py

其他资源

• FRED 主页：https://fred.stlouisfed.org/
• API 文档：https://fred.stlouisfed.org/docs/api/fred/
• GeoFRED 地图：https://geofred.stlouisfed.org/
• ALFRED（版本数据）：https://alfred.stlouisfed.org/
• 使用条款：https://fred.stlouisfed.org/legal/

在论文中使用的每个序列都应引用 FRED（序列 ID、来源机构和检索日期）。

属于 AlterLab Academic Skills 套件。