fred-macro

FRED Macro — Federal Reserve Economic Data API

セントルイス連邦準備銀行（FRED）が提供する無料の公式 API で、GDP、インフレ率（CPI/PCE）、金利、雇用、M2、VIX、米国債、住宅ローンなど、840,000+ 件のマクロ経済時系列データを利用できます。

ベース URL: https://api.stlouisfed.org/fred 公式ドキュメント: fred.stlouisfed.org/docs/api/fred/

---

認証

API Key の取得（無料）

1. 次の URL にアクセスします：https://fred.stlouisfed.org/docs/api/api_key.html
2. 無料アカウントを作成します（メールアドレス＋パスワード）
3. API key を申請します（即座に発行されます）
4. クレジットカードは不要です

API Key の使用方法

import os
API_KEY = os.getenv("FRED_API_KEY")  # Recomendado
# o directamente para pruebas:
# API_KEY = "TU_API_KEY_AQUI"

⚠️ 共有コードやコミットに API key を絶対にハードコードしないでください。

---

レート制限

制限	値
1 分あたりのリクエスト数	120 req/min
1 日あたりのリクエスト数	無制限（明示的な日次制限なし）
1 リクエストあたりの最大観測値数	100,000
1 リクエストあたりの最大系列数	エンドポイントによります（通常は 1）
料金	完全無料

推奨事項

• レスポンスをローカルにキャッシュします（マクロ経済データの更新頻度は低いため）
• observation_start と observation_end を使用して範囲を限定します
• HTTP 429（Too Many Requests）を受信した場合は、バックオフ付きの再試行を実装します
• 多数の系列をダウンロードする場合は、リクエストの間隔を 0.5 秒空けます

---

主なエンドポイント

系列と観測値

エンドポイント	説明	認証
GET /fred/series/observations	系列の過去の値	API Key
GET /fred/series/search	テキストで系列を検索	API Key
GET /fred/series	系列のメタデータ	API Key
GET /fred/series/categories	系列のカテゴリ	API Key
GET /fred/series/release	系列に関連付けられたリリース	API Key

カテゴリとリリース

エンドポイント	説明
GET /fred/category	カテゴリの情報
GET /fred/category/children	サブカテゴリ
GET /fred/category/related	関連カテゴリ
GET /fred/category/series	カテゴリ内の系列
GET /fred/release	リリースの情報
GET /fred/release/dates	リリースの日付
GET /fred/release/series	リリース内の系列

タグ（ラベル）

エンドポイント	説明
GET /fred/tags	タグを検索
GET /fred/related_tags	関連タグ
GET /fred/tags/series	特定のタグが付いた系列
GET /fred/series/tags	系列のタグ

ソース

エンドポイント	説明
GET /fred/sources	データソースの一覧
GET /fred/source	ソースの情報

カレンダーマップ

エンドポイント	説明
GET /fred/series/updates	最近更新された系列
GET /fred/seasonal/adjustments	季節調整のオプション

---

レスポンス形式

デフォルトでは XML を返します。&file_type=json で変更できます。

{
  "realtime_start": "2026-06-01",
  "realtime_end": "2026-06-01",
  "observation_start": "1954-07-01",
  "observation_end": "2026-06-01",
  "units": "lin",
  "count": 864,
  "observations": [
    {
      "realtime_start": "2026-06-01",
      "realtime_end": "2026-06-01",
      "date": "1954-07-01",
      "value": "."
    },
    {
      "realtime_start": "2026-06-01",
      "realtime_end": "2026-06-01",
      "date": "1954-10-01",
      "value": "126.8"
    }
  ]
}

注： 値 "." はデータが利用できない（N/A）ことを示します。

---

シリーズのカテゴリ

FRED シリーズはカテゴリ（数値 ID）で整理されています。

ID	カテゴリ	例
0	すべてのカテゴリ（ルート）	—
32991	人口、雇用、労働市場	UNRATE, PAYEMS, NFP
32992	国民所得・生産勘定	GDP, GDPC1, GNP
32993	消費者物価指数（CPI）	CPIAUCSL, CPILFESL
32994	生産者物価指数（PPI）	PPIACO, PPIFIS
32995	金利	FEDFUNDS, DGS10, DGS2
32996	貨幣、銀行、金融	M2SL, M1SL, TOTBKCR
32997	国際貿易	BOPGSTB
33000	米国の地域データ	州別統計
33001	学術データ	学術データ

全リファレンスはreferences/SERIES_REFERENCE.mdを参照してください。

---

クイックスタート

1. シリーズをダウンロードする（Python）

import requests

API_KEY = "TU_API_KEY"
url = "https://api.stlouisfed.org/fred/series/observations"
params = {
    "series_id": "GDP",
    "api_key": API_KEY,
    "file_type": "json",
    "observation_start": "2020-01-01",
    "observation_end": "2025-12-31"
}
r = requests.get(url, params=params)
data = r.json()
for obs in data["observations"]:
    if obs["value"] != ".":
        print(obs["date"], obs["value"])

2. キーワードでシリーズを検索する

params = {
    "api_key": API_KEY,
    "file_type": "json",
    "search_text": "inflation",
    "search_type": "full_text",  # o "series_id"
    "limit": 10
}
r = requests.get("https://api.stlouisfed.org/fred/series/search", params=params)

3. pandas を使う

import pandas as pd
import requests

def fetch_fred(series_id, api_key, start="2020-01-01"):
    url = "https://api.stlouisfed.org/fred/series/observations"
    params = {"series_id": series_id, "api_key": api_key,
              "file_type": "json", "observation_start": start}
    r = requests.get(url, params=params)
    df = pd.DataFrame(r.json()["observations"])
    df["date"] = pd.to_datetime(df["date"])
    df["value"] = pd.to_numeric(df["value"], errors="coerce")
    return df.set_index("date")["value"]

gdp = fetch_fred("GDP", API_KEY)
cpi = fetch_fred("CPIAUCSL", API_KEY)
fedfunds = fetch_fred("FEDFUNDS", API_KEY)

---

利用可能なスクリプト

スクリプト	説明
fetch_series.py	1 つ以上の FRED シリーズを CSV/JSON/Parquet でダウンロードします
search_series.py	テキスト、カテゴリ、タグで FRED シリーズを検索します
download_multiple.py	カテゴリ別に定義済みのシリーズを一括ダウンロードします

---

主要シリーズ（ヘッドライン）

シリーズ	説明	頻度
GDP	名目 GDP（10 億ドル）	四半期
GDPC1	実質 GDP（連鎖方式の 10 億ドル）	四半期
CPIAUCSL	総合 CPI（CPI All Items）	月次
CPILFESL	コア CPI	月次
PCEPILFE	コア PCE	月次
FEDFUNDS	フェデラルファンド金利	日次
DFF	フェデラルファンド実効金利	日次
DGS10	10 年米国債利回り	日次
DGS2	2 年米国債利回り	日次
T10Y2Y	10 年物と 2 年物のスプレッド（逆イールドカーブ）	日次
UNRATE	失業率	月次
PAYEMS	非農業部門雇用者数（Nonfarm Payrolls）	月次
M2SL	M2 マネーサプライ	月次
M1SL	M1 マネーサプライ	月次
VIXCLS	VIX（S&P 500 のボラティリティ）	日次
BAA10Y	BAA と 10 年物のスプレッド（信用スプレッド）	日次
TOTALSA	小売売上高	月次
INDPRO	鉱工業生産	月次
HOUST	住宅着工件数	月次
MORTGAGE30US	30 年住宅ローン金利	週次

全リファレンス：references/SERIES_REFERENCE.md（100 以上のシリーズを掲載）。

---

ベストプラクティス

1. データをキャッシュする：マクロ経済データは頻繁には変わらないため、ローカルに Parquet/CSV で保存します
2. file_type=jsonを使用する：XML よりも解析が簡単です
3. 日付でフィルタリングする：observation_startを使用して、不要な過去データのダウンロードを避けます
4. "."の値を処理する：データが利用できないことを示します（NaN）
5. レート制限：120 req/min = 最低でも 0.5 秒に 1 リクエスト
6. API キー：環境変数FRED_API_KEYを使用します
7. 出典を明記する：商用アプリでは「This product uses the FRED API but is not endorsed or certified by the Federal Reserve Bank of St. Louis」を必ず含めてください