FLAT format for Batch Reporting (API)

FLAT format for Batch Reporting (API)


New flat format for Batch Reporting exports
Eulerian introduces a flattened response format, designed to simplify the use of API data by data, BI and marketing teams.
This format allows you to retrieve a response in the form of a table:
columns explicitly described , then rows of values ​​directly usable in an ETL, a dashboard, a notebook, a data warehouse or a CSV export.



1. Why this change?

Until now, some API Reporting responses were structured as nested analytical blocks; this format, inspired by the Google Analytics API, allows for compatibility with existing tools:
  • dimensions separated from metrics;
  • values ​​encapsulated in multiple levels of JSON;
  • specific parsing logic to be rebuilt on the client side;
  • The mapping between columns and values ​​is sometimes difficult to read.

The new flat format responds to a simple objective: to make Eulerian data easier to read, transform, load and maintain in existing data tools.


2. How do I enable the flattened format?

The flattened format is used via the Batch Reporting endpoint:

The following parameter must be added to the body of the request:
 For example :
{"output": {"type": "flat"}}


{
  "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"] }]] }
 ]
 }
 ]
This format remains complete, but requires specific logic to reconstruct a usable table.
}



Next: a tabular answer

With the flat format, the answer is organized around two main blocks:
  • columnHeader: describes the available columns;
  • data: contains the rows of values, in the same order as columnHeader.
Simplified example:
{
  "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
Ordered list of returned columns
field
Technical identifier of the column
name
Readable column name
kind
Indicates whether it is a dimension or a metric
dataType
Expected data type: date, string, int, float, etc.
data
List of result lines
rowCount
Number of lines returned in the response
totalRowCount
Total number of rows available for the query
Each row of data is a table.Each value must be read according to the position of the corresponding column in columnHeader.



5. Date dimensions in flat mode

The flat mode also allows requesting date dimensions of type date_XXX.
For example, depending on the desired level of granularity, the client can use dimensions such as:
  • date_day
  • date_hour
  • date_week
  • date_year
The list of dimensions is available via the  Dimensions  API
This facilitates frequent use of reporting:
  • analysis per day;
  • hourly analysis;
  • powering time-based dashboards;
  • aggregation in a data warehouse;
  • export CSV or BI table with explicit date columns.



7. Example of client-side integration

The integration logic consists of:
    read columnHeader;
    retrieve the field fields;
    iterate through each line of data;
    reconstruct a key-value object.
JavaScript example:
 Expected result:
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]);

 {
 "date_hour": "2026-04-21T00",
 "website_name": "demo-fr",
 "media_key": "PARTNER",
 "hit": 3,
 "visit": 1
9. Best practices for integration
}





To do

  • Use field as a technical identifier in the code.
  • Use name as the display label if needed.
  • Read the column order systematically from columnHeader .
  • Do not hardcode column indices.
  • Use dataType to type values ​​before storage or calculation.
  • Compare rowCount and totalRowCount to check the returned volumes.

Avoid

  • Assume that the order of the columns will always remain the same.
  • Parse the values ​​without reading columnHeader .
  • Mix display logic and technical logic.
  • Ignore the date dimensions available in flat mode.