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

Query Parameters

Name	Type	Description
datamartId*	number	The ID of the datamart to query

Request Body

Name	Type	Description
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.

200

{
    "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"
                ]
            ]
        }
    }
}

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.