economic-calendar-fetcher

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

概要

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

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

主な機能:

• 指定した期間の経済イベントを取得（最大 90 日間）
• 柔軟な API キーの指定方法をサポート（環境変数または CLI 引数）
• 影響度、国、イベント種別によるフィルタリング（フィルタリングはアシスタントが実行）
• フィルタリングされた結果を、影響分析を含む構造化された Markdown レポートとして提示（アシスタントが生成、スクリプトは生成しない）
• 迅速な市場見通しのために、デフォルトで今後 7 日間を対象

データソース:

• FMP 経済カレンダー API: https://financialmodelingprep.com/api/v3/economic_calendar
• 主要経済圏をカバー: 米国、EU、英国、日本、中国、カナダ、オーストラリア
• イベント種別: 中央銀行の決定、雇用、インフレ、GDP、貿易、住宅、調査

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

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

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. 許容: 単発の実行には --api-key CLI 引数を使用します
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."

ステップ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日であることを確認
• 過去の日付をクエリする場合は警告

ステップ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 プランのアップグレードを提案
• ネットワークエラー → 接続を確認してスクリプトを再実行
• 無効な日付形式 → 正しい形式の例を提示

ステップ4: イベントを解析してフィルタリングする

スクリプトからの JSON レスポンスを処理します:

1. イベントデータを解析: API レスポンスからすべてのイベントを抽出
2. ユーザーが指定したフィルターを適用:
   • 影響度レベル: "High"、"Medium"、"Low"
   • 国: "US"、"EU"、"JP"、"CN" など
   • イベントタイプ: FOMC、CPI、雇用、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. 影響度インジケーター: (High Impact)、(Medium Impact)、(Low Impact) のラベルを使用します
3. タイムゾーンの明確化: 常に UTC を指定します。ET/PT への変換は、米国の DST カレンダーに基づいてアシスタントが実行します
4. データの完全性: 利用可能なすべてのフィールドを含めます（previous、estimate、過去の場合は actual）
5. Null の扱い: null 値には「N/A」または「No estimate」を表示します
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/api/v3/economic_calendar
• 認証: API キーが必要（無料枠: 1 日 250 リクエスト）
• 最大日付範囲: 1 リクエストあたり 90 日
• レスポンス形式: イベントオブジェクトの JSON 配列
• レート制限: 1 秒あたり 5 リクエスト（無料枠）

イベントの対象範囲:

• 主要経済圏: 米国、EU、英国、日本、中国、カナダ、オーストラリア、スイス
• イベントカテゴリ: 金融政策、雇用、インフレ、GDP、貿易、住宅、調査
• 更新頻度: リアルタイム（イベントは予定どおりに追加・更新されます）
• 過去データ: 過去のイベントについて actual 値を含めて利用可能

使用上のヒント:

1. 結果をキャッシュして API 呼び出しを最小限に抑えます（イベントは一度予定されるとほとんど変更されません）
2. リクエスト効率を最適化するには 7〜30 日の範囲でクエリします
3. 6 か月より先はクエリしないでください（データが乏しく、日付が推測的です）
4. 時間変更を捉えるため、今後 1 週間分のキャッシュを毎日更新します
5. リアルタイムのイベント監視には、より短い範囲（1〜7 日）を使用します

エラー処理:

• API キーエラー: 無料キーの取得方法について明確なガイダンスをユーザーに提示します
• レート制限（429）: 待機するか FMP のプランアップグレードを提案します。待機後にスクリプトを再実行してください
• ネットワーク障害: 接続を確認して再実行します。スクリプトには自動リトライやキャッシュはありません
• 無効な日付: 役立つエラーメッセージを伴う検証を行います