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

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

CalendarValueHistoryByEventは、MetaTrader 5（MQL5）の経済カレンダー機能にアクセスし、特定の経済指標（イベントID指定）に絞って過去の発表データ（実績値、予想値、前回値）を配列として取得するための関数です。

実務レベルの開発において、この関数は非常に重要な役割を果たします。例えば、「米雇用統計（NFP）の発表直後に、実績値が予想値よりも乖離していた場合のみエントリーする」といったイベントドリブン・ストラテジーを構築する際に不可欠です。

多くの開発者がつまずくポイントは、「どのイベントがどのIDを持っているか」を事前に把握する必要がある点と、データが更新されるタイミングの処理です。単純にチャートの価格だけを見てトレードする手法とは異なり、ファンダメンタルズデータを数値としてEAに読み込ませることで、ロジックの優位性を飛躍的に高めることが可能になります。

2. 構文と戻り値

この関数の構文は以下の通りです。

bool  CalendarValueHistoryByEvent(
   ulong                event_id,          // イベントID（経済指標の識別番号）
   MqlCalendarValue&    values[],          // データを格納する構造体配列
   datetime             datetime_from,     // 取得開始日時
   datetime             datetime_to=0      // 取得終了日時（0の場合は現在まで）
   );

パラメーター解説

• event_id: 取得したい特定の経済指標のIDです。あらかじめCalendarEventGetなどで取得しておくか、特定の指標のIDを特定して指定します。
• values[]: 取得したデータが格納される MqlCalendarValue 構造体の配列です。
• datetime_from / datetime_to: データを取得する期間を指定します。

戻り値

• 成功した場合は true、失敗した場合は false を返します。
• 失敗の詳細は GetLastError() 関数で確認できます。

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

以下は、特定のイベントID（例として米雇用統計などを想定）を指定し、その過去の発表結果を取得してエキスパートアドバイザーの操作ログに出力するサンプルです。

//+------------------------------------------------------------------+
//|                                     CalendarHistoryExample.mq5   |
//+------------------------------------------------------------------+
#property strict

void OnStart()
{
    // 例：取得したいイベントID（実際には適切なIDを指定してください）
    // ※IDは CalendarEventGet 関数などで取得可能です
    ulong targetEventID = 840030016; // これは一例（米国雇用統計のIDなど）

    MqlCalendarValue values[]; // データを格納する配列
    datetime fromDate = D'2023.01.01 00:00'; // 2023年初頭から
    datetime toDate = 0; // 現在まで

    // 指定したイベントの履歴を取得
    if(CalendarValueHistoryByEvent(targetEventID, values, fromDate, toDate))
    {
        PrintFormat("イベントID %d のデータを %d 件取得しました。", targetEventID, ArraySize(values));

        for(int i = 0; i < ArraySize(values); i++)
        {
            // 各発表時のデータを解析
            datetime releaseTime = values[i].time;      // 発表時間
            long actual = values[i].actual_value;       // 実績値
            long forecast = values[i].forecast_value;   // 予想値

            // 値は特定の倍率で格納されているため、スケーリングが必要な場合があります
            // 実際の実務では values[i].HasActualValue() などで値の有無を確認します

            PrintFormat("[%d] 発表日時: %s, 実績: %ld, 予想: %ld", 
                        i, TimeToString(releaseTime), actual, forecast);
        }
    }
    else
    {
        Print("データの取得に失敗しました。エラーコード: ", GetLastError());
    }
}

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

1. イベントIDの特定:
   CalendarValueHistoryByEvent を使うには、まずその指標の event_id を知る必要があります。全てのイベントをループで回して CalendarEventGet で名称を確認し、目的のIDを特定する前処理が必要になることが一般的です。

2. データのスケーリング:
   MqlCalendarValue 構造体で取得できる actual_value や forecast_value は、そのままの数値ではなく、10の累乗倍された整数として格納されている場合があります。正しい数値を表示するには、CalendarEventGet で取得できる MqlCalendarEvent 構造体の multiplier（倍率）を確認し、計算し直す必要があります。

3. 初回のデータ同期:
   MT5を起動した直後などは、カレンダーデータベースがローカルに同期されていないことがあります。関数が false を返したり、空の配列を返したりする場合は、少し待機してから再試行するロジックを組むのが安全です。

4. 構造体のフラグ確認:
   取得できたデータの中に必ずしも「予想値」や「実績値」が入っているとは限りません。impact_type や revision などのフラグを確認し、データが有効かどうかを判定するようにしてください。

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

経済カレンダーを利用したイベントドリブン・トレードにおいて、最も致命的なリスクは「物理的なネットワーク遅延」です。指標発表時は一瞬で価格が数十から数百ピップス跳躍します。もし、あなたが自宅のPCや一般的な光回線でEAを稼働させている場合、指標データを検知してから注文がサーバーに届くまでに数百ミリ秒のラグが発生し、最悪の価格で約定する（スリッページ）ことになります。

プロのクオンツエンジニアにとって、このレイテンシ（遅延）の排除はロジック構築と同じくらい重要です。極限まで約定スピードを高め、滑りによる損失を最小限に抑えるには、取引サーバーに物理的に近いデータセンターに設置された「専用のVPS（仮想専用サーバー）」の使用が絶対条件です。ネットワークの「0.1秒の差」が、月間の収支をプラスからマイナスへ転じさせるのがFX自動売買のシビアな現実です。