Analytics¶
Overview¶
The Analytics API allows to get reports of any complexity. You may select any combination of columns and filter/segment the data. One can obtain data in JSON, XML or Excel formats.
Get analytical reports¶
POST /project/analytics/dataOverview¶
It is the main method for obtaining analytical reports.
It is important to specify the columns you want to view, time period and filters in the request body. There are two types of columns: metrics and dimensions. They should be listed in separate fields in the request body and will be returned in separate fields in the response body. Metrics and dimensions are discussed further in detail. Filters are used similarly to other methods. For further details see the examples below.
Metrics and dimensions¶
A metric is a quantitative measure in a report. E.g.: the number of visits or orders, revenue etc. Metrics are those parameters that you can add, subtract, average or compare to find the minimum and maximum, for example. I.e. they always are numbers.
A dimension is a qualitative measure. E.g.: advertising source, browser, sex, age, ordering method. I.e. dimensions are those measures usually displayed in the left part of a report. Dimensions are used for grouping data and calculating metrics. E.g., you want to view a report with the number of visits for each of your marketing channel. In that case, the report will contain one dimension "marketing channel" and one metric "Visits".
To form a request, you need to know a current list of dimensions and metrics. You can obtain it by using the /project/analytics/metrics and /project/analytics/dimensions methods.
Multi-Channel reports¶
By default, Analytics comprises all deals created within the chosen period of time, but visit dates for the deals are ignored. This attribution model is called "Default".
However, Roistat allows to set some other attribution models for calculating metrics: - First click; - Last click; - U-shape: attribution model based on the position that a marketing channel takes in the visit history for a deal; - Custom: under development.
The list of available models can always be obtained with the /project/analytics/attribution-models method.
Consequently, one metric may be presented by several columns, being calculated according to different attribution models.
Metrics that can be calculated according to different models have the is_has_attribution_model: true attribute (see the response body of the /project/analytics/metrics method). In summary, metrics with such an attribute can be counted under any available attribution model.
Filtering by metrics and dimensions¶
This method allows to extract the exact volume of data that you wish to view in your reports.
You can filter data by metrics and dimensions.
Filtering parameters should be specified in the filters array inside the request body.
WARNING! Filtering by dimensions is applied at the stage of data processing and filters by metrics are used after the data is processed. I.e. firstly, filtering by dimensions is applied, and secondly, filtering by metrics starts.
Sample report¶
Bellow is an example of a typical report on advertising sources for a month.
| Source | Visits | Leads | Sales | Profit, $ | Costs, $ | ROI, % |
|---|---|---|---|---|---|---|
| Yandex.Direct | 7556 | 128 | 28 | 36320 | 28498 | 27 |
| Google.Adwords | 2373 | 47 | 4 | 4050 | 2515 | 61 |
So, we need the Source dimension. Sources usually have several nesting levels (e.g. Direct > Campaign 1 > Banner 232). Now we are interested in the upper level. Let's obtain available dimensions and find the name field for the level concerned. The title value is used only in the Roistat interface. The system name of the 1st level source is marker_level_1.
Then, let's deal with metrics in the same way as for dimensions.
Bellow is an example of the request we need:
{
"dimensions": ["marker_level_1"],
"metrics": ["visits","leads","sales","profit","marketing_cost","roi"],
"period": {
"from":"2016-07-01T00:00:00+0300",
"to":"2016-07-31T23:59:59+0300"
}
}
You will receive a JSON response, the data field containing one object. This object has the items entry and that is the array of rows for our report. Each object of the items array corresponds to one row of the report table. Data on metrics and dimensions is returned in separate fields grouped within separate objects. System information in the response body will be described further.
If you want to receive this data in user readable view, you can send the following request: /project/analytics/data/export/excel. Instead of a JSON response, you will receive a user-friendly Excel file, which is easier to view and analyze.
curl 'https://cloud.roistat.com/api/v1/project/analytics/data?project=12345' \
--request POST \
--header 'Content-type: application/json' \
--header 'Api-key: {KEY}' \
--data Request body - see below
Request Body:
{
"dimensions": [
"marker_level_1",
"marker_level_2"
],
"metrics": [
"visits",
"leads",
"sales",
"marketing_cost",
"roi",
{
"metric": "profit",
"attribution": "first_click"
}
],
"period": {
"from": "2016-07-01T00:00:00+0300",
"to": "2016-07-31T23:59:59+0300"
},
"filters": [
{
"field": "marker_level_1",
"operation": "in",
"value": [
"site1",
"site2",
"site3"
]
},
{
"field": "roi",
"operation": ">",
"value": "0"
}
],
"interval": "1w",
"next_dimensions": [
"marker_level_2"
]
}
{
"data": [
{
"items": [
{
"metrics": {
"visits": {
"value": "136",
"formatted": "136",
"metric_name": null,
"attribution_model_id": null
},
"conversion_leads_to_sales": {
"value": 17.948717948717999,
"formatted": "18 %",
"metric_name": null,
"attribution_model_id": null
},
"average_sale": {
"value": 687.51871428570996,
"formatted": "688 р.",
"metric_name": null,
"attribution_model_id": null
},
"conversion_visits_to_leads": {
"value": 28.676470588234999,
"formatted": "29 %",
"metric_name": null,
"attribution_model_id": null
},
"sales": {
"value": "7",
"formatted": "7",
"metric_name": null,
"attribution_model_id": null
},
"revenue": {
"value": 4812.6310000000003,
"formatted": "4 813 р.",
"metric_name": null,
"attribution_model_id": null
},
"profit": {
"value": 2887.5790000000002,
"formatted": "2 888 р.",
"metric_name": null,
"attribution_model_id": null
},
"roi": {
"value": 596.31223836256004,
"formatted": "596 %",
"metric_name": null,
"attribution_model_id": null
},
"leads": {
"value": "39",
"formatted": "39",
"metric_name": null,
"attribution_model_id": null
},
"marketing_cost": {
"value": 414.69600000000003,
"formatted": "415 р.",
"metric_name": null,
"attribution_model_id": null
}
},
"dimensions": {
"marker_level_1": {
"value": "adwords2",
"title": "Google Adwords",
"icon": "https://favicon.yandex.net/favicon/google.com"
}
},
"isHasChild": 1
},
{
"metrics": {
"visits": {
"value": "173",
"formatted": "173",
"metric_name": null,
"attribution_model_id": null
},
"conversion_leads_to_sales": {
"value": 11.111111111111001,
"formatted": "11 %",
"metric_name": null,
"attribution_model_id": null
},
"average_sale": {
"value": 387.02199999999999,
"formatted": "387 р.",
"metric_name": null,
"attribution_model_id": null
},
"conversion_visits_to_leads": {
"value": 31.213872832370001,
"formatted": "31 %",
"metric_name": null,
"attribution_model_id": null
},
"sales": {
"value": "6",
"formatted": "6",
"metric_name": null,
"attribution_model_id": null
},
"revenue": {
"value": 2322.1320000000001,
"formatted": "2 322 р.",
"metric_name": null,
"attribution_model_id": null
},
"profit": {
"value": 774.04499999999996,
"formatted": "774 р.",
"metric_name": null,
"attribution_model_id": null
},
"roi": {
"value": 47.145654322864999,
"formatted": "47 %",
"metric_name": null,
"attribution_model_id": null
},
"leads": {
"value": "54",
"formatted": "54",
"metric_name": null,
"attribution_model_id": null
},
"marketing_cost": {
"value": 526.03999999999996,
"formatted": "526 р.",
"metric_name": null,
"attribution_model_id": null
}
},
"dimensions": {
"marker_level_1": {
"value": "direct1",
"title": "Yandex.Direct",
"icon": "https://favicon.yandex.net/favicon/www.direct.yandex.ru"
}
},
"isHasChild": 1
},
{
"metrics": {
"visits": {
"value": "102",
"formatted": "102",
"metric_name": null,
"attribution_model_id": null
},
"conversion_leads_to_sales": {
"value": 0,
"formatted": "0.00 %",
"metric_name": null,
"attribution_model_id": null
},
"average_sale": {
"value": 0,
"formatted": "0.00 р.",
"metric_name": null,
"attribution_model_id": null
},
"conversion_visits_to_leads": {
"value": 3.9215686274510002,
"formatted": "3.92 %",
"metric_name": null,
"attribution_model_id": null
},
"sales": {
"value": 0,
"formatted": "0",
"metric_name": null,
"attribution_model_id": null
},
"revenue": {
"value": 0,
"formatted": "0.00 р.",
"metric_name": null,
"attribution_model_id": null
},
"profit": {
"value": 0,
"formatted": "0.00 р.",
"metric_name": null,
"attribution_model_id": null
},
"roi": {
"value": -100,
"formatted": "-100 %",
"metric_name": null,
"attribution_model_id": null
},
"leads": {
"value": "4",
"formatted": "4",
"metric_name": null,
"attribution_model_id": null
},
"marketing_cost": {
"value": 311.06200000000001,
"formatted": "311 р.",
"metric_name": null,
"attribution_model_id": null
}
},
"dimensions": {
"marker_level_1": {
"value": "facebook5",
"title": "Facebook",
"icon": "https://favicon.yandex.net/favicon/facebook.com"
}
},
"isHasChild": 1
},
{
"metrics": {
"visits": {
"value": "105",
"formatted": "105",
"metric_name": null,
"attribution_model_id": null
},
"conversion_leads_to_sales": {
"value": 0,
"formatted": "0.00 %",
"metric_name": null,
"attribution_model_id": null
},
"average_sale": {
"value": 0,
"formatted": "0.00 р.",
"metric_name": null,
"attribution_model_id": null
},
"conversion_visits_to_leads": {
"value": 2.8571428571428998,
"formatted": "2.86 %",
"metric_name": null,
"attribution_model_id": null
},
"sales": {
"value": 0,
"formatted": "0",
"metric_name": null,
"attribution_model_id": null
},
"revenue": {
"value": 0,
"formatted": "0.00 р.",
"metric_name": null,
"attribution_model_id": null
},
"profit": {
"value": 0,
"formatted": "0.00 р.",
"metric_name": null,
"attribution_model_id": null
},
"roi": {
"value": -100,
"formatted": "-100 %",
"metric_name": null,
"attribution_model_id": null
},
"leads": {
"value": "3",
"formatted": "3",
"metric_name": null,
"attribution_model_id": null
},
"marketing_cost": {
"value": 336.887,
"formatted": "337 р.",
"metric_name": null,
"attribution_model_id": null
}
},
"dimensions": {
"marker_level_1": {
"value": "seo",
"title": "SEO",
"icon": "https://cloud.roistat.com/img/MagnifyingGlass.png"
}
},
"isHasChild": 1
},
{
"metrics": {
"visits": {
"value": "70",
"formatted": "70",
"metric_name": null,
"attribution_model_id": null
},
"conversion_leads_to_sales": {
"value": 40,
"formatted": "40 %",
"metric_name": null,
"attribution_model_id": null
},
"average_sale": {
"value": 359.79849999999999,
"formatted": "360 р.",
"metric_name": null,
"attribution_model_id": null
},
"conversion_visits_to_leads": {
"value": 7.1428571428570997,
"formatted": "7.1 %",
"metric_name": null,
"attribution_model_id": null
},
"sales": {
"value": "2",
"formatted": "2",
"metric_name": null,
"attribution_model_id": null
},
"revenue": {
"value": 719.59699999999998,
"formatted": "720 р.",
"metric_name": null,
"attribution_model_id": null
},
"profit": {
"value": 239.86600000000001,
"formatted": "240 р.",
"metric_name": null,
"attribution_model_id": null
},
"roi": {
"value": 11.695979957997,
"formatted": "12 %",
"metric_name": null,
"attribution_model_id": null
},
"leads": {
"value": "5",
"formatted": "5",
"metric_name": null,
"attribution_model_id": null
},
"marketing_cost": {
"value": 214.749,
"formatted": "215 р.",
"metric_name": null,
"attribution_model_id": null
}
},
"dimensions": {
"marker_level_1": {
"value": "vk4",
"title": "VKontakte",
"icon": "https://favicon.yandex.net/favicon/vk.com"
}
},
"isHasChild": 1
},
{
"metrics": {
"visits": {
"value": "68",
"formatted": "68",
"metric_name": null,
"attribution_model_id": null
},
"conversion_leads_to_sales": {
"value": 0,
"formatted": "0.00 %",
"metric_name": null,
"attribution_model_id": null
},
"average_sale": {
"value": 0,
"formatted": "0.00 р.",
"metric_name": null,
"attribution_model_id": null
},
"conversion_visits_to_leads": {
"value": 4.4117647058824003,
"formatted": "4.41 %",
"metric_name": null,
"attribution_model_id": null
},
"sales": {
"value": 0,
"formatted": "0",
"metric_name": null,
"attribution_model_id": null
},
"revenue": {
"value": 0,
"formatted": "0.00 р.",
"metric_name": null,
"attribution_model_id": null
},
"profit": {
"value": 0,
"formatted": "0.00 р.",
"metric_name": null,
"attribution_model_id": null
},
"roi": {
"value": -100,
"formatted": "-100 %",
"metric_name": null,
"attribution_model_id": null
},
"leads": {
"value": "3",
"formatted": "3",
"metric_name": null,
"attribution_model_id": null
},
"marketing_cost": {
"value": 198.08699999999999,
"formatted": "198 р.",
"metric_name": null,
"attribution_model_id": null
}
},
"dimensions": {
"marker_level_1": {
"value": "yamarket3",
"title": "Yandex.Market",
"icon": "https://favicon.yandex.net/favicon/market.yandex.ru"
}
},
"isHasChild": 1
}
],
"mean": {
"metrics": {
"visits": {
"value": 654,
"formatted": "654",
"metric_name": null,
"attribution_model_id": null
},
"conversion_leads_to_sales": {
"value": 13.888888888888999,
"formatted": "14 %",
"metric_name": null,
"attribution_model_id": null
},
"average_sale": {
"value": 523.62400000000002,
"formatted": "524 р.",
"metric_name": null,
"attribution_model_id": null
},
"conversion_visits_to_leads": {
"value": 16.513761467889999,
"formatted": "17 %",
"metric_name": null,
"attribution_model_id": null
},
"sales": {
"value": 15,
"formatted": "15",
"metric_name": null,
"attribution_model_id": null
},
"revenue": {
"value": 7854.3599999999997,
"formatted": "7 854 р.",
"metric_name": null,
"attribution_model_id": null
},
"profit": {
"value": 3901.4899999999998,
"formatted": "3 901 р.",
"metric_name": null,
"attribution_model_id": null
},
"roi": {
"value": 94.926258580349995,
"formatted": "95 %",
"metric_name": null,
"attribution_model_id": null
},
"leads": {
"value": 108,
"formatted": "108",
"metric_name": null,
"attribution_model_id": null
},
"marketing_cost": {
"value": 2001.521,
"formatted": "2 002 р.",
"metric_name": null,
"attribution_model_id": null
}
},
"dimensions": [],
"isHasChild": 0
},
"dateFrom": "2016-08-18T21:00:00+0000",
"dateTo": "2016-08-25T20:59:59+0000"
}
],
"status": "success"
}
Query String:
| Parameter | Type | Description | Required |
|---|---|---|---|
| project | string | Project number | yes |
Request Body:
| Parameter | Type | Description | Required |
|---|---|---|---|
| dimensions | array[string] | List of dimensions | yes |
| metrics | array | List of metrics. It can be both metric's name (string) and metric with some attribution model (object) | yes |
| > metric | string | Metric's system name. It can be found with the project/analytics/metrics method | no |
| > attribution | string | System name of an attribution model. It can be found with the /project/analytics/attribution-models method | no |
| period | object | Time period | yes |
| > from | string | Start date like 2016-07-01T00:00:00+0300 | yes |
| > to | string | End date like 2016-07-31T00:00:00+0300 | yes |
| filters | array[object] | Filters to limit data volume | no |
| > field | string | Parameter to be filtered by. It can be both metrics and dimensions. If field is a metric's name, the filter will be applied after the data is processed. If field is a dimension's name, the filter will be applied before data processing | no |
| > operation | string | Comparison operators: >, <, =, <>, >=, <=, in | no |
| > value | string or array[string] | Value of the metric/dimension to be filtered by | no |
| interval | string | Intervals to divide time period. Value in XmYwZd format: number of months(m), weeks(w) and/or days(d). E.g.: - 2w3d - a 2 weeks 3 days interval (7*2 +3 = 17 days); - 1m1w - a 1 month 1 week interval | no |
| next_dimensions | array[string] | no |
| Parameter | Type | Description |
|---|---|---|
| data | array[object] | |
| > items | array[object] | Data on metrics and dimensions for all period (period) or for separate intervals if specified in the request (interval) |
| >> metrics | object | Data on metrics for all period (period) or for separate intervals if specified in the request (interval) |
| >>> metric1 | object | Parameters of metric 1 |
| >>>> value | string or number | Metric value |
| >>>> formatted | string | Metric value in the Roistat interface. E.g., if the value of roi is 0, you'll see 0.00 % in the interface |
| >>>> metric_name | string | Metric's system name |
| >>>> attribution_model_id | null or string | Attribution model name used to calculate metrics |
| >>> metricN | object | Parameters of the next metric etc. |
| >>>> value | string or number | |
| >>>> formatted | string | |
| >>>> metric_name | string | |
| >>>> attribution_model_id | null or string | |
| >> dimensions | object | Data on dimensions for all period (period) or for separate intervals if specified in the request (interval) |
| >>> dimension1 | object | Parameters of dimension 1 |
| >>>> value | string | Dimension's system name |
| >>>> title | string | A human-readable dimension name (in the Roistat interface) |
| >>>> icon | string | URL where a dimension icon is stored |
| >>> dimensionN | object | Parameters of the next dimension etc. |
| >>>> value | string | |
| >>>> title | string | |
| >>>> icon | string | |
| >> isHasChild | integer | This characteristic relates to degree of report detailization Namely, whether data on a specific metric can be divided into other dimensions' groupings. Or simply, whether it is possible to add one more ("lower") level to the current one: 1 - it can have a lower level, 0 - can't have lower levels. E.g., statistics on direct visits can be presented only as one-level report, with no detailization, i.e. it can be presented only for all direct visits altogether. |
| > mean | object | Total and average metric values for the chosen period (the "in total/average" row in reports) |
| >> metrics | object | |
| >>> metric1 | object | Total/average value of metric 1 |
| >>>> value | string or number | |
| >>>> formatted | string | |
| >>>> metric_name | string | |
| >>>> attribution_model_id | null or string | |
| >>> metricN | object | Total/average value of metric 2 etc. |
| >>>> value | string or number | |
| >>>> formatted | string | |
| >>>> metric_name | string | |
| >>>> attribution_model_id | null or string | |
| > dateFrom | string | Start date of the period (the from parameter in the request body) |
| > dateTo | string | End date of the period (the to parameter in the request body) |
| status | string |
Get analytical reports in the Excel format¶
POST /project/analytics/data/export/excelThis API method is similar to the /project/analytics/data method, but it returns an Excel file with a report.
WARNING! In that case, the following parameters cannot be used in the request body: interval and next_dimensions.
There are no other differences.
curl 'https://cloud.roistat.com/api/v1/project/analytics/data/export/excel?project=12345' \
--request POST \
--header 'Content-type: application/json' \
--header 'Api-key: {KEY}' \
--data Request body - see below
Request Body:
{
"dimensions": [
"marker_level_1",
"marker_level_2"
],
"metrics": [
"visits",
"leads",
"sales",
"marketing_cost",
"roi",
{
"metric": "profit",
"attribution": "first_click"
}
],
"period": {
"from": "2016-07-01T00:00:00+0300",
"to": "2016-07-31T23:59:59+0300"
},
"filters": [
{
"field": "marker_level_1",
"operation": "in",
"value": [
"site1",
"site2",
"site3"
]
},
{
"field": "roi",
"operation": ">",
"value": "0"
}
],
"interval": "1w",
"next_dimensions": [
"marker_level_2"
]
}
An Excel file.
Query String:
| Parameter | Type | Description | Required |
|---|---|---|---|
| project | string | Project number | yes |
Request Body:
| Parameter | Type | Description | Required |
|---|---|---|---|
| dimensions | array[string] | List of dimensions | yes |
| metrics | array | List of metrics. It can be both metric's name (string) and metric with some attribution model (object) | yes |
| > metric | string | Metric's system name. It can be found with the project/analytics/metrics method | no |
| > attribution | string | System name of an attribution model. It can be found with the /project/analytics/attribution-models method | no |
| period | object | Time period | yes |
| > from | string | Start date like 2016-07-01T00:00:00+0300 | yes |
| > to | string | End date like 2016-07-31T00:00:00+0300 | yes |
| filters | array[object] | Filters to limit data volume | no |
| > field | string | Parameter to be filtered by. It can be both metrics and dimensions. If field is a metric's name, the filter will be applied after the data is processed. If field is a dimension's name, the filter will be applied before data processing | no |
| > operation | string | Comparison operators: >, <, =, <>, >=, <=, in | no |
| > value | string or array[string] | Value of the metric/dimension to be filtered by | no |
| interval | string | Intervals to divide time period. Value in XmYwZd format: number of months(m), weeks(w) and/or days(d). E.g.: - 2w3d - a 2 weeks 3 days interval (7*2 +3 = 17 days); - 1m1w - a 1 month 1 week interval | no |
| next_dimensions | array[string] | no |
An Excel file.
Get a list of available metrics¶
POST /project/analytics/metrics-newReturns a list of available metrics. See /project/analytics/data for details.
curl 'https://cloud.roistat.com/api/v1/project/analytics/metrics-new?project=12345' \
--request POST \
--header 'Content-type: application/json' \
--header 'Api-key: {KEY}'
{
"metrics": [
{
"name": "impressions",
"title": "Impressions",
"info": "Number of impressions for ad campaign",
"group": "visitsAndConversions",
"is_has_attribution_model": false,
"is_absolute": true,
"order": 98,
"type": "integer",
"formula": "{impressions} ? {impressions} : 0"
}
],
"status": "success"
}
Query String:
| Parameter | Type | Description | Required |
|---|---|---|---|
| project | string | Project number | yes |
Request Body:
No parameters.
| Parameter | Type | Description |
|---|---|---|
| metrics | array[object] | |
| > name | string | System name of metric |
| > title | string | human-readable name of metric |
| > info | string | short description of metric |
| > group | string | system name of the group of metrics that this metric belongs to in Roistat |
| > is_has_attribution_model | boolean | flag that specifies if the metric uses and attribution model. |
| > is_absolute | boolean | flag that specifies the calculation type.: - true - absolute metric, e.g. Revenue, number of clicks, etc.; - false - relative metrics, e.g. CPO, CPC, etc. |
| > order | integer | sort order of the metric in the reports |
| > type | string | metric type: - integer, percent or money. |
| > formula | string | formula to calculate the metric |
| status | string |
Get a list of available dimensions¶
POST /project/analytics/dimensionsReturns a list of available dimensions. For more details see /project/analytcs/data.
curl 'https://cloud.roistat.com/api/v1/project/analytics/dimensions?project=12345' \
--request POST \
--header 'Content-type: application/json' \
--header 'Api-key: {KEY}'
{
"dimensions": [
{
"name": "marker_level_1",
"title": "Source (level 1)",
"order": 100
},
{
"name": "marker_level_2",
"title": "Source (level 2)",
"order": 200
},
{
"name": "marker_level_3",
"title": "Source (level 3)",
"order": 300
},
{
"name": "marker_level_4",
"title": "Source (level 4)",
"order": 400
},
{
"name": "marker_level_5",
"title": "Source (level 5)",
"order": 500
},
{
"name": "marker_level_6",
"title": "Source (level 6)",
"order": 600
},
{
"name": "marker_level_7",
"title": "Source (level 7)",
"order": 700
},
{
"name": "utm_source",
"title": "utm_source",
"order": 800
},
{
"name": "utm_medium",
"title": "utm_medium",
"order": 900
},
{
"name": "utm_campaign",
"title": "utm_campaign",
"order": 1000
},
{
"name": "utm_term",
"title": "utm_term",
"order": 1100
},
{
"name": "utm_content",
"title": "utm_content",
"order": 1200
},
{
"name": "roistat_param1",
"title": "roistat_param1",
"order": 1300
},
{
"name": "roistat_param2",
"title": "roistat_param2",
"order": 1400
},
{
"name": "roistat_param3",
"title": "roistat_param3",
"order": 1500
},
{
"name": "roistat_param4",
"title": "roistat_param4",
"order": 1600
},
{
"name": "roistat_param5",
"title": "roistat_param5",
"order": 1700
},
{
"name": "host",
"title": "Host",
"order": 1800
},
{
"name": "landing_page",
"title": "Landing page",
"order": 1900
},
{
"name": "referrer",
"title": "Referrer",
"order": 2000
},
{
"name": "referrer_host",
"title": "Referrer host",
"order": 2100
},
{
"name": "country",
"title": "Country",
"order": 2200
},
{
"name": "city",
"title": "City",
"order": 2300
},
{
"name": "device",
"title": "Device",
"order": 1005002
},
{
"name": "browser",
"title": "Browser",
"order": 1005003
},
{
"name": "ad_position_type",
"title": "Ad position type",
"order": 2400
},
{
"name": "ad_position",
"title": "Ad position",
"order": 2500
},
{
"name": "daily",
"title": "Daily",
"order": 2700
},
{
"name": "weekly",
"title": "Weekly",
"order": 2900
},
{
"name": "monthly",
"title": "Monthly",
"order": 3000
},
{
"name": "order_field_21",
"title": "customer_id",
"order": 3200
},
{
"name": "order_field_4",
"title": "Order status",
"order": 3300
},
{
"name": "order_field_5",
"title": "City",
"order": 3400
},
{
"name": "order_field_23",
"title": "Delivery date",
"order": 3500
},
{
"name": "order_field_22",
"title": "Shipping date",
"order": 3600
},
{
"name": "order_field_11",
"title": "Send date",
"order": 3700
},
{
"name": "order_field_3",
"title": "Designer",
"order": 3800
},
{
"name": "order_field_7",
"title": "Cashier",
"order": 3900
},
{
"name": "order_field_1",
"title": "Number of items",
"order": 4000
},
{
"name": "order_field_13",
"title": "Coupon",
"order": 4100
},
{
"name": "order_field_9",
"title": "Operator",
"order": 4200
},
{
"name": "order_field_19",
"title": "Return cause",
"order": 4300
},
"name": "event_meta_id",
"title": "Events",
"order": 3100
},
{
"name": "hours",
"title": "Hours",
"order": 2600
},
{
"name": "week_days",
"title": "Week days",
"order": 2800
},
{
"name": "device_type",
"title": "Device type",
"order": 1005001
}
],
"status": "success"
}
Query String:
| Parameter | Type | Description | Required |
|---|---|---|---|
| project | string | Project number | yes |
Request Body:
No parameters.
| Parameter | Type | Description |
|---|---|---|
| dimensions | array[object] | |
| > name | string | Dimension's system name |
| > title | string | A human-readable dimension name |
| > order | integer | The way dimensions (= levels) are sorted in reports |
| status | string |
Get dimensions (e.g. Direct visits, Visits from websites) available for a specific grouping type¶
POST /project/analytics/dimension-valuesThis method allows to obtain dimensions (e.g. Direct visits, Visits from websites) available for a specific grouping type (e.g. Source (level 1), Domain).
curl 'https://cloud.roistat.com/api/v1/project/analytics/dimension-values?project=12345&dimension=marker_level_1' \
--request POST \
--header 'Content-type: application/json' \
--header 'Api-key: {KEY}'
{
"values": [
{
"value": "",
"title": "Direct visits"
},
{
"value": "site",
"title": "Visits from the site"
},
{
"value": "seo",
"title": "SEO"
}
],
"status": "success"
}
Query String:
| Parameter | Type | Description | Required |
|---|---|---|---|
| project | string | Project number | yes |
| dimension | string | Dimension system name (you can get it using /project/analytics/dimensions) | yes |
Request Body:
No parameters.
| Parameter | Type | Description |
|---|---|---|
| values | array[object] | |
| > value | string | System name |
| > title | string | A human-readable name |
| status | string |
Get a list of attribution models¶
POST /project/analytics/attribution-modelsA method for obtaining a list of attribution models.
curl 'https://cloud.roistat.com/api/v1/project/analytics/attribution-models?project=12345' \
--request POST \
--header 'Content-type: application/json' \
--header 'Api-key: {KEY}'
{
"models": [
{
"id": "default",
"name": "Standard attribution model",
"is_system": true
},
{
"id": "ushape",
"name": "UShape",
"is_system": true
},
{
"id": "first_click",
"name": "First click",
"is_system": true
},
{
"id": "last_click",
"name": "Last click",
"is_system": true
}
],
"status": "success"
}
Query String:
| Parameter | Type | Description | Required |
|---|---|---|---|
| project | string | Project number | yes |
Request Body:
No parameters.
| Parameter | Type | Description |
|---|---|---|
| models | array[object] | |
| > id | string | System name of an attribution model |
| > name | string | A human-readable name of the attribution name |
| > is_system | boolean | Attribution models can be: - system - they are available in Roistat by default; - custom - they are configured manually by a user |
| status | string |
Set values for custom metrics¶
POST /project/analytics/metrics/custom/manual/value/addUse this method to set values for custom metrics. To get the list of all custom metrics, use /project/analytics/metrics/custom/manual/list.
curl 'https://cloud.roistat.com/api/v1/project/analytics/metrics/custom/manual/value/add?project=12345' \
--request POST \
--header 'Content-type: application/json' \
--header 'Api-key: {KEY}' \
--data Request body - see below
Request Body:
{
"manual_custom_metric_id": 4,
"source": "Direct visits",
"value": 9999,
"period": {
"from": "2021-03-31T21:00:00",
"to": "2021-04-13T20:59:59"
}
}
No parameters.
Query String:
| Parameter | Type | Description | Required |
|---|---|---|---|
| project | string | Project number | yes |
Request Body:
| Parameter | Type | Description | Required |
|---|---|---|---|
| manual_custom_metric_id | number | custom metric ID (to get it, use /project/analytics/metrics/custom/manual/list) | no |
| source | string | source / marketing channel | no |
| value | number | metric value | no |
| period | object | period (use UTC+0 format) | no |
| > from | string | no | |
| > to | string | no |
No parameters.
Get the list of all custom metrics¶
GET /project/analytics/metrics/custom/listUse this method to get the list of all custom metrics.
curl 'https://cloud.roistat.com/api/v1/project/analytics/metrics/custom/list?project=12345' \
--request GET \
--header 'Content-type: application/json' \
--header 'Api-key: {KEY}'
{
"data": [
{
"id": 4,
"title": "Начатые чаты",
"type": "integer",
"creation_date": "2021-03-05T12:05:38+0000",
"is_used_in_custom_metric": false
},
{
"id": 3,
"title": "Показанные телефоны",
"type": "integer",
"creation_date": "2021-03-05T12:05:30+0000",
"is_used_in_custom_metric": false
}
],
"total": 2,
"status": "success"
}
Query String:
| Parameter | Type | Description | Required |
|---|---|---|---|
| project | string | Project number | yes |
Request Body:
No parameters.
| Parameter | Type | Description |
|---|---|---|
| data | array[object] | |
| > id | number | metric ID |
| > title | string | metric title |
| > type | string | metric type |
| > creation_date | string | metric creation date |
| > is_used_in_custom_metric | boolean | flag that specifies if the metric is used in other custom metrics |
| total | integer | |
| status | string |
Get the "Statuses Funnel" Report Data¶
POST /project/reports/funnel/dataUse this method to get the "Statuses Funnel" Report Data.
curl 'https://cloud.roistat.com/api/v1/project/reports/funnel/data?project=12345' \
--request POST \
--header 'Content-type: application/json' \
--header 'Api-key: {KEY}' \
--data Request body - see below
Request Body:
{
"period": {
"from": "2022-01-31T21:00:00.000Z",
"to": "2022-02-28T20:59:59.999Z"
},
"filters": [
{
"field": "marker_level_1",
"operator": "=",
"value": "google1"
}
],
"funnel": [
{
"title": "In Progress",
"statuses": ["0","1","2"],
"order": "1"
},
{
"title": "Paid",
"statuses": ["3"],
"order": "2"
}
],
"dimensions": ["marker_level_1"],
"next_dimensions": ["marker_level_2"]
}
{
"data": {
"date_from": "2022-01-31T21:00:00+0000",
"date_to": "2022-02-28T20:59:59+0000",
"items":[
{
"dimensions": {
"marker_level_1": {
"icon": "https:\/\/cloud.roistat.com\/img\/engines\/ga.png",
"title": "Google Ads",
"value": "google1"
}
},
"metrics": {
"visits": 2139,
"marketing_cost": 53586.983999999997,
"leads": 99
},
"funnel": {
"1": {
"cost": 541.27272727272725,
"count": 99,
"conversion": 4.6283309957924264,
"status_duration": 29.016828703703705
},
"2": {
"cost": 1531.0285714285715,
"count": 35,
"conversion": 35.353535353535356,
"status_duration": 17.214733796296297
}
},
"is_has_children": true
}
],
"mean": {
"1": {
"cost": 541.27272727272725,
"count": 99,
"conversion": 4.6283309957924264,
"status_duration": 29.016828703703705
},
"2": {
"cost": 1531.0285714285715,
"count": 35,
"conversion": 35.353535353535356,
"status_duration": 17.214733796296297
}
}
},
"status": "success"
}
Query String:
| Parameter | Type | Description | Required |
|---|---|---|---|
| project | string | Project number | yes |
Request Body:
| Parameter | Type | Description | Required |
|---|---|---|---|
| period | object | Time period | yes |
| > from | string | Start date like 2016-07-01T00:00:00+0300 | yes |
| > to | string | End date like 2016-07-31T00:00:00+0300 | yes |
| filters | array[object] | Filters to limit data volume | no |
| > field | string | Parameter to be filtered by. It can be both metrics and dimensions. If field is a metric's name, the filter will be applied after the data is processed. If field is a dimension's name, the filter will be applied before data processing | no |
| > operator | string | Comparison operators: >, <, =, <>, >=, <=, in | no |
| > value | string or array[string] | Value of the metric/dimension to be filtered by | no |
| funnel | array[object] | Information about the funnels for which you want to upload data | yes |
| > title | string | Status group name: Unsorted, In progress, Awaiting payment or Paid | yes |
| > statuses | array[string] | Funnel status IDs in the Roistat system (to get status IDs, use /project/integration/order/list) | yes |
| > order | string | Sequence number of the funnel in the response | yes |
| dimensions | array[string] | List of dimensions | yes |
| next_dimensions | array[string] | Next level in the report (for example, if you pass the value "marker_level_2", the is_has_children parameter in the response will indicate whether this report level exists for each source) | yes |
| Parameter | Type | Description |
|---|---|---|
| data | array[object] | |
| > date_from | string | Start date of the period (the from parameter in the request body) |
| > date_to | string | End date of the period (the to parameter in the request body) |
| > items | array[object] | Data on metrics, dimensions, and funnels for all period (period) |
| >> dimensions | object | Data on dimensions for all period (period) |
| >>> value | string | Dimension's system name |
| >>> title | string | A human-readable dimension name (in the Roistat interface) |
| >>> icon | string | URL where a dimension icon is stored |
| >> metrics | array[object] | Data on metrics for all period (period) |
| >> funnel | array[object] | Data on specified funnels (displayed in the order specified in the order parameter) |
| >>> cost | string | Cost |
| >>> count | string | Number of leads that passed through the status |
| >>> conversion | string | Conversion |
| >>> status_duration | string | Total time the deals were in the status |
| >> is_has_children | boolean | Parameter indicating whether the next level of the report exists for this grouping (next level is specified in next_dimensions) |
| > mean | object | Total and average values of the corresponding metrics for the selected time period (data for each funnel is displayed in the order specified in the order parameter) |
| >> cost | string | Cost |
| >> count | string | Number of leads that passed through the status |
| >> conversion | string | Conversion |
| >> status_duration | string | Total time the deals were in the status |
| status | string |