Nouveau : la formation trading algorithmique MQL5, MQL4 et ProRealTimeDécouvrir →

MQL5 · Avancé

Le calendrier économique en MQL5 : CalendarValueHistory et filtre d’annonces

Interroger le calendrier économique intégré à MetaTrader 5 depuis un EA : fonctions Calendar, structures MqlCalendarValue et MqlCalendarEvent, valeurs multipliées par un million, heure serveur, et un filtre complet pour suspendre le trading autour des annonces.

Mis à jour le 23 octobre 2026Lecture : 9 minPar Alix, OptiBot Trading

MetaTrader 5 intègre un calendrier économique consultable directement en MQL5, sans API externe. La fonction principale, CalendarValueHistory, remplit un tableau de structures MqlCalendarValue avec toutes les publications comprises entre deux dates, éventuellement filtrées par pays et par devise. Chaque valeur pointe, via son champ event_id, vers la description de l’événement (MqlCalendarEvent), que l’on obtient avec CalendarEventById et qui indique notamment son importance. Les heures sont exprimées en heure du serveur de trading, et les valeurs numériques (réel, prévision, précédent) sont stockées multipliées par un million. Avec ces trois fonctions, vous pouvez par exemple empêcher un EA d’ouvrir une position dans les minutes qui entourent une annonce importante sur l’une des devises du symbole.

Cette page fait partie de la rubrique MQL5 avancé. Le filtre construit ici s’intègre naturellement aux autres filtres d’un robot, présentés dans Filtres horaires, de spread et de volatilité.

Les fonctions du calendrier

FonctionRôle
CalendarCountriesliste des pays couverts
CalendarCountryByIddescription d’un pays à partir de son identifiant
CalendarEventByCountryévénements d’un pays (code pays)
CalendarEventByCurrencyévénements liés à une devise
CalendarEventByIddescription d’un événement à partir de son identifiant
CalendarValueByIdune valeur précise à partir de son identifiant
CalendarValueHistoryvaleurs sur une période, filtrables par pays et devise
CalendarValueHistoryByEventvaleurs d’un seul événement sur une période
CalendarValueLastnouvelles valeurs depuis un change_id, filtrables
CalendarValueLastByEventnouvelles valeurs d’un événement depuis un change_id

Les deux fonctions CalendarValueLast... sont conçues pour la surveillance en continu : elles ne renvoient que ce qui a changé depuis le dernier appel, ce qui évite de relire toute la période à chaque fois.

CalendarValueHistory en détail

La signature est : int CalendarValueHistory(MqlCalendarValue &values[], datetime datetime_from, datetime datetime_to=0, const string country_code=NULL, const string currency=NULL).

  • datetime_from doit être antérieur à datetime_to. Si datetime_to vaut 0, la fonction renvoie toutes les valeurs à partir de datetime_from, y compris les événements à venir.
  • country_code attend un code ISO 3166-1 alpha-2 ("US", "EU"…), currency un code de devise ("USD", "EUR"…). NULL et la chaîne vide signifient « pas de filtre ». Si les deux sont renseignés, ils se combinent par un ET logique.
  • La fonction renvoie le nombre de valeurs obtenues, ou -1 en cas d’erreur. Parmi les erreurs documentées : ERR_CALENDAR_TIMEOUT (5401) et ERR_CALENDAR_MORE_DATA (5400), qui signale qu’un tableau de taille fixe était trop petit et n’a été rempli que partiellement. Utilisez un tableau dynamique pour éviter ce cas.

Les structures : valeur, événement, pays

MqlCalendarValue décrit une publication : id, event_id, time, period, revision, actual_value, prev_value, revised_prev_value, forecast_value et impact_type. Les quatre champs numériques sont des entiers égaux à la valeur réelle multipliée par un million, et un champ non renseigné contient LONG_MIN. Plutôt que de diviser vous-même, utilisez les méthodes de la structure : HasActualValue(), HasForecastValue(), HasPreviousValue(), HasRevisedValue() indiquent si la valeur existe, et GetActualValue(), GetForecastValue(), GetPreviousValue(), GetRevisedValue() renvoient la valeur convertie, ou NaN si elle n’est pas renseignée.

