# Creating a report ## Report Reports returned by the API are a [ReportView](https://developer.mediarithmics.io/resources/reference#reportview) object in a [Single resource wrapper](https://developer.mediarithmics.io/api-overview#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_ddchannel_idusersnumber_of_transactions
2021-10-10666388117800
2021-10-1055518384200
2021-10-116665323900
## 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`](https://developer.mediarithmics.io/resources/reference#daterange) field * At least one valid entry in the [`metrics`](https://developer.mediarithmics.io/resources/reference#metric) field if you want to measure anything and not just get possible values of a dimension * At least one valid entry in the [`dimensions`](https://developer.mediarithmics.io/resources/reference#dimension) 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](https://developer.mediarithmics.io/resources/reference#metric) to retrieve. | | dimension\_filter\_clauses | object | Filters to apply on dimensions before calculating the metric. For more information, see [FilterClause](https://developer.mediarithmics.io/resources/reference#filterclause). | | dimensions\* | array | [Dimensions](https://developer.mediarithmics.io/resources/reference#dimension) 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](https://developer.mediarithmics.io/resources/reference#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 %} {% code title="Minimal object to start with" %} ```json5 { "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" } ] } ``` {% endcode %} ## 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. ```json "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. ```json5 "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](https://developer.mediarithmics.io/resources/reference#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). {% hint style="info" %} **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. {% endhint %} ## 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](https://developer.mediarithmics.io/resources/reference#filterclause) in your request object. It contains an operator and one or more [DimensionFilter](#dimension-filters). In this example, the metrics are only calculated for activities of type `SITE_VISIT` or `DISPLAY_AD` on channel `666` {% code title="" %} ```json "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" ] } ] } ``` {% endcode %} ## 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. ```json "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` : ```javascript 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. ```json // 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](https://developer.mediarithmics.io/querying-your-data/activities-analytics-queries/use-cases) to have better ideas of what you can achieve. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developer.mediarithmics.io/resources/data-cubes/creating-a-report.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.