Skip to content

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/data

Overview

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/excel

This 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-new

Returns 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/dimensions

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

This 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-models

A 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/add

Use 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/list

Use 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/data

Use 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