MqlCalendarEvent décrit l’événement récurrent (par exemple un indice des prix publié chaque mois) : id, type, sector, frequency, time_mode, country_id, unit, importance, multiplier, digits, source_url, event_code et name. L’importance suit l’énumération ENUM_CALENDAR_EVENT_IMPORTANCE : CALENDAR_IMPORTANCE_NONE, CALENDAR_IMPORTANCE_LOW, CALENDAR_IMPORTANCE_MODERATE et CALENDAR_IMPORTANCE_HIGH.

Point souvent mal compris : un événement n’a pas de champ devise. La devise est portée par le pays (MqlCalendarCountry, champs currency et currency_symbol), auquel l’événement est rattaché par country_id. C’est pourquoi le filtre par devise se fait dans CalendarValueHistory et non en lisant l’événement.

Le piège de l’heure serveur

Toutes les heures du calendrier sont en heure du serveur de trading, celle que renvoie TimeTradeServer(), et non en heure locale. Comparez donc toujours l’heure d’une annonce à TimeTradeServer() (ou à TimeCurrent(), l’heure de la dernière cotation reçue du serveur). Le décalage horaire du serveur varie d’un courtier à l’autre et peut changer avec l’heure d’été ; ne codez jamais un décalage en dur. Les fonctions de temps sont détaillées dans Dates, heures et fuseaux.

Exemple complet : un filtre d’annonces importantes

L’EA suivant bloque toute nouvelle entrée lorsqu’une annonce d’importance élevée concernant la devise de base ou la devise de cotation du symbole est prévue dans la fenêtre choisie. La liste des annonces est rafraîchie toutes les quinze minutes, pas à chaque tick.

//+------------------------------------------------------------------+
//| NewsFilter.mq5 : blocage des entrées autour des annonces fortes  |
//+------------------------------------------------------------------+
input int InpMinutesBefore=30;   // blocage avant l'annonce (minutes)
input int InpMinutesAfter =15;   // blocage après l'annonce (minutes)

datetime g_news[];               // heures (serveur) des annonces importantes
datetime g_next_refresh=0;

//--- ajoute les annonces importantes d'une devise sur la période donnée
void LoadCurrency(const string currency,const datetime from,const datetime to)
  {
   MqlCalendarValue values[];
   int n=CalendarValueHistory(values,from,to,NULL,currency);
   if(n<0)
     {
      PrintFormat("CalendarValueHistory(%s) : erreur %d",currency,GetLastError());
      return;
     }
   for(int i=0;i<n;i++)
     {
      MqlCalendarEvent ev;
      if(!CalendarEventById(values[i].event_id,ev)) continue;
      if(ev.importance!=CALENDAR_IMPORTANCE_HIGH) continue;
      int k=ArraySize(g_news);
      ArrayResize(g_news,k+1);
      g_news[k]=values[i].time;
     }
  }

//--- recharge les annonces des prochaines 24 heures
void RefreshNews()
  {
   datetime now=TimeTradeServer();
   ArrayFree(g_news);
   datetime from=now-InpMinutesAfter*60;
   datetime to  =now+24*3600;
   string base  =SymbolInfoString(_Symbol,SYMBOL_CURRENCY_BASE);
   string profit=SymbolInfoString(_Symbol,SYMBOL_CURRENCY_PROFIT);
   LoadCurrency(base,from,to);
   if(profit!=base) LoadCurrency(profit,from,to);
   g_next_refresh=now+15*60;
   PrintFormat("%d annonce(s) importante(s) sur %s/%s dans les prochaines 24 h",
               ArraySize(g_news),base,profit);
  }

//--- true si l'heure courante tombe dans une fenêtre d'annonce
bool IsNewsTime()
  {
   datetime now=TimeTradeServer();
   for(int i=0;i<ArraySize(g_news);i++)
      if(now>=g_news[i]-InpMinutesBefore*60 && now<=g_news[i]+InpMinutesAfter*60)
         return(true);
   return(false);
  }

int OnInit()
  {
   RefreshNews();
   return(INIT_SUCCEEDED);
  }

