Метод getAnalyticsData¶
getAnalyticsData¶
Загальний опис. Метод дає змогу отримати звіт із даними аналітики за конкретним проєктом. Звіти будуються в офлайн-режимі. Тобто необхідно опитувати API щодо готовності звіту. Метод: POST Посилання: https://api.r7k12.com/{{TOKEN}}/getAnalyticsData Заголовки. Обов’язковий заголовок «Content-Type: application/json; charset=UTF-8» Параметри запиту:
{
"name": (string),
"metrics": [(string),...],
"dimensions": [(string),...],
"date": ("today"|"yesterday"|...|"last 30 day")|[(string),...],
"query": (string),
"bots": (bool),
"eventData":(bool),
"page": (int)
}
Таблиця 1 - Опис параметрів
| Параметр | Тип | Опис | Обов’язковий |
| name | string | Назва звіту | Так |
| metrics | array of string | Показники звіту (опис у таблиці 2) | Так |
| dimensions | array of string | Параметри звіту (опис у таблиці 2). Якщо вказати некоректний параметр звіту, його буде пропущено. | Так |
| date | string or array of string | Тип діапазону дат / інтервал дат. today - сьогодні yesterday - вчора week - поточний тиждень month - поточний місяць previous week - попередній тиждень previous month - попередній місяць last 7 day - останні 7 днів last 10 day - останні 10 днів last 14 day - останні 14 днів last 30 day - останні 30 днів [ ‘Y-m-d’, ‘Y-m-d’ ] - Інтервал дат | Так |
| query | string | Фільтр побудови звіту (таблиця 3) | Ні |
| bots | bool | Не враховувати ботів | Ні |
| eventDate | bool | Враховувати дати події | Ні |
| page | int | Номер сторінки, що запитується | Ні |
Таблиця 2 - Опис фільтрів
| Фільтри | ||
| == | Точна відповідність | source1==yandex |
| != | Не відповідає | source1!=yandex |
| =@ | Містить підрядок | source1=@yandex |
| !@ | Не містить підрядка | source1!@yandex |
| =~ | Містить збіг для регулярного виразу | source1=~yandex |
| !~ | Не відповідає регулярному виразу | source1!~yandex |
| Об’єднання | ||
| , | Логічне «АБО» | source1==yandex,source1==google |
| ; | Логічне «І» | source1==yandex;source1==google |
| *Під час формування фільтрів логічне «АБО» має пріоритет над «І». Приклад: фільтр виду source1==yandex;source1==google,source1=facebook відповідатиме (source1 == ‘yandex’ && source1== ’google’) | (source1 == ‘facebook’)* |
Обробка відповіді:
{
"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)
}
}
Таблиця 3 - Поля відповіді
| Назва | Тип | Опис | Наявність |
| name | string | Назва звіту | Так (якщо status - ready) |
| status | string | Статус побудови звіту. Головний параметр відповіді, з якого необхідно починати обробку. Можливі варіанти: process - звіт перебуває на етапі побудови. У цьому разі повертається лише поле «status». Щоб перевірити готовність звіту, необхідно повторити запит із тими самими параметрами через певний інтервал часу. Інтервал часу визначається залежно від наявності у відповіді заголовка «retryIn» - якщо цей заголовок присутній, то повторний запит необхідно надіслати через кількість секунд, зазначену в цьому заголовку, інакше запит повторюється через інтервал часу не менше 5 секунд - інакше буде отримано помилку API. Перевірка заголовка retryIn є обов’язковою. ready - звіт готовий. error - помилка побудови звіту | Так |
| fields | array of object | Опис полів, що виводяться у звіт. Поля вказано в тому порядку, в якому вони виводяться в масиві «data». | Так (якщо status - ready) |
| fields[index].name | string | Назва поля (параметра/показника) | Так (якщо status - ready) |
| fields[index].type | string | Тип поля: INTEGER | FLOAT |
| fields[index].category | string | Категорія поля (параметр/показник): dimensions | metrics |
| fields[index].description | string | Опис поля | Так (якщо status - ready) |
| totals | object | Об’єкт, що містить підсумкові дані за кожним показником звіту. | Так (якщо status - ready) |
| count | int | загальна кількість рядків у звіті | Так (якщо status - ready) |
| interval | object | Інтервал дат, за який було побудовано звіт | Так (якщо status - ready) |
| interval.from | string | Початкова дата у форматі: Y-m-d | Так (якщо status - ready) |
| interval.to | string | Кінцева дата у форматі: Y-m-d | Так (якщо status - ready) |
| pages | int | Кількість сторінок звіту. На одній сторінці виводиться не більше 10000 рядків результату. Якщо сторінок більше 1, то необхідно повторити запит із зазначенням параметра «page» | Так (якщо status - ready) |
| page | int | Номер сторінки звіту, що запитується | Так (якщо status - ready) |
| data | array of array | Масив із даними звіту. Кожен рядок виводиться в окремому масиві. Послідовність елементів у масивах рядків відповідає послідовності опису полів в елементі «fields» | Так (якщо status - ready) |
| error | object | Помилка побудови звіту аналітики. Не плутати з помилками API | Так (якщо status - error) |
| error.code | int | Код помилки | Так (якщо status - error) |
| error.error | string | Помилка | Так (якщо status - error) |
| error.error_detail | string | Опис помилки | Так (якщо status - error) |
Обмеження методу:
- Одночасно на сервері може зберігатися не більше 60 звітів
- Звіти зберігаються протягом однієї години
- Підсумковий звіт не може містити більше 1 млн рядків
- Обсяг оброблюваних даних не може перевищувати 20 Gb
- Повторний запит на перевірку статусу звіту надсилати не раніше ніж через 5 сек. або через кількість секунд, зазначену в заголовку «retryIn».
Таблиця 4 - Помилки побудови звіту
| Код | Помилка | Опис |
| 101 | Некоректний вхідний параметр. | Не задано обов’язкове поле 'name' (Назва звіту). Допустимі символи: 0-9,A-Z,a-z,А-Я,а-я,-,_,(,), (пробіл). |
| 102 | Некоректний вхідний параметр. | Не задано обов’язкове поле 'metrics' (Показники звіту), або воно має неприпустимий формат. |
| 103 | Некоректний вхідний параметр. | Не задано обов’язкове поле 'dimensions' (Параметри звіту), або воно має неприпустимий формат. |
| 104 | Некоректний вхідний параметр. | Поле 'date' (Період звіту) містить некоректне значення. |
| 105 | Перевищено квоту. | Одночасно на сервері може зберігатися не більше 60 звітів. Звіти зберігаються 1 годину. |
| 106 | Некоректний вхідний параметр. | Вхідний параметр 'page' містить некоректне значення. |
| 111 | Перевищено квоту. | Звіт може містити не більше 1 млн записів. |
| 112 | Перевищено квоту. | Дозволено не більше 1 запиту протягом 5 секунд. |
| 117 | Перевищено квоту. | Перевищено квоту обсягу оброблюваних даних. |
| 0 | Невідома помилка |
Приклад виклику методу (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);