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

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

CalendarEventByCountryは、MetaTrader 5（MQL5）の組み込み経済指標カレンダーから、指定した国・地域に関連するイベント情報を一括で取得するための関数です。

FXのシステムトレード（EA）開発において、この関数は「特定の国の重要指標発表前後にトレードを停止させる」といったリスク管理や、「指標結果に基づいたファンダメンタルズトレード」を実装する際の入り口として非常に重要です。

実務での活用例

• 米雇用統計時の自動停止: “US”（米国）を指定してイベント一覧を取得し、重要度が「高」の指標がある場合にエントリーを制限する。
• 通貨ペアごとのフィルタリング: 例えばEURJPYを取引する場合、”EU”（欧州）と”JP”（日本）の両方のイベントを取得し、相場変動リスクを事前に察知する。

つまずきやすいポイント

初心者が特につまずきやすいのは、この関数が取得するのはあくまで「イベントの定義（名前や重要度など）」であり、「その指標の具体的な数値（前回値、予想値、発表値）」ではないという点です。数値データを取得するには、ここで得られた「イベントID」を元に別の関数（CalendarValueByEventなど）を呼び出す必要があります。

2. 構文と戻り値

関数の定義

int  CalendarEventByCountry(
   const string           country_code,     // 国のコード (ISO 3166-1 alpha-2)
   MqlCalendarEvent&      events[]          // イベントを受け取る配列
   );

パラメーター解説

1. country_code: 取得したい国の2文字コードを文字列で指定します（例: “US”, “JP”, “EU”, “GB”, “AU”）。
2. events[]: MqlCalendarEvent 構造体の配列です。関数が成功すると、この配列にイベント情報が格納されます。

戻り値

• 成功した場合：取得したイベントの要素数を返します。
• 失敗した場合：-1 を返します。

MqlCalendarEvent構造体の主なメンバ

この構造体には、以下のようなデータが含まれています。
* id: イベントの一意なID（数値を取得する際に使用）
* type: イベントの種類（指標、祝日など）
* name: イベントの名称（日本語設定なら日本語で取得可能）
* importance: 重要度（0:無し、1:低、2:中、3:高）
* currency: 通貨コード

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

以下のサンプルは、米国の重要指標（重要度：高）の名称とIDを一覧表示するスクリプトです。これを応用すれば、特定の指標の有無を判定するロジックが組めます。

//+------------------------------------------------------------------+
//|                                     CheckUSHighImportance.mq5    |
//+------------------------------------------------------------------+
void OnStart()
{
   // イベント情報を格納する配列
   MqlCalendarEvent events[];

   // 米国("US")のイベントをすべて取得
   int count = CalendarEventByCountry("US", events);

   if(count > 0)
   {
      PrintFormat("米国に関連するイベントを %d 件取得しました。", count);

      for(int i = 0; i < count; i++)
      {
         // 重要度が「高(CALENDAR_IMPORTANCE_HIGH)」のものだけを抽出
         if(events[i].importance == CALENDAR_IMPORTANCE_HIGH)
         {
            PrintFormat("重要指標発見: [ID] %d [名称] %s", 
                        events[i].id, 
                        events[i].name);
         }
      }
   }
   else if(count == 0)
   {
      Print("指定した国のイベントは見つかりませんでした。");
   }
   else
   {
      Print("エラーが発生しました。エラーコード:", GetLastError());
   }
}

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

1. 国コードは必ず「大文字」で

country_codeに指定する文字列（”US”など）は、内部的に大文字で管理されています。小文字で “us” と指定すると正しく取得できない場合があるため、常に大文字で記述する癖をつけましょう。

2. 配列の動的確保

サンプルコードのように MqlCalendarEvent events[]; と宣言すれば、関数内で自動的にメモリが割り当てられます。しかし、ループ内で何度も呼び出す場合は、メモリ効率を考慮して ArrayFree() を活用し、適切にリセットを行うのがクオンツエンジニアとしての作法です。

3. 歴史的データとの混同

CalendarEventByCountry で取得できるのは「どのような指標が存在するか」というリストです。「明日何時に発表があるか」というスケジュール（時間軸）の情報は CalendarValueByCountry という別の関数を使用する必要があるため、混同しないように注意してください。

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

経済指標を利用したロジックを組む際、多くのエンジニアが見落としがちなのが「実行環境のネットワークレイテンシ（遅延）」です。経済指標の発表直後は世界中の注文が集中し、1ミリ秒（0.001秒）を争う極限の状態となります。

自宅のPC環境で自動売買を行う場合、家庭用回線の不安定さや物理的なサーバー距離によって、どれほど優れたアルゴリズムであっても致命的なスリッページ（約定価格のズレ）や注文拒否を回避できません。プロフェッショナルなクオンツの世界では、ブローカーのサーバーと同じデータセンター内、あるいは至近距離に位置する専用のVPS（仮想専用サーバー）を利用することが、戦略の優位性を保つための最低条件です。インフラへの投資を惜しむことは、アルゴリズムそのものを無効化させてしまうのと同義であることを肝に銘じておきましょう。