【MQL5】CalendarValueHistory関数の使い方と自動売買実装コード

1. CalendarValueHistory関数の概要と実務での活用法

MQL5のCalendarValueHistory関数は、経済指標カレンダーの過去の発表結果（実績値、予測値、前回値など）を取得するための非常に強力な関数です。MetaTrader 5（MT5）に組み込まれた経済カレンダー機能へアクセスし、指定した期間内に行われた指標発表の詳細を配列としてまとめて取得できます。

実務での活用法

システムトレード（EA）開発において、この関数は主に以下の3つの目的で活用されます。

1. 経済指標時のトレード制限: 雇用統計や政策金利発表などの高ボラティリティが予想される時間帯に、新規エントリーを停止させる、または既存ポジションをクローズするフィルターとして利用します。
2. 指標結果に基づいたロジック: 「実績値が予想値よりも大幅に良かった場合に順張りする」といった、ファンダメンタルズ要素を組み込んだ自動売買の実装を可能にします。
3. バックテストの精度向上: 過去の指標発表タイミングとチャートの動きを照らし合わせ、特定の指標がロジックにどのような影響を与えたかを分析する際に不可欠です。

初心者・中級者がつまずきやすいポイントとして、「取得できるデータはあくまでMT5サーバーに配信されたもの」であるという点があります。ブローカーによってカレンダーの更新頻度やデータ量が異なる場合があるため、実装時には「データが存在しない場合」の例外処理が必須となります。

2. 構文と戻り値

CalendarValueHistory関数の基本的な構文は以下の通りです。

int  CalendarValueHistory(
   MqlCalendarValue&  values[],          // 値を受け取る配列
   datetime           from,              // 取得開始日時
   datetime           to=0,              // 取得終了日時
   const string       country_code=NULL, // 国のISOコード (例: "US", "JP")
   const string       currency=NULL      // 通貨コード (例: "USD", "JPY")
   );

パラメーター解説

• values[]: 取得したデータが格納される MqlCalendarValue 構造体の配列です。
• from: データを取得する期間の開始時間を指定します。
• to: 終了時間を指定します。0 を指定すると、現在までのすべての値を取得します。
• country_code: 特定の国（米国なら “US” など）に限定する場合に使用します。
• currency: 特定の通貨に関連する指標に限定する場合に使用します。

戻り値

• 成功した場合、取得されたレコードの数を返します。
• 失敗した場合は -1 を返します。エラーの詳細は GetLastError() 関数で確認できます。

3. 具体的な使い方・実践サンプルコード

以下は、過去24時間以内に発表された米国の経済指標の結果を取得し、エキスパートログに出力するシンプルなスクリプトの例です。

void OnStart()
{
   // 指標データを格納する配列
   MqlCalendarValue values[];

   // 期間の設定（例：現在から24時間前まで）
   datetime to = TimeCurrent();
   datetime from = to - PeriodSeconds(PERIOD_D1);

   // 米国(US)の経済指標履歴を取得
   // 戻り値は取得できたデータの個数
   int count = CalendarValueHistory(values, from, to, "US");

   if(count > 0)
   {
      PrintFormat("%d 件の指標データを取得しました。", count);

      for(int i = 0; i < count; i++)
      {
         // 各指標の詳細情報を取得
         MqlCalendarEvent event;
         CalendarEventById(values[i].event_id, event);

         string eventName = event.name;
         datetime time = values[i].time;
         long actual = values[i].actual_value;
         long forecast = values[i].forecast_value;

         // 取得した情報をログに出力
         PrintFormat("指標名: %s | 発表時間: %s | 実績: %ld | 予想: %ld", 
                     eventName, TimeToString(time), actual, forecast);
      }
   }
   else if(count == 0)
   {
      Print("指定した期間内に指標データはありませんでした。");
   }
   else
   {
      Print("エラーが発生しました。エラーコード:", GetLastError());
   }
}

4. 使用上の注意点とよくあるエラー

1. 構造体の取り違え

MqlCalendarValue には「指標の結果（数値）」が格納されますが、「指標の名前」や「重要度」は MqlCalendarEvent 構造体に格納されています。values[i].event_id を使って CalendarEventById 関数を呼び出し、イベントの詳細を別途取得する必要がある点に注意してください。

2. 時間軸（タイムゾーン）の不一致

経済カレンダーの時間は通常 UTC（協定世界時） で管理されています。MT5のサーバー時間（通常はGMT+2/DST+3など）と乖離があるため、時間比較を行う際は必ず TimeGMT() を利用するか、時差を考慮した計算を行ってください。

3. 初回実行時のデータ未取得

MT5を起動した直後や、初めてこの関数を呼び出す際は、ターミナルがデータをキャッシュしていないため 0 が返ってくることがあります。実務では、データが取得できるまで数回リトライするか、初期化時にあらかじめデータを呼び出しておく処理を入れるのが一般的です。

5. 【重要】自動売買における約定スピードと環境の罠

どれほど高度なアルゴリズムを CalendarValueHistory で組み上げたとしても、実行環境が貧弱であればすべてが無に帰します。特に経済指標発表時は、市場の流動性が一瞬で枯渇し、価格が数ミリ秒単位で激しく動きます。自宅のPCや一般的な光回線を利用した環境では、ネットワークの物理的な距離に起因する「レイテンシ（遅延）」が発生し、プログラムが売買指示を出した瞬間の価格から大きく乖離した場所で約定（スリッページ）してしまいます。

この遅延は、システムトレーダーにとって致命的な「隠れたコスト」です。プロのクオンツエンジニアが極限まで約定スピードを追求するのは、コンマ数秒の遅れが利益を損失に変えることを知っているからです。勝率を安定させ、設計通りのパフォーマンスを発揮させるためには、ブローカーの取引サーバーと物理的に近い距離に設置された専用のVPS（仮想専用サーバー）の利用が必須条件となります。安定した電源、24時間365日の稼働、そして圧倒的な低レイテンシ環境を整えることこそが、技術力以上にトレードの成否を分ける境界線と言っても過言ではありません。