Creating a report

Search…
Creating a report
This is an overview of the activities analytics capabilities.
Report
Reports returned by the API are a ReportView object in a Single resource wrapper. The result table is made up of headers and rows, with dimensions and metrics. The following report view is a table with two dimensions (day and channel ID) and two metrics (users and number of transactions).
"report_view": {
    "columns_headers": [
                "date_yyyy_mm_dd",
                "channel_id",
                "users",
                "number_of_transactions"
            ],
    // Data
    "rows": [
        [
            "2021-10-10",
            666,
            3881,
            17800.0
        ],
        [
            "2021-10-10",
            555,
            1838,
            4200.0
        ],
        [
            "2021-10-11",
            666,
            532,
            3900.0
        ],
        [
            "2021-10-11",
            555,
            8,
            100.0
        ]
        // ...[
    ]
}
date_yyyy_mm_dd
channel_id
users
number_of_transactions
2021-10-10
666
3881
17800
2021-10-10
555
1838
4200
2021-10-11
666
532
3900
Report request
To use any data dube endpoint, you can build a report request object. Main parameters to start with are : 
A valid entry in the date_ranges field
At least one valid entry in the metrics field if you want to measure anything and not just get possible values of a dimension
At least one valid entry in the dimensions field if you want to get the possible values of a dimension or calculate metrics for different dimensions.
post
https://api.mediarithmics.com
/v1/datamarts/:datamartId/user_activities_analytics
Minimal object to start with
{
    "date_ranges": [
        {
            "start_date": "2021-10-10T00:00:00",
            "end_date": "2021-10-25T23:59:59"
        }
    ],
    "dimensions": [
        {
            "name": "date_yyyy_mm_dd"
        }
    ],
    "metrics": [
        {
            "expression": "users"
        }
    ]
}
Dimensions
Dimensions describe and group data. The channel_id dimension, for example, indicates the channel on which the activity was registered. You can specify zero or more dimensions. See the documentation of each data cube for a complete list of available dimensions.
For example, this request groups active users by channel, day and type of device in activities analytics data cube.
"dimensions": [
    {
        "name": "date_yyyy_mm_dd"
    },
    {
        "name": "channel_id"
    },
    {
        "name": "device_form_factor"
    }
]
"metrics": [
    {
        "expression": "users"
    }
]
Metrics
Metrics are calculated on your data, for the specified date range and for each requested dimension. You can specify zero or more metrics. Specifying zero metrics usually means that you are only interested in the possible values of a dimension. See the documentation of each data cube for a complete list of available metrics.
This request will show three metrics, grouped per day.
"dimensions": [
    {
        "name": "date_yyyy_mm_dd"
    }
]
"metrics": [
    {
        "expression": "users"
    },
    {
        "expression": "sessions"
    },
    {
        "expression": "revenue"
    }
]
Pagination
You can only get the first page of a report at the moment.
The ReportView returned object contains two properties : 
"report_view": {
    "items_per_page": int,
    "total_items": int,
    ...
}
items_per_page is the page size (always 100 right now) and total_items is the number of returned items (between zero and items_per_page as only the first page can be retrieved).
Tip : you should usually find workarounds to not use a real pagination system.
For example, if you want the number of sessions per day on the last four months, you know you will have 122 days in the result which can't be retrieved by a single request. You then do two requests, one for the two first months and one for the others, and you don't need a pagination.
Dimension filters
You can ask to retrieve data only for specific dimension values. For example, to calculate the revenue for a specific channel, or to only look at activities with transactions. To filter dimensions, specify a FilterClause in your request object. It contains an operator and one or more DimensionFilter.
In this example, the metrics are only calculated for activities of type SITE_VISIT or DISPLAY_AD on channel 666
 "dimension_filter_clauses": {
        "operator": "AND",
        "filters": [
            {
                "dimension_name": "type",
                "operator": "IN_LIST",
                "not": false,
                "expressions": [
                    "SITE_VISIT", "DISPLAY_AD"
                ]
            },
            {
                "dimension_name": "channel_id",
                "operator": "EXACT",
                "not": false,
                "expressions": [
                    "666"
                ]
            }
        ]
    }
Date ranges
You can only retrieve data for one specific date range. The format is ready to be able to query multiple date ranges in the future.
"date_ranges": [
    {
        "start_date": "2021-10-10T00:00:00",
        "end_date": "2021-10-25T23:59:59"
    }
]
Date Math format
The idea of the date match syntax is to define a relative date compared to an anchor date. The anchor date is either now or a date (ISO8601 or timestamp format) followed by ||.
The expression begins with the anchor date and is followed by one or more math expressions :
+1h adds one hour
-1d substracts one day
/d rounds down to the nearest day
Example, assuming now is 2001-01-01 12:00:00 :
now+1h // Resolves to: 2001-01-01 13:00:00
now-1h // Resolves to: 2001-01-01 11:00:00
now-1h/d // Resolves to: 2001-01-01 00:00:00
2001.02.01||+1M/d // Resolves to: 2001-03-01 00:00:00
The supported units are the following :
Date operator
description
y
Years
M
Months
w
Weeks
d
Days
h or H
Hours
m
Minutes
s
Seconds
​
Order by
You can specify which metrics to order by.
  // Order by the number of users, in ascending order
  "order_by": {
    "field_name": "users"
  }
  
 // Order by the number of users, in descending order
  "order_by": {
    "field_name": "-users"
  },
​
Next step
Now that we have covered the basics of reports, you can take a look at our sample Use cases to have better ideas of what you can achieve.
Resources - Previous
Data cubes
Reference
Last modified 2mo ago
Copy link
On this page
Report
Report request
post
Dimensions
Metrics
Pagination
Dimension filters
Date ranges
Order by
Next step