Creating a report
This is an overview of the activities analytics capabilities.
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 |
To use any data dube endpoint, you can build a report request object. Main parameters to start with are :
- At least one valid entry in the
metricsfield if you want to measure anything and not just get possible values of a dimension - At least one valid entry in the
dimensionsfield if you want to get the possible values of a dimension or calculatemetricsfor differentdimensions.
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 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 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"
}
]
You can only get the first page of a report at the moment.
"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.
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"
]
}
]
}
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"
}
]
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 :
+1hadds one hour-1dsubstracts one day/drounds 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 |
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"
},
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.
Last modified 8mo ago