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、日次・月次財務諸表、または入札結果	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"
)

リファレンス： すべての 10 個の系列エンドポイントについては、references/series.md を参照してください

カテゴリエンドポイント

経済データの階層的な構成をたどります。

主なエンドポイント：

• 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)

リファレンス： すべての 6 個のカテゴリエンドポイントについては、references/categories.md を参照してください

リリースエンドポイント

データのリリーススケジュールと公表情報にアクセスします。

主なエンドポイント：

• 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)

リファレンス： すべての 9 個のリリースエンドポイントについては、references/releases.md を参照してください

タグエンドポイント

FRED のタグを使用して系列を検索・絞り込みます。

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

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

リファレンス： すべての 3 個のタグエンドポイントについては、references/tags.md を参照してください

Sources エンドポイント

データソース（BLS、BEA、Census など）の情報を取得します。

# Get all sources
sources = fred.get_sources()

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

リファレンス： 3 つすべての Sources エンドポイントについては、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 という 1 つのエンドポイントがあり、1 回のページネーション付き呼び出しで、リリース内のすべての系列（全履歴）を返します。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	1 年前からの変化
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 ではキーごとに 1 分あたり最大 120 リクエストが許可されています。これを超えると HTTP 429 が返され、スロットリングを無視するとキーが一時的にブロックされる可能性があります。
• 繰り返しのクエリはキャッシュしてください（FREDQuery はデフォルトの TTL が 1 時間のインメモリキャッシュを保持します）。また、系列ごとの呼び出しを何百回も行うより、v2 のリリースダウンロードを 1 回利用することをお勧めします。
• FREDQuery は 429/5xx 応答を指数バックオフで再試行し、その他のエラーは即座に {"error": {"code": ..., "message": ...}}（FRED 独自の error_code/error_message）として返します。

リファレンスドキュメント

エンドポイントの詳細なドキュメントについては、以下を参照してください。

• Series エンドポイント - references/series.md を参照
• Categories エンドポイント - references/categories.md を参照
• Releases エンドポイント - references/releases.md を参照
• Tags エンドポイント - references/tags.md を参照
• Sources エンドポイント - 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 スイートの一部です。