13 recommandations pour l'utilisation de l'API de reporting Eulerian

13 recommandations pour l'utilisation de l'API de reporting Eulerian



1. Principe clé de l’API Batch Reporting

L’API Batch Reporting permet d’extraire les données de reporting Eulerian à partir des vues disponibles dans l’interface.
Elle doit être utilisée comme un moyen d’automatiser l’extraction de rapports déjà exploitables dans l’interface Eulerian. Elle ne doit pas être considérée comme un outil permettant de créer en une seule requête une granularité ou une combinaison de données qui n’existe pas dans les rapports.
Par exemple, si une analyse nécessite de combiner plusieurs sources ou plusieurs vues, il faut effectuer plusieurs requêtes API, puis agréger les résultats côté BI, datawarehouse ou script de traitement.


2. Heure recommandée pour lancer les jobs API

Pour récupérer les données complètes de J-1, il est recommandé de lancer les exports à partir de 06h00 du matin.
Pendant la nuit, Eulerian synchronise la base froide afin d’y intégrer les données de J-1. Une requête très matinale, par exemple vers 05h00, peut tomber pendant cette synchronisation et rencontrer une indisponibilité ou retourner des données incomplètes.
La recommandation opérationnelle est donc de planifier les jobs API à partir de 06h00.


3. Récupérer les bons paramètres pour une requête API

Une méthode simple pour construire une requête API consiste à partir du rapport souhaité dans l’interface Eulerian, puis à observer la requête générée par l’interface.
Étapes recommandées :
    Ouvrir le rapport souhaité dans l’interface Eulerian.
    Ouvrir les outils développeur du navigateur avec F12.
    Aller dans l’onglet Réseau / Network.
    Identifier la requête de reporting générée par l’interface.
    Récupérer les paramètres utiles pour construire le body API.
Les éléments utiles à récupérer sont notamment :
Élément observé dans la requête réseau
Utilisation dans l’API
view-id
ID de la vue d’attribution
ea-datasource
Valeur du kind, avec le préfixe rt# dans le body API
path
Valeur à utiliser dans le champ path du body JSON
IDs présents dans le path
IDs de publisher, levier, plan média ou campagne selon la vue consultée
Le path visible dans la console contient déjà les IDs correspondant au niveau de données consulté : publisher, levier, plan média, campagne, etc.


4. Endpoint de requête

L’endpoint utilisé pour interroger l’API Batch Reporting est de la forme :
POST /ea/{site}/report/{batch}/query.json
Content-Type: application/json
Le body JSON contient généralement un tableau reports, dans lequel on définit :
Élément
Rôle
dateRanges
Période d’analyse
dimensions
Axes de lecture du rapport
kind
Source de données / type de rapport
metrics
Indicateurs à extraire
path
Niveau de reporting ou périmètre média
segmentFilterClauses
Filtres optionnels, par exemple sur les types de ventes
Exemple simple :
{
  "reports": [
    {
      "dateRanges": [
        {
          "range": "YESTERDAY"
        }
      ],
      "dimensions": [
        {
          "field": "ope_name",
          "name": "campaign"
        }
      ],
      "kind": "rt#insummary",
      "metrics": [
        {
          "field": "scartvalid",
          "name": "sales"
        }
      ],
      "path": "mcMEDIAINCOMING[?].mcMEDIAAD.mcOPE"
    }
  ]
}

Le kind, le path, les dimensions et les métriques doivent être adaptés au rapport que l’on souhaite reproduire.


5. Filtrer sur des types de ventes

