Format FLAT pour le Batch Reporting (API)

Format FLAT pour le Batch Reporting (API)


Nouveau format flat pour les exports Batch Reporting
Eulerian introduit un format de réponse aplati, pensé pour simplifier l’exploitation des données API par les équipes data, BI et marketing.
Ce format permet de récupérer une réponse sous la forme d'un tableau :
des colonnes décrites explicitement, puis des lignes de valeurs directement exploitables dans un ETL, un dashboard, un notebook, un data warehouse ou un export CSV.



1. Pourquoi cette évolution ?

Jusqu’ici, certaines réponses API Reporting étaient structurées sous forme de blocs analytiques imbriqués, ce format inspiré de celui de l'API Google Analytics permet une compatibilité avec les outils déjà existants :
  • dimensions séparées des métriques ;
  • valeurs encapsulées dans plusieurs niveaux JSON ;
  • logique de parsing spécifique à reconstruire côté client ;
  • mapping parfois peu lisible entre colonnes et valeurs.

Le nouveau format flat répond à un objectif simple : rendre la donnée Eulerian plus facile à lire, transformer, charger et maintenir dans les outils data existants.


2. Comment activer le format aplati ?

Le format aplati s’utilise via l’endpoint Batch Reporting :
 https://doc.api.eulerian.com/#tag/Batch-Reporting/operation/queryBatchReporting 

Dans le corps de la requête, il faut ajouter le paramètre suivant :
{"output": {"type": "flat"}}

Par exemple :
{
  "output": {
    "type": "flat"
  },
  "reports": [
    {
      "dateRanges": [
        {
          "range": "YESTERDAY"
        }
      ],
      "dimensions": [
        {
          "field": "website_name",
          "name": "website_name"
        },
        {
          "name" : "Date",
          "field": "date_day"
        }
      ],
      "kind": "rt#website",
      "metrics": [
        {
          "field": "visit",
          "name": "Sessions (visits)"
        },
        {
          "field": "realscartvalid",
          "name": "Sales (transactions)"
        },
        {
          "field": "realscartvalidamount",
          "name": "Revenue"
        }
      ]
    }
  ]
}
Une fois ce mode activé, la réponse API est retournée dans un format tabulaire.


3. Ce que change le mode flat

Avant : une logique imbriquée

Dans l’ancien format, une valeur pouvait être stockée dans une structure profonde, par exemple :
{
  "data": [
    {
      "columnHeader": {
        "dimensions": [{ "field": "ope_name", "name": "campaign" }],
        "metrics": [
          { "field": "click", "name": "inbound clicks", "affinity": "int" }
        ]
      },
      "data": [
        { "dimensions": ["Google"], "metrics": [[{ "values": ["29222"] }]] }
      ]
    }
  ]
}
Ce format reste complet, mais il nécessite une logique spécifique pour reconstruire une table exploitable.


Après : une réponse tabulaire

Avec le format flat, la réponse est organisée autour de deux blocs principaux :
  • columnHeader : décrit les colonnes disponibles ;
  • data : contient les lignes de valeurs, dans le même ordre que columnHeader.
Exemple simplifié :
{
  "content": {
    "columnHeader": [
      {
        "field": "date_day",
        "type": "dimension",
        "name": "Date",
        "dataType": "date"
      },
      {
        "field": "website_name",
        "type": "dimension",
        "name": "website_name",
        "dataType": "string"
      },
      {
        "field": "media_key",
        "type": "dimension",
        "name": "media_key",
        "dataType": "string"
      },
      { "field": "hit", "type": "metric", "name": "hit", "dataType": "int" },
      { "field": "visit", "type": "metric", "name": "visit", "dataType": "int" }
    ],
    "data": [
      ["2026-04-21", "demo-fr", "PARTNER", 3, 1],
      ["2026-04-21", "demo-fr", "PARTNER", 0, 0]
    ],
    "rowCount": 2,
    "totalRowCount": 2
  },
  "error": 0
}


4. Lecture de la réponse

Le principe est volontairement simple :
Élément
Rôle
columnHeader
Liste ordonnée des colonnes retournées
field
Identifiant technique de la colonne
name
Nom lisible de la colonne
type
Indique s’il s’agit d’une dimension ou d’une metric
dataType
Type de donnée attendu : date, string, int, float, etc.
data
Liste des lignes de résultats
rowCount
Nombre de lignes retournées dans la réponse
totalRowCount
Nombre total de lignes disponibles pour la requête
Chaque ligne de data est un tableau.Chaque valeur doit être lue selon la position de la colonne correspondante dans columnHeader.



5. Dimensions de date en mode flat

Le mode flat permet également de demander des dimensions de date de type date_XXX.
Par exemple, selon le niveau de granularité souhaité, le client peut exploiter des dimensions telles que :
  • date_day
  • date_hour
  • date_week
  • date_year
La liste des dimensions est disponible via l'API  Dimensions 
Cela facilite les usages fréquents de reporting :
  • analyse par jour ;
  • analyse par heure ;
  • alimentation de dashboards temporels ;
  • agrégation dans un data warehouse ;
  • export CSV ou table BI avec colonnes de date explicites.



7. Exemple d’intégration côté client

La logique d’intégration consiste à :
    lire columnHeader ;
    récupérer les champs field ;
    parcourir chaque ligne de data ;
    reconstruire un objet clé-valeur.
Exemple JavaScript :
const payload = await response.json();const columns = payload.content.columnHeader;const fields = columns.map((column) => column.field);const rows = payload.content.data.map((line) => {return Object.fromEntries(fields.map((field, index) => [field, line[index]]));});console.log(rows[0]);
Résultat attendu :
{
  "date_hour": "2026-04-21T00",
  "website_name": "demo-fr",
  "media_key": "PARTNER",
  "hit": 3,
  "visit": 1
}



9. Bonnes pratiques d’intégration

À faire

  • Utiliser field comme identifiant technique dans le code.
  • Utiliser name comme libellé d’affichage si besoin.
  • Lire systématiquement l’ordre des colonnes depuis columnHeader.
  • Ne pas coder en dur les index des colonnes.
  • Utiliser dataType pour typer les valeurs avant stockage ou calcul.
  • Comparer rowCount et totalRowCount pour contrôler les volumes retournés.

À éviter

  • Supposer que l’ordre des colonnes restera toujours identique.
  • Parser les valeurs sans lire columnHeader.
  • Mélanger logique d’affichage et logique technique.
  • Ignorer les dimensions de date disponibles en mode flat.