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).
To use any data dube endpoint, you can build a report request object. Main parameters to start with are :
A valid entry in the field
At least one valid entry in the field if you want to measure anything and not just get possible values of a dimension
At least one valid entry in the 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
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.
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.
You can only get the first page of a report at the moment.
The returned object contains two properties :
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).
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 in your request object. It contains an operator and one or more .
In this example, the metrics are only calculated for activities of type SITE_VISIT or DISPLAY_AD on channel 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.
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 :
The supported units are the following :
You can specify which metrics to order by.
Now that we have covered the basics of reports, you can take a look at our sample to have better ideas of what you can achieve.
"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
]
// ...[
]
}Minutes
s
Seconds
2021-10-10
666
3881
17800
2021-10-10
555
1838
4200
2021-10-11
666
532
3900
datamartId*
number
The ID of the datamart to query
metrics*
array
Array of Metric to retrieve.
dimension_filter_clauses
object
Filters to apply on dimensions before calculating the metric. For more information, see FilterClause.
dimensions*
array
Dimensions to group metrics by.
date_ranges*
array
Periods to analyze. Each date range is an object with a start_date and an end_date. See DateRange.
Date operator
description
y
Years
M
Months
w
Weeks
d
Days
h or H
Hours
m
{
"status": "ok",
"data": {
"report_view": {
"items_per_page": 100,
"total_items": 7,
"columns_headers": [
"type"
],
"rows": [
[
"DISPLAY_AD"
],
[
"EMAIL"
],
[
"SITE_VISIT"
],
[
"USER_SCENARIO_NODE_ENTER"
],
[
"USER_SCENARIO_NODE_EXIT"
],
[
"USER_SCENARIO_START"
],
[
"USER_SCENARIO_STOP"
]
]
}
}
}{
"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": [
{
"name": "date_yyyy_mm_dd"
},
{
"name": "channel_id"
},
{
"name": "device_form_factor"
}
]
"metrics": [
{
"expression": "users"
}
]"dimensions": [
{
"name": "date_yyyy_mm_dd"
}
]
"metrics": [
{
"expression": "users"
},
{
"expression": "sessions"
},
{
"expression": "revenue"
}
]"report_view": {
"items_per_page": int,
"total_items": int,
...
} "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": [
{
"start_date": "2021-10-10T00:00:00",
"end_date": "2021-10-25T23:59:59"
}
]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 // 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"
},Multiple API endpoints give you access to data cubes. In every of those cubes, you Create a report with a specific set of metrics and dimensions defined for each cube.
Here is the list of available cubes :
Activities analytics cube returns informations on UserActivity
Collection volumes cube returns informations on the number of indexed objects at given times
user_activities_analytics endpointReturns a customized report of your Activities analytics event data. The data returned from the API is as a table with columns for the requested dimensions and metrics. Metrics are individual measurements of UserActivity, such as active users or sessions count. Dimensions break down metrics across some common criteria, such as day or channel.
POST https://api.mediarithmics.com/v1/datamarts/:datamartId/user_activities_analytics
POST https://api.mediarithmics.com/v1/datamarts/:datamartId/user_activities_analytics
platform_monitoring/collections endpointReturns a customized report of your Collection volumes. The data returned from the API is as a table with columns for the requested dimensions and metrics. Metrics are individual measurements of UserActivity, such as active users or sessions count. Dimensions break down metrics across some common criteria, such as date or collection.
POST https://api.mediarithmics.com/v1/platform_monitoring/collections
POST https://api.mediarithmics.com/v1/platform_monitoring/collections
date_ranges[] object()
Retrieve the data in the specified date range. Mandatory. The data is only queryable for the last 4 months. Only one range is allowed, but the API is prepared to accept multiple ranges in the future.
dimensions[] object()
The list of dimensions. Mandatory, but can be an empty array.
dimension_filter_clauses object([])
To express dimension filters. Should either have at least one filter, or is undefined.
metrics[] object()
The list of metrics. Mandatory, but can be an empty array.
A contiguous set of days.
start_date string
The inclusive start date for the query in the format YYYY-MM-DDTHH:mm:ss.
end_date string
The inclusive end date for the query in the format YYYY-MM-DDTHH:mm:ss.
Dimensions are attributes of your data. For example, the dimension channel_id indicates the channel on which activities are recorded.
For a list of all available dimensions, see the documentation specific to the data cube you are using.
The quantitative measurements of a report. For example, the metric sessions is the total number of sessions.
For a list of all available metrics, see the documentation specific to the data cube you are using.
A group of filters to apply in a request.
operator enum
OR AND. Defaults to OR.
filters[] object()
List of filters to apply the operator on. At least one filter should be set.
To express a dimension filter, in a dimension_name operator expressions format.
dimension_name string
The name of the dimension to filter on. For a list of all dimensions, see the documentation specific to the data cube you are using.
not boolean
Defaults to false. If set to true, the dimension filter will be evaluated with the dimension_name not operator expressions logic.
operator enum
Select one of the following queries:
EXACT will force the dimension to match the first expression set
LIKE will allow the dimension to only contain the first expression set
IN_LIST will allow the dimension to be one of the expressions set
expressions[] string
One or more keywords to search for.
The API responds with a containing a report view as data.
items_per_page int
The maximum number of items per page. Always 100 at the moment.
total_items int
The total number of items that are currently returned. Between zero and items_per_page as only the first page can be retrieved at the moment.
column_headers[] string
Used to know which dimension or metric is represented by each column in the rows
rows[] object()
Each row represents a combination of dimensions value and their associated metrics.
A row is created for each dimensions value combination, with the corresponding metrics.
Values are in the same order as column_headers of the ReportView.
datamartId*
number
The ID of the datamart to query
metrics*
array
Array of Metric to retrieve.
dimension_filter_clauses
object
Filters to apply on dimensions before calculating the metric. For more information, see FilterClause.
dimensions*
array
Dimensions to group metrics by.
date_ranges*
array
Periods to analyze. Each date range is an object with a start_date and an end_date. See DateRange.
datamartId*
number
h9wQyqalVBMp
metrics*
array
o5TPO6Hrysij
dimension_filter_clauses
object
8Gi22Dj6BNJp
dimensions*
array
dBZaT9GCysCI
date_ranges*
array
3gwAgLk173E8
metrics*
array
Array of Metric to retrieve.
dimension_filter_clauses*
object
Filters to apply on dimensions before calculating the metric. For more information, see FilterClause.
dimensions*
Dimensions to group metrics by.
Dimensions to group metrics by.
date_ranges*
array
Periods to analyze. Each date range is an object with a start_date and an end_date. See DateRange.
metrics*
array
xjgU0Gn01X2g
dimension_filter_clauses*
object
15L2OkaiJVFf
dimensions*
Dimensions to group metrics by.
5asYSNhYhp1D
date_ranges*
array
A7QWMxNeFvGQ
{
"status": "ok",
"data": {
"report_view": {
"items_per_page": 100,
"total_items": 7,
"columns_headers": [
"type"
],
"rows": [
[
"DISPLAY_AD"
],
[
"EMAIL"
],
[
"SITE_VISIT"
],
[
"USER_SCENARIO_NODE_ENTER"
],
[
"USER_SCENARIO_NODE_EXIT"
],
[
"USER_SCENARIO_START"
],
[
"USER_SCENARIO_STOP"
]
]
}
}
}{
"status": "ok",
"data": {
"report_view": {
"items_per_page": 100,
"total_items": 7,
"columns_headers": [
"date_time",
"datamart_id",
"collection",
"count"
],
"rows": [
[
1637931755000,
9999,
"USER_POINT",
100
],
[
1637931755100,
9999,
"USER_EVENT",
50
]
]
}
}
}{
"date_ranges": [DateRange],
"dimensions": [Dimension],
"dimension_filter_clauses": FilterClause[DimensionFilter]
"metrics": [Metric]
}{
"start_date": "2021-10-10T00:00:00",
"end_date": "2021-10-25T23:59:59"
}{
"name": "date_yyyy_mm_dd"
}{
"expression": "users"
}{
"operator": "OR | AND", // Defaults to OR
"filters": [DimensionFilter]
}{
"dimension_name": string,
"not": boolean,
"operator": enum,
"expressions": [String],
}// TYPE should be DISPLAY_AD
{
"dimension_name": "TYPE",
"not": false,
"operator": "EXACT",
"expressions": [
"DISPLAY_AD"
]
}
// TYPE should contain SITE
// SITE_VISIT activities will be used
{
"dimension_name": "TYPE",
"not": false,
"operator": "LIKE",
"expressions": [
"SITE"
]
}
// TYPE should not contain SITE
{
"dimension_name": "TYPE",
"not": true,
"operator": "LIKE",
"expressions": [
"SITE"
]
}
// CHANNEL_ID should be either 8888 or 6666
{
"dimension_name": "CHANNEL_ID",
"not": false,
"operator": "IN_LIST",
"expressions": [
"8888",
"6666"
]
}{
"status": "ok",
"data": {
"report_view": {
"items_per_page": int,
"total_items": int,
"columns_headers": [string],
"rows": [Row]
}
}
} "rows": [
[
// Date dimension
"2021-10-10",
// Channel ID dimension
666,
// users metric
3881,
// sessions metric
17800.0
],
[
"2021-10-10",
555,
1838,
4200.0
],
[
"2021-10-11",
666,
532,
3900.0
],
[
"2021-10-11",
555,
8,
100.0
]
// ...[
]