Les filtres sur les types de ventes sont gérés via segmentFilterClauses.
Dans le cas des types de ventes, le champ à utiliser est :
"field": "ordertype_id"
Exemple de requête avec filtre sur type de vente :
{
  "reports": [
    {
      "dateRanges": [
        {
          "range": "YESTERDAY"
        }
      ],
      "dimensions": [
        {
          "field": "ope_name",
          "name": "campaign"
        }
      ],
      "kind": "rt#insummary",
      "metrics": [
        {
          "field": "scartvalid",
          "name": "sales"
        }
      ],
      "path": "mcMEDIAINCOMING[?].mcMEDIAAD.mcOPE",
      "segmentFilterClauses": [
        {
          "field": "ordertype_id",
          "operator": "IN",
          "value": [
            1,
            2
          ]
        }
      ]
    }
  ]
}

Les IDs à renseigner dans value doivent être récupérés dans l’interface Eulerian via la recherche Liste des types de ventes.
À retenir : il ne faut pas utiliser directement le libellé métier du type de vente dans la requête API. Il faut utiliser son ID technique.


6. Récupérer les IDs des types de ventes

Pour récupérer les IDs des types de ventes :
    Aller dans l’interface Eulerian.
    Utiliser la barre de recherche en haut à droite.
    Rechercher Liste des types de ventes.
    Identifier les IDs correspondant aux types de ventes souhaités.
    Utiliser ces IDs dans segmentFilterClauses.value.
Exemple :
"segmentFilterClauses": [
  {
    "field": "ordertype_id",
    "operator": "IN",
    "value": [
      117,
      135,
      159
    ]
  }
]

Les valeurs ci-dessus sont données à titre d’exemple. Elles doivent être adaptées au périmètre client et aux types de ventes réellement visibles dans l’interface.


7. IDs des leviers média Eulerian

Les principaux IDs de leviers média sont les suivants :
ID
Levier
2
MAILING
3
ADVERTISING / Display
4
AFFILIATION
5
SPONSOREDLINK / Liens sponsorisés
6
PARTNER / Partenariat
7
INTERNAL
8
TRUSTEDFEED
10
BRANDING
16
OFFLINE
17
SOCIAL
20
GENERIC
Ces IDs peuvent être utilisés pour vérifier ou construire les path liés aux vues média.


8. IDs des modèles d’attribution augmentés

Pour les algorithmes d'attribution, les IDs visibles dans l’interface Eulerian, via la page Création et édition de mes modèles.
Cela vous permettra d'identifier le modèle d’attribution utilisé dans les vues de reporting.


9. Bonnes pratiques d’intégration côté BI / Datawarehouse

Pour industrialiser l’utilisation de l’API de reporting Eulerian, il est recommandé de :
  • partir d’une vue existante dans l’interface Eulerian pour construire la requête API ;
  • récupérer le kind, le path et les IDs via l’onglet Réseau du navigateur ;
  • planifier les appels API à partir de 06h00 ;
  • utiliser les IDs techniques plutôt que les libellés métier ;
  • utiliser segmentFilterClauses pour appliquer des filtres spécifiques ;
  • exécuter plusieurs requêtes lorsque la vue souhaitée combine plusieurs périmètres ;
  • agréger les résultats côté BI, datawarehouse ou script de traitement ;
  • conserver un timestamp d’extraction pour faciliter l’audit des données.


10. Résumé opérationnel

Sujet
Recommandation
Endpoint
POST /ea/{site}/report/{batch}/query.json
Format
JSON
Heure de lancement conseillée
À partir de 06h00
Construction de la requête
Partir d’une vue existante dans l’interface
Récupération du kind et du path
Via l’onglet Réseau du navigateur
Filtre type de vente
segmentFilterClauses avec field: "ordertype_id"
IDs types de ventes
À récupérer dans Liste des types de ventes
IDs leviers média
À utiliser pour vérifier les path
IDs modèles MTA augmentés
Via la page Création et Editons des modèles
Agrégation complexe
Faire plusieurs requêtes puis agréger côté BI


11. Comment requêter les plans média

