# Reference

## `user_activities_analytics` endpoint

Returns a customized report of your [Activities analytics](https://developer.mediarithmics.io/data-streams/data-ingestion/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.

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/datamarts/:datamartId/user_activities_analytics`

#### Query Parameters

| Name                                         | Type   | Description                     |
| -------------------------------------------- | ------ | ------------------------------- |
| datamartId<mark style="color:red;">\*</mark> | number | The ID of the datamart to query |

#### Request Body

| Name                                           | Type   | Description                                                                                                            |
| ---------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
| metrics<mark style="color:red;">\*</mark>      | array  | Array of [Metric](#metric) to retrieve.                                                                                |
| dimension\_filter\_clauses                     | object | Filters to apply on dimensions before calculating the metric. For more information, see [FilterClause](#filterclause). |
| dimensions<mark style="color:red;">\*</mark>   | array  | [Dimensions](#dimension) to group metrics by.                                                                          |
| date\_ranges<mark style="color:red;">\*</mark> | array  | Periods to analyze. Each date range is an object with a `start_date` and an `end_date`. See [DateRange](#daterange).   |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/datamarts/:datamartId/user_activities_analytics`

#### Query Parameters

| Name                                         | Type   | Description  |
| -------------------------------------------- | ------ | ------------ |
| datamartId<mark style="color:red;">\*</mark> | number | h9wQyqalVBMp |

#### Request Body

| Name                                           | Type   | Description  |
| ---------------------------------------------- | ------ | ------------ |
| metrics<mark style="color:red;">\*</mark>      | array  | o5TPO6Hrysij |
| dimension\_filter\_clauses                     | object | 8Gi22Dj6BNJp |
| dimensions<mark style="color:red;">\*</mark>   | array  | dBZaT9GCysCI |
| date\_ranges<mark style="color:red;">\*</mark> | array  | 3gwAgLk173E8 |

## `platform_monitoring/collections` endpoint

Returns  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.

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/platform_monitoring/collections`

#### Request Body

| Name                                                         | Type                            | Description                                                                                                            |
| ------------------------------------------------------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| metrics<mark style="color:red;">\*</mark>                    | array                           | Array of [Metric](#metric) to retrieve.                                                                                |
| dimension\_filter\_clauses<mark style="color:red;">\*</mark> | object                          | Filters to apply on dimensions before calculating the metric. For more information, see [FilterClause](#filterclause). |
| dimensions<mark style="color:red;">\*</mark>                 | Dimensions to group metrics by. | [Dimensions](#dimension) to group metrics by.                                                                          |
| date\_ranges<mark style="color:red;">\*</mark>               | array                           | Periods to analyze. Each date range is an object with a `start_date` and an `end_date`. See [DateRange](#daterange).   |

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}
{% endtabs %}

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/platform_monitoring/collections`

#### Request Body

| Name                                                         | Type                            | Description  |
| ------------------------------------------------------------ | ------------------------------- | ------------ |
| metrics<mark style="color:red;">\*</mark>                    | array                           | xjgU0Gn01X2g |
| dimension\_filter\_clauses<mark style="color:red;">\*</mark> | object                          | 15L2OkaiJVFf |
| dimensions<mark style="color:red;">\*</mark>                 | Dimensions to group metrics by. | 5asYSNhYhp1D |
| date\_ranges<mark style="color:red;">\*</mark>               | array                           | A7QWMxNeFvGQ |

### Request body

{% code title="JSON representation" %}

```json5
{
    "date_ranges": [DateRange],
    "dimensions": [Dimension],
    "dimension_filter_clauses": FilterClause[DimensionFilter]
    "metrics": [Metric]
}
```

{% endcode %}

### Fields

`date_ranges[]` **object(**[**DateRange**](#daterange)**)**

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(**[**Dimension**](#dimension)**)**

The list of dimensions. Mandatory, but can be an empty array.

`dimension_filter_clauses` **object(**[**FilterClause**](#filterclause)**\[**[**DimensionFilter**](#dimensionfilter)**])**

To express dimension filters. Should either have at least one filter, or is undefined.

`metrics[]` **object(**[**Metric**](#metric)**)**

The list of metrics. Mandatory, but can be an empty array.

{% hint style="info" %}
Metrics without dimensions will calculate the metric for the whole data in the date ranges. Metrics with dimensions will calculate the metric for each dimension value.

You usually use dimensions without metrics to retrieve the possible values of a dimension.
{% endhint %}

## DateRange

A contiguous set of days.

```json5
{
     "start_date": "2021-10-10T00:00:00",
     "end_date": "2021-10-25T23:59:59"
}
```

`start_date` **string**

The inclusive start date for the query in the format `YYYY-MM-DDTHH:mm:ss`.&#x20;

`end_date` **string**

The inclusive end date for the query in the format `YYYY-MM-DDTHH:mm:ss`.&#x20;

## Dimension

Dimensions are attributes of your data. For example, the dimension `channel_id` indicates the channel on which activities are recorded.&#x20;

```json
{
    "name": "date_yyyy_mm_dd"
}
```

For a list of all available dimensions, see the documentation specific to the data cube you are using.

## Metric

The quantitative measurements of a report. For example, the metric `sessions` is the total number of sessions.

```json
{
    "expression": "users"
}
```

For a list of all available metrics, see the documentation specific to the data cube you are using.

## FilterClause

*A* group of filters to apply in a request.

```json
{
        "operator": "OR | AND", // Defaults to OR
        "filters": [DimensionFilter]         
}
```

`operator` **enum**

`OR` `AND`. Defaults to `OR`.

`filters[]` **object(**[**DimensionFilter**](#dimensionfilter)**)**

List of filters to apply the `operator` on. At least one filter should be set.

## DimensionFilter

To express a dimension filter, in a `dimension_name` `operator` `expressions` format.

```json
{
  "dimension_name": string,
  "not": boolean,
  "operator": enum,
  "expressions": [String],
}
```

`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.

{% code title="Examples" %}

```json
// 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"
  ]
}
```

{% endcode %}

## ReportView

The API responds with a [Single resource wrapper](https://developer.mediarithmics.io/api-overview#resource-list-wrapper-non-paginated-apis) containing a report view as data.

```json
{
    "status": "ok",
    "data": {
        "report_view": {
            "items_per_page": int,
            "total_items": int,
            "columns_headers": [string],
            "rows": [Row]
        }
    }
}
```

`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(**[**Row**](#undefined)**)**

Each row represents a combination of dimensions value and their associated metrics.

## Row

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.

```json
 "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
                ]
                // ...[
            ]
```