User guidesDeveloper websiteHelp centerLog in

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.

{
    "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.

PreviousData cubesNextReference

Last updated

Was this helpful?