Pour requêter les plans média via l’API de reporting Eulerian, il est recommandé de splitter la requête en plusieurs parties afin qu’elle reste viable et exploitable.
La bonne pratique consiste notamment à effectuer une requête par levier d’acquisition.
Chaque requête reprend la même structure, mais avec un path différent selon le levier souhaité.
Levier d’acquisition
Path à utiliser
Display
mcWEBSITE[1].mcGLOBALMEDIAPLAN.mcMEDIAPLAN[1].mcMEDIA[3].mcPUBLISHER
Mailing
mcWEBSITE[1].mcGLOBALMEDIAPLAN.mcMEDIAPLAN[1].mcMEDIA[2].mcPUBLISHER
Social
mcWEBSITE[1].mcGLOBALMEDIAPLAN.mcMEDIAPLAN[1].mcMEDIA[17].mcPUBLISHER
SEA
mcWEBSITE[1].mcGLOBALMEDIAPLAN.mcMEDIAPLAN[1].mcMEDIA[5].mcPUBLISHER
Affiliation
mcWEBSITE[1].mcGLOBALMEDIAPLAN.mcMEDIAPLAN[1].mcMEDIA[4].mcPUBLISHER
Dans ces exemples :
  • mcWEBSITE[1] correspond au site concerné ;
  • mcMEDIAPLAN[1] correspond au plan média ciblé ;
  • mcMEDIA[x] correspond au levier d’acquisition ;
  • mcPUBLISHER permet de descendre au niveau support / publisher.
Les IDs doivent être adaptés au contexte client et au niveau de reporting souhaité.

Exemple de requête pour le levier Display

Exemple pour le levier Display, avec les vues d’attribution 3, 8 et 6, sur la période du 01/04/2026 au 31/05/2026.
{
  "async": false,
  "reports": [
    {
      "kind": "rt#mediaplan",
      "path": "mcWEBSITE[1].mcGLOBALMEDIAPLAN.mcMEDIAPLAN[1].mcMEDIA[3].mcPUBLISHER",
      "segments": [
        {
          "name": "Attribution rule",
          "operator": "IN",
          "type": "attributionrule",
          "value": [
            3,
            8,
            6
          ]
        }
      ],
      "dimensions": [
        {
          "field": "publisheralias_alias",
          "name": "Support"
        }
      ],
      "metrics": [
        {
          "name": "Ventes réelles",
          "field": "realscartvalid"
        }
      ],
      "dateRanges": [
        {
          "dateFrom": "2026-04-01",
          "dateTo": "2026-05-31",
          "dateFormat": "YYYY-MM-DD"
        }
      ]
    }
  ]
}

Pour requêter un autre levier, il suffit de reprendre la même structure et de remplacer la valeur du path par celle du levier souhaité.
Par exemple, pour le SEA, le path devient :
"path": "mcWEBSITE[1].mcGLOBALMEDIAPLAN.mcMEDIAPLAN[1].mcMEDIA[5].mcPUBLISHER"
Cette approche permet de sécuriser les temps de réponse, de mieux contrôler les volumes retournés et de faciliter l’agrégation des résultats côté BI ou datawarehouse.


12. Recommandation : choisir entre publisheralias_alias et publisher_name

Lors d’une requête, il peut arriver que la dimension publisheralias_alias retourne une valeur vide alors que des métriques sont bien présentes.
Ce comportement est normal et dépend de la manière dont le tracking Eulerian a été implémenté sur les plateformes partenaires.

Différence entre publisheralias_alias et publisher_name

Lorsque le tracking Eulerian est implémenté au sein d’une plateforme tierce de type DSP, adserver ou plateforme média, les paramètres de suivi des campagnes ne collectent oas directement le nom du publisher ou de la campagne via une macro lisible, par exemple :
ead-publisher={{publisher_name}}, qui deviendrait "lequipe.fr"
Dans ce cas, le tracking peut être alimenté avec des IDs techniques, par exemple :
ead-publisher={{publisher_id}}, qui deviendrait "1234"
Eulerian utilise alors des connecteurs EPC pour faire le mapping entre l’ID collecté dans les paramètres de suivi et le libellé réel du publisher ou de la campagne tel qu’il apparaît dans la plateforme tierce.
Ces libellés retraités sont appelés des alias côté Eulerian. Ils sont accessibles via la dimension :
{
  "field": "publisheralias_alias",
  "name": "Support"
}
À l’inverse, lorsque le nom du publisher est directement envoyé dans le tracking, sans nécessiter de mapping par connecteur, il faut utiliser la dimension :
{
  "field": "publisher_name",
  "name": "Support"
}


13. Utiliser overwriteNameByAlias pour gérer automatiquement les alias

Pour éviter d’avoir à jongler manuellement entre publisher_name et publisheralias_alias, il est possible d’utiliser l’option API suivante :
"overwriteNameByAlias": true
Cette option permet de demander à l’API de privilégier l’alias lorsqu’il existe, tout en conservant le nom brut lorsque l’alias n’est pas disponible.
Elle répond notamment au cas suivant :
  • si le publisher dispose d’un alias, l’API retourne l’alias ;
  • si le publisher ne dispose pas d’alias, l’API retourne le publisher_name.
Cela permet de limiter les lignes vides dans les exports et d’obtenir une dimension “Support” plus directement exploitable côté BI ou datawarehouse.

Où placer l’option dans la requête

L’option overwriteNameByAlias doit être ajoutée au niveau du bloc de rapport, au même niveau que kind, path, segments, dimensions, metrics et dateRanges.
Exemple sur le levier Social :
{
  "async": false,
  "reports": [
    {
      "kind": "rt#mediaplan",
      "path": "mcWEBSITE[1].mcGLOBALMEDIAPLAN.mcMEDIAPLAN[1].mcMEDIA[17].mcPUBLISHER",
      "overwriteNameByAlias": true,
      "segments": [
        {
          "name": "Attribution rule",
          "operator": "IN",
          "type": "attributionrule",
          "value": [
            3,
            8,
            6
          ]
        }
      ],
      "dimensions": [
        {
          "field": "publisher_name",
          "name": "Support"
        }
      ],
      "metrics": [
        {
          "name": "Ventes réelles",
          "field": "realscartvalid"
        }
      ],
      "dateRanges": [
        {
          "dateFrom": "2026-04-01",
          "dateTo": "2026-05-31",
          "dateFormat": "YYYY-MM-DD"
        }
      ]
    }
  ]
}


Dimension à utiliser avec cette option

Lorsque overwriteNameByAlias est activé, il est recommandé d’utiliser la dimension standard publisher_name :
"dimensions": [
  {
    "field": "publisher_name",
    "name": "Support"
  }
]
L’API se charge alors d’appliquer l’alias lorsque celui-ci est disponible.
Cette approche est plus simple que de requêter séparément publisher_name et publisheralias_alias, puis de réconcilier les deux champs côté BI.

Portée de l’option

L’option overwriteNameByAlias ne s’applique pas uniquement aux publishers.
Elle peut également s’appliquer aux autres dimensions disposant d’un mécanisme d’alias, par exemple :
Dimension brute
Alias potentiellement appliqué
publisher_name
alias du publisher
ope_name
alias de campagne
creative_name
alias de création
L’option permet donc d’obtenir des libellés plus propres et plus cohérents dans les exports API lorsque des connecteurs Eulerian alimentent des alias.

Recommandation opérationnelle

Pour les requêtes par support / publisher :
    Utiliser publisher_name comme dimension principale.
    Ajouter "overwriteNameByAlias": true dans le bloc de rapport.
    Tester le résultat sur les leviers où les deux logiques coexistent, notamment Social.
    Conserver cette option si les supports remontent correctement avec les alias attendus et sans lignes vides injustifiées.
Cette option est particulièrement utile pour le levier Social, où certaines campagnes peuvent être trackées via des IDs partenaires puis retraitées par alias, tandis que d’autres campagnes peuvent être trackées manuellement avec un nom de publisher déjà disponible.