void OnTick()
  {
   if(TimeTradeServer()>=g_next_refresh)
      RefreshNews();
   if(IsNewsTime())
     {
      Comment("Annonce importante proche : aucune nouvelle entrée");
      return;                          // la gestion des positions ouvertes peut continuer ailleurs
     }
   Comment("");
   // ... logique d'entrée habituelle ...
  }

Le filtre ne ferme pas les positions existantes : il empêche seulement d’en ouvrir de nouvelles. Selon votre stratégie, vous pouvez aussi resserrer les stops ou réduire le volume dans la fenêtre d’annonce. Les deux devises sont interrogées séparément, puisque le filtre par devise ne prend qu’un code à la fois.

Exploiter les valeurs publiées

Au-delà du filtre, les valeurs permettent des analyses plus fines : écart entre valeur réelle et prévision (la « surprise »), révisions de la valeur précédente, réaction du prix dans les minutes suivantes. Les fonctions CalendarValueLast et CalendarValueLastByEvent permettent de détecter la publication d’une nouvelle valeur dès qu’elle arrive dans le terminal. Utilisez toujours HasActualValue() avant GetActualValue() : avant la publication, le champ n’est pas renseigné.

Backtester un filtre d’annonces

Tester honnêtement une règle fondée sur le calendrier demande des données d’annonces cohérentes avec la période testée. La méthode la plus reproductible consiste à exporter au préalable l’historique des événements qui vous intéressent, depuis un script exécuté dans le terminal, vers un fichier CSV ou une base SQLite (voir Bases de données SQLite), puis à faire lire ce fichier par l’EA lorsqu’il tourne dans le testeur. Vous savez ainsi exactement quelles annonces le filtre a vues.

Pièges fréquents

  • Heure locale : comparer une annonce à TimeLocal() décale tout le filtre du fuseau de votre machine.
  • Valeurs brutes : actual_value vaut la valeur multipliée par un million, et LONG_MIN quand elle n’existe pas. Passez par les méthodes Get...Value().
  • Interrogation à chaque tick : inutile et coûteuse. Mettez la liste en cache et rafraîchissez-la périodiquement.
  • Devise de l’or ou des indices : pour un symbole comme XAUUSD, la devise de base n’est pas celle d’un pays ; seule la devise de cotation donnera des annonces. Vérifiez la logique pour chaque type d’instrument.
  • Annonces non programmées : le calendrier ne contient que les événements publiés à l’avance. Un filtre de news ne protège pas d’une déclaration imprévue.
Autour des annonces importantes, le spread peut s’élargir fortement et les ordres être exécutés avec un glissement important, y compris sur les stops. Un filtre d’annonces réduit cette exposition sans la supprimer : testez-le et gardez une gestion du risque prudente.

Questions fréquentes

En quelle heure sont exprimées les annonces du calendrier ?

En heure du serveur de trading, celle renvoyée par TimeTradeServer(). Comparez toujours les heures d’annonces à cette fonction ou à TimeCurrent(), jamais à l’heure locale de votre ordinateur.

Pourquoi actual_value contient-il un nombre énorme ou négatif ?

Les valeurs sont stockées multipliées par un million, et une valeur non renseignée vaut LONG_MIN. Utilisez HasActualValue() puis GetActualValue(), qui renvoie la valeur réelle ou NaN si elle n’existe pas encore.

Comment filtrer uniquement les annonces importantes ?

Récupérez les valeurs avec CalendarValueHistory, puis lisez l’événement associé avec CalendarEventById(value.event_id, event) et conservez ceux dont event.importance vaut CALENDAR_IMPORTANCE_HIGH.

Peut-on filtrer par devise et par pays à la fois ?

Oui : renseignez les deux paramètres de CalendarValueHistory, ils se combinent par un ET logique. Pour plusieurs devises, appelez la fonction une fois par devise.

A

Alix · fondateur d’OptiBot Trading

Développeur MQL5 et ProBuilder, spécialiste du backtest et de l’optimisation de stratégies automatiques. Chaque contenu est vérifié sur la documentation officielle (MQL5.com, manuels ProRealTime) et testé avant publication. Notre méthode éditoriale.