economic-calendar-fetcher

経済カレンダー取得ツール

概要

Financial Modeling Prep（FMP）の Economic Calendar API から、今後予定されている経済イベントやデータ発表を取得します。このスキルでは、中央銀行の金融政策決定、雇用統計、インフレデータ（CPI／PPI）、GDP 発表、小売売上高、製造業データなど、金融市場に影響を与えるその他のイベントを含む、予定されている経済指標を取得します。

このスキルは Python スクリプトを使用して FMP API に問い合わせ、生の JSON またはテキスト出力を返します。アシスタントがその後イベントを絞り込み、市場への影響を評価し、予定されている各イベントについて時系列の Markdown レポートを生成します。ファイルは自動生成されません。

主な機能：

• 指定した期間（最大 90 日）の経済イベントを取得
• 柔軟な API キーの指定に対応（環境変数または CLI 引数）
• 影響度、国、イベント種別で絞り込み（絞り込みはアシスタントが実施）
• 絞り込んだ結果を、影響分析を含む構造化 Markdown レポートとして提示（スクリプトではなくアシスタントが生成）
• 市場の見通しをすばやく確認できるよう、デフォルトでは今後 7 日間を対象とする

データソース：

• FMP Economic Calendar API：https://financialmodelingprep.com/stable/economic-calendar（「economic」は単数形です）
• 主要経済圏を対象とします：米国、EU、英国、日本、中国、カナダ、オーストラリア
• イベント種別：中央銀行の決定、雇用、インフレ、GDP、貿易、住宅、調査
• 注：従来の api/v3/economic_calendar エンドポイントは、FMP により 2025-08-31 に完全に廃止され、現在は 403 Legacy Endpoint を返します。フォールバックとしても使用しないでください。

このスキルを使用する場面

ユーザーから次のようなリクエストがあった場合に、このスキルを使用します。

1. 経済カレンダーに関する問い合わせ：

   • 「今週はどのような経済イベントがありますか？」
   • 「今後 2 週間の経済カレンダーを見せてください」
   • 「次の FOMC 会合はいつですか？」
   • 「来月、主要な経済データの発表はありますか？」

2. 市場イベントの計画：

   • 「今週の市場で注目すべきことは何ですか？」
   • 「影響の大きい経済指標の発表は予定されていますか？」
   • 「次の雇用統計／CPI 発表／GDP 発表はいつですか？」

3. 特定の期間に関するリクエスト：

   • 「1 月 1 日から 1 月 31 日までの経済イベントを取得してください」
   • 「2025 年第 1 四半期の経済カレンダーには何が載っていますか？」

4. 特定の国に関する問い合わせ：

   • 「来週発表される米国の経済指標を見せてください」
   • 「ECB のイベントは何が予定されていますか？」
   • 「日本のインフレデータの発表はいつですか？」

このスキルを使用しないでください：

• 過去の経済イベント（過去の分析には market-news-analyst を使用してください）
• 企業の決算カレンダー（このスキルでは決算を対象外としています）
• リアルタイムの市場データやライブの相場情報
• テクニカル分析やチャートの解釈

前提条件

• FMP API キー（必須）： https://financialmodelingprep.com で無料のキーを取得してください（1 日あたり 250 リクエスト）。FMP_API_KEY 環境変数で設定するか、スクリプトに --api-key を渡してください。
• Python 3.10 以降： skills/economic-calendar-fetcher/scripts/get_economic_calendar.py の実行に必要です。
• サードパーティパッケージ不要： スクリプトは Python 標準ライブラリのみを使用します。

ワークフロー

経済カレンダーの取得と分析は、以下の手順に従ってください。

ステップ 1：FMP API キーを取得する

API キーの有無を、優先順位に従って確認します。

1. 推奨： FMP_API_KEY 環境変数が設定されているか確認します。これにより、キーがセッションログに記録されるのを防げます。
2. 許容される方法： 1 回限りの実行では、CLI 引数 --api-key を使用します。
3. 非推奨： ユーザーにチャットへキーを貼り付けるよう求めること。セッションログにキーが残る可能性があります。
4. ユーザーが API キーを持っていない場合は、次の手順を案内します。
   • https://financialmodelingprep.com にアクセスする
   • 無料アカウントに登録する（1 日あたり 250 リクエストの上限）
   • API ダッシュボードに移動してキーを取得する

ユーザーとのやり取りの例：

User: "Show me economic events for next week"
Assistant: "I'll fetch the economic calendar. I'll use the FMP_API_KEY environment variable if it's set. Otherwise, please pass the key via --api-key when running the script."

Step 2: 日付範囲を決定する

ユーザーのリクエストに基づいて適切な日付範囲を設定します：

デフォルト（特定の日付の指定なし）： 今日から7日後まで 期間の指定あり： 指定された日付を使用します（形式を検証：YYYY-MM-DD） 最大範囲： 90日間（FMP API の制限）

例：

• 「来週」→ 今日から7日後まで
• 「今後2週間」→ 今日から14日後まで
• 「2025年1月」→ 2025-01-01 から 2025-01-31
• 「2025年第1四半期」→ 2025-01-01 から 2025-03-31

日付範囲を検証します：

• 開始日 ≤ 終了日であることを確認します
• 範囲が90日以内であることを確認します
• 過去の日付を照会する場合は警告します

Step 3: API 取得スクリプトを実行する

適切なパラメーターを指定して get_economic_calendar.py スクリプトを実行します：

基本的な使用方法（デフォルトで7日間）：

python3 skills/economic-calendar-fetcher/scripts/get_economic_calendar.py --api-key YOUR_KEY

特定の日付範囲を指定する場合：

python3 skills/economic-calendar-fetcher/scripts/get_economic_calendar.py \
  --from 2025-01-01 \
  --to 2025-01-31 \
  --api-key YOUR_KEY \
  --format json

環境変数を使用する場合（--api-key は不要）：

export FMP_API_KEY=your_key_here
python3 skills/economic-calendar-fetcher/scripts/get_economic_calendar.py \
  --from 2025-01-01 \
  --to 2025-01-07

スクリプトのパラメーター：

• --from：開始日（YYYY-MM-DD）- デフォルト：今日
• --to：終了日（YYYY-MM-DD）- デフォルト：今日 + 7日
• --api-key：FMP API キー（FMP_API_KEY 環境変数が設定されている場合は省略可能）
• --format：出力形式（json または text）- デフォルト：json
• --output：出力ファイルのパス（任意、デフォルト：stdout）

エラーと空の結果を処理します：

• 無効な API キー → キーを確認するようユーザーに依頼します
• レート制限超過（429）→ しばらく待つか、FMP のプランをアップグレードするよう提案します
• 制限されたエンドポイント（402 Payment Required）→ スクリプトは、現在の FMP サブスクリプションプランに Economic Calendar エンドポイントが含まれていないことを明示するエラーを発生させます。https://financialmodelingprep.com/ で FMP プランをアップグレードする必要があることをユーザーに伝えてください。これを「イベントなし」として扱わず、レガシー v3 エンドポイントにもフォールバックしないでください（2025-08-31 に廃止されており、403 Legacy Endpoint が返されます）。
• ネットワークエラー → 接続を確認してスクリプトを再実行します
• 無効な日付形式 → 正しい形式の例を提示します
• 妥当な現在または将来の日付範囲に対する空のリスト []： 現在のスクリプトバージョンでは、API から返される空のリストは実際に「イベントなし」を意味します。404 または制限されたエンドポイントの応答は、現在は [] に変換されず、明示的なエラーを発生させます。データが欠落している疑いがある場合は、エンドポイントの不具合と決めつけずに、日付範囲と API キーを再確認してください。

Step 4: イベントを解析してフィルタリングする

スクリプトからの JSON 応答を処理します：

1. イベントデータを解析する： API 応答からすべてのイベントを抽出します
2. 指定された場合はユーザーフィルターを適用する：
   • 影響度：「High」、「Medium」、「Low」
   • 国：「US」、「EU」、「JP」、「CN」など
   • イベントの種類：FOMC、CPI、Employment、GDP など
   • 通貨：USD、EUR、JPY など

フィルターの例：

• 「影響度の高いイベントのみ表示」→ impact == "High" でフィルタリング
• 「米国のイベントのみ」→ country == "US" でフィルタリング
• 「中央銀行の決定」→ イベント名から "Rate"、"Policy"、"FOMC"、"ECB"、"BOJ" を検索

イベントデータ構造：

{
  "date": "2025-01-15 14:30:00",
  "country": "US",
  "event": "Consumer Price Index (CPI) YoY",
  "currency": "USD",
  "previous": 2.6,
  "estimate": 2.7,
  "actual": null,
  "change": null,
  "impact": "High",
  "changePercentage": null
}

ステップ 5：市場への影響を評価する

各イベントの市場的重要性を評価します：

影響度の分類（FMP に基づく）：

• 影響度：高： 市場を大きく動かすイベント

  • FOMC の金利決定、ECB／BOJ の政策会合
  • 非農業部門雇用者数（NFP）、CPI、GDP
  • 市場では通常、日中に 0.5～2％以上のボラティリティが見られます

• 影響度：中： 重要ですが、ボラティリティは比較的低いイベント

  • 小売売上高、鉱工業生産
  • PMI 調査、消費者信頼感
  • 住宅関連データ、耐久財受注

• 影響度：低： 影響の小さい指標

  • 週間失業保険申請件数（極端な値でない場合）
  • 地域の製造業調査
  • 重要度の低い入札結果

追加の背景要因：

1. 現在の市場の注目点：

   • インフレ率が高い環境 → CPI／PPI の重要性が高まります
   • 景気後退への懸念 → 雇用データがより重要になります
   • 利下げ観測 → 中央銀行の会合が極めて重要になります

2. サプライズの可能性：

   • 予想値と前回値を比較します
   • 予想される変化が大きいほど、注目度が高まります
   • コンセンサスの不確実性が高いほど、影響が大きくなる可能性があります

3. イベントの集中：

   • 同日に関連イベントが複数あると、影響が増幅します
   • 例：CPI ＋ 小売売上高 ＋ FRB 講演 ＝ 影響度が非常に高い日

4. 今後への重要性：

   • このイベントは今後の中央銀行の決定に影響しますか？
   • 暫定値ですか、それとも確報値ですか？
   • このデータは改定されますか？

ステップ 6：出力レポートを生成する

担当範囲： スクリプトは生の JSON またはテキストを出力します。このステップは、スクリプトの出力を使ってアシスタントが実行します。Markdown ファイルは自動生成されません。結果はチャットに表示され、リクエストに応じて reports/ に保存できます。

次のセクションを含む、構造化された Markdown レポートを作成します：

レポートヘッダー：

# Economic Calendar
**Period:** [Start Date] to [End Date]
**Report Generated:** [Timestamp]
**Total Events:** [Count]
**High Impact Events:** [Count]

イベント一覧（時系列順）：

各イベントについて、次の情報を記載します：

## [Date] - [Day of Week]

### [Event Name] ([Impact Level])
- **Country:** [Country Code] ([Currency])
- **Time:** [HH:MM UTC]
- **Previous:** [Value]
- **Estimate:** [Consensus Forecast]
- **Impact Assessment:** [Your analysis]

**Market Implications:**
[2-3 sentences on why this matters, what markets watch for, typical reaction patterns]

---

イベント記載例：

## 2025-01-15 - Wednesday

### Consumer Price Index (CPI) YoY (High Impact)
- **Country:** US (USD)
- **Time:** 14:30 UTC (8:30 AM ET)
- **Previous:** 2.6%
- **Estimate:** 2.7%
- **Impact Assessment:** Very High - Core inflation metric for Fed policy decisions

**Market Implications:**
CPI reading above estimate (>2.7%) likely strengthens hawkish Fed expectations, potentially pressuring equities and supporting USD. Reading at or below 2.7% could reinforce disinflation narrative and support risk assets. Options market pricing 1.2% S&P 500 move on release day.

---

概要セクション：

最後に分析の概要を追加します：

## Key Takeaways

**Highest Impact Days:**
- [Date]: [Events] - [Combined impact rationale]
- [Date]: [Events] - [Combined impact rationale]

**Central Bank Activity:**
- [Summary of any scheduled Fed/ECB/BOJ meetings or speeches]

**Major Data Releases:**
- Employment: [NFP, Unemployment Rate dates]
- Inflation: [CPI, PPI dates]
- Growth: [GDP, Retail Sales dates]

**Market Positioning Considerations:**
[2-3 bullets on how traders might position around these events]

**Risk Events:**
[Highlight any particularly high-uncertainty or surprise-potential events]

フィルターに関する注記：

ユーザーが特定のフィルターを指定した場合は、冒頭に記載します：

**Filters Applied:**
- Impact Level: High only
- Country: US
- Events shown: [X] of [Y] total events in date range

出力：

• 結果はチャットに表示されます。ファイルは自動生成されません。
• 生の JSON／テキストデータを保存するには、スクリプトの実行時に --output reports/economic_calendar_[START]_to_[END].json を使用します。
• Markdown レポートを保存するには、チャットで生成した後、アシスタントに reports/ への書き込みを依頼します。

アシスタントが生成するレポートの形式

Markdown の構成要件：

1. 時系列順： イベントを日時順（早いものから）に並べます
2. 影響度の表示： （影響度：高）、（影響度：中）、（影響度：低）のラベルを使用します
3. タイムゾーンの明示： 必ず UTC を指定します。ET／PT への変換は、アシスタントが米国の夏時間カレンダーに基づいて行います
4. データの完全性： 利用可能なすべての項目（前回値、予想値、過去の場合は実績値）を含めます
5. NULL 値の処理： NULL 値は「該当なし」または「予想値なし」と表示します
6. 影響度の評価： 影響度が高または中のイベントには、必ず市場への影響の分析を含めます

表形式の選択肢（一覧が多い場合）：

| Date/Time (UTC) | Event | Country | Impact | Previous | Estimate | Assessment |
|-----------------|-------|---------|--------|----------|----------|------------|
| 01-15 14:30 | CPI YoY | US | High | 2.6% | 2.7% | Core inflation metric |

言語： すべてのレポートは英語で作成します

リソース

Python スクリプト：

• skills/economic-calendar-fetcher/scripts/get_economic_calendar.py：CLI インターフェースを備えたメインの API 取得スクリプト

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

• references/fmp_api_documentation.md：FMP Economic Calendar API の完全なリファレンス
  • 認証と API キーの管理
  • リクエストパラメーターと日付形式
  • レスポンスフィールドの定義
  • レート制限とエラー処理
  • キャッシュと効率化のベストプラクティス

API の詳細：

• 主なエンドポイント：https://financialmodelingprep.com/stable/economic-calendar（「economic」は単数形です。複数形の economics-calendar は無効な URL で、404 を返します）
• 廃止された旧エンドポイント：https://financialmodelingprep.com/api/v3/economic_calendar は、FMP により 2025-08-31 に停止され、現在は 403 Legacy Endpoint を返します。使用したり、フォールバック先にしたりしないでください。
• エンドポイントの利用制限に関する注意：stable Economic Calendar エンドポイントの利用には、有料の FMP サブスクリプションプランが必要な場合があります。API キーに利用権限がない場合、402 Payment Required が返されます。この場合、スクリプトは空のリストではなく、明確なエラーを表示します。
• 日付範囲に関する注意：レスポンスに、指定した from／to の範囲からわずかに外れた行が含まれる場合があります。取得後、解析した date でイベントをローカルにフィルタリングし、指定した日付範囲のイベントのみを報告してください。
• 認証：API キーが必要です（無料プラン：1 日あたり 250 リクエスト）
• 最大日付範囲：1 リクエストにつき 90 日
• レスポンス形式：イベントオブジェクトの JSON 配列
• レート制限：毎秒 5 リクエスト（無料プラン）

イベントの対象範囲：

• 主な経済圏：米国、EU、英国、日本、中国、カナダ、オーストラリア、スイス
• イベントカテゴリ：金融政策、雇用、インフレ、GDP、貿易、住宅、各種調査
• 更新頻度：リアルタイム（予定に応じてイベントが追加・更新されます）
• 過去データ：実績値を含む過去のイベントを利用できます

使用上のヒント：

1. API 呼び出しを最小限に抑えるため、結果をキャッシュしてください（予定が決まった後はイベントが変更されることはほとんどありません）
2. リクエストを効率よく行うには、7～30 日の範囲をクエリしてください
3. 6 か月を超える先の日付をクエリしないでください（データがまばらで、日付は推測に基づきます）
4. 時刻の変更を反映するため、今後 1 週間分のキャッシュを毎日更新してください
5. イベントをリアルタイムで監視する場合は、より短い範囲（1～7 日）を使用してください

エラー処理：

• イベント行の形式不正、フィールドの欠落や名称変更、型の変更、無効な UTC イベントタイムスタンプ、有限でない読み取り値がある場合、フォーマット処理や出力ファイルを開く前に失敗します。標準エラー出力には ZERO_RESULT_REASON=economic_calendar_schema_drift が含まれ、終了コードは 1 です。通常の null 読み取り値には対応しており、impact の "None" はプロバイダーが返す有効な文字列です。
• プロバイダーの配列が空の場合、イベントが予定されていない証拠ではなく、未検証です。標準エラー出力には ZERO_RESULT_REASON=empty_calendar_unverified が含まれ、終了コードは 1 です。既存の出力ファイルは保持されます。イベントがないカレンダーのレポートを書き込む前に、プロバイダーと日付範囲を確認してください。
• データ取得に失敗すると、ZERO_RESULT_REASON=calendar_fetch_failed が出力され、終了コード 1 で終了します。これには HTTP／プラン／ネットワークの失敗と、生成されたクライアントの一般的な失敗ケース（上限付きリトライ後の HTTP 200 の null または無効な JSON）が含まれます。null ではない配列以外の JSON レスポンスは、スキーマの不整合として扱われます。エラー診断では API キーがマスキングされ、形式不正なイベント値は出力されません。
• API キーのエラー：無料キーの取得方法を明確に案内します
• レート制限（429）：FMP のプランをアップグレードするか、しばらく待つよう案内します。待機後にスクリプトを再実行してください
• 利用制限のあるエンドポイント（402）：スクリプトは明確なエラーを発生させます。FMP のサブスクリプションプランではこのエンドポイントを利用できないため、ユーザーに https://financialmodelingprep.com/ でのアップグレードを案内してください。廃止された旧 v3 エンドポイント（2025-08-31 に廃止、403 を返します）にはフォールバックしないでください。
• ネットワーク障害：明確な Network error: ... メッセージを表示し、再実行してください。単一回の 429 リトライ、タイムアウト、呼び出しごとのレート制限は、同梱された生成済みの fmp_client.py が処理します（Issue #495）
• 実際の 404：スクリプトは空のリストを黙って返すのではなく、エラーを発生させるようになりました。イベントがゼロだと決めつけず、原因を調査してください。
• 無効な日付：わかりやすいエラーメッセージを表示して検証します