getAnalyticsData method¶
getAnalyticsData¶
General description. The method returns a report with analytics data for a specific project. Reports are built offline. This means you need to poll the API to find out whether the report is ready. Method: POST URL: https://api.r7k12.com/{{TOKEN}}/getAnalyticsData Headers. Required header “Content-Type: application/json; charset=UTF-8” Request parameters:
{
"name": (string),
"metrics": [(string),...],
"dimensions": [(string),...],
"date": ("today"|"yesterday"|...|"last 30 day")|[(string),...],
"query": (string),
"bots": (bool),
"eventData":(bool),
"page": (int)
}
Table 1 - Parameter descriptions
| Parameter | Type | Description | Required |
| name | string | Report name | Yes |
| metrics | array of string | Report metrics (described in table 2) | Yes |
| dimensions | array of string | Report dimensions (described in table 2). If an invalid report dimension is specified, it will be skipped. | Yes |
| date | string or array of string | Date range type / date interval. today - today yesterday - yesterday week - current week month - current month previous week - previous week previous month - previous month last 7 day - last 7 days last 10 day - last 10 days last 14 day - last 14 days last 30 day - last 30 days [ ‘Y-m-d’, ‘Y-m-d’ ] - Date interval | Yes |
| query | string | Report filter (table 3) | No |
| bots | bool | Exclude bots | No |
| eventDate | bool | Use event dates | No |
| page | int | Requested page number | No |
Table 2 - Filter descriptions
| Filters | ||
| == | Exact match | source1==yandex |
| != | Does not match | source1!=yandex |
| =@ | Contains substring | source1=@yandex |
| !@ | Does not contain substring | source1!@yandex |
| =~ | Contains a match for the regular expression | source1=~yandex |
| !~ | Does not match the regular expression | source1!~yandex |
| Combining | ||
| , | Logical “OR” | source1==yandex,source1==google |
| ; | Logical “AND” | source1==yandex;source1==google |
| *When building filters, logical “OR” takes precedence over “AND”. Example: a filter such as source1==yandex;source1==google,source1=facebook will match (source1 == ‘yandex’ && source1== ’google’) | (source1 == ‘facebook’)* |
Response handling:
{
"name": (string),
"status": (string),
"fields": (array of object) [
{
"name": (string),
"type": (string),
"category": (string),
"description": (string)
},
…….
],
"totals": (object),
"count": (int),
"interval": (object) {
"from": (string),
"to": (string)
},
"pages": (int),
"page": (int),
"data": (array of array),
"error": (object){
"code": (int),
"error": (string),
"error_detail": (string)
}
}
Table 3 - Response fields
| Name | Type | Description | Present |
| name | string | Report name | Yes (if status - ready) |
| status | string | Report build status. The main response parameter, where processing should start. Possible values: process - the report is being built. In this case only the “status” field is returned. To check whether the report is ready, repeat the request with the same parameters after some time. The interval is determined by whether the response contains the “retryIn” header - if this header is present, the request must be repeated after the number of seconds specified in it; otherwise the request is repeated after an interval of at least 5 seconds - otherwise you will get an API error. Checking the retryIn header is mandatory. ready - the report is ready. error - report build error | Yes |
| fields | array of object | Description of the fields included in the report. The fields are listed in the same order in which they appear in the “data” array. | Yes (if status - ready) |
| fields[index].name | string | Field name (dimension/metric) | Yes (if status - ready) |
| fields[index].type | string | Field type: INTEGER | FLOAT |
| fields[index].category | string | Field category (dimension/metric): dimensions | metrics |
| fields[index].description | string | Field description | Yes (if status - ready) |
| totals | object | An object containing the totals for each report metric. | Yes (if status - ready) |
| count | int | total number of rows in the report | Yes (if status - ready) |
| interval | object | The date interval for which the report was built | Yes (if status - ready) |
| interval.from | string | Start date in the format: Y-m-d | Yes (if status - ready) |
| interval.to | string | End date in the format: Y-m-d | Yes (if status - ready) |
| pages | int | Number of report pages. One page contains no more than 10000 result rows. If there is more than 1 page, repeat the request with the “page” parameter | Yes (if status - ready) |
| page | int | Number of the requested report page | Yes (if status - ready) |
| data | array of array | Array with the report data. Each row is returned as a separate array. The order of the elements in the row arrays matches the order of the field descriptions in the “fields” element | Yes (if status - ready) |
| error | object | Analytics report build error. Not to be confused with API errors | Yes (if status - error) |
| error.code | int | Error code | Yes (if status - error) |
| error.error | string | Error | Yes (if status - error) |
| error.error_detail | string | Error description | Yes (if status - error) |
Method limits:
- No more than 60 reports can be stored on the server at the same time
- Reports are stored for one hour
- The resulting report cannot contain more than 1 million rows
- The amount of processed data cannot exceed 20 Gb
- Send a repeat request to check the report status no earlier than 5 seconds later, or after the number of seconds specified in the “retryIn” header.
Table 4 - Report build errors
| Code | Error | Description |
| 101 | Invalid input parameter. | The required field 'name' (Report name) is not set. Allowed characters: 0-9,A-Z,a-z,А-Я,а-я,-,_,(,), (space). |
| 102 | Invalid input parameter. | The required field 'metrics' (Report metrics) is not set or has an invalid format. |
| 103 | Invalid input parameter. | The required field 'dimensions' (Report dimensions) is not set or has an invalid format. |
| 104 | Invalid input parameter. | The 'date' field (Report period) contains an invalid value. |
| 105 | Quota exceeded. | No more than 60 reports can be stored on the server at the same time. Reports are stored for 1 hour. |
| 106 | Invalid input parameter. | The input parameter 'page' contains an invalid value. |
| 111 | Quota exceeded. | A report can contain no more than 1 million records. |
| 112 | Quota exceeded. | No more than 1 request per 5 seconds is allowed. |
| 117 | Quota exceeded. | The quota for the volume of processed data has been exceeded. |
| 0 | Unknown error |
Example method call (PHP):
define('TOKEN','YOURTOKEN');
function POST ($request) {
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.r7k12.com/'.TOKEN.'/getAnalyticsData');
curl_setopt($curl, CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($request,JSON_UNESCAPED_UNICODE));
$out = curl_exec($curl);
curl_close($curl);
return json_decode($out,true);
}
$response = POST(
[
'name' => 'API R7K12',
'metrics' => [
'sessions',
'cost',
'impressions'
],
'dimensions' => [
'nameProject',
'idProject'
],
'date' => 'today',
'bots' => true,
'eventDate' => false
]
);
print_r($response);