Перейти до змісту

Метод 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)

Обмеження методу:

  1. Одночасно на сервері може зберігатися не більше 60 звітів
  2. Звіти зберігаються протягом однієї години
  3. Підсумковий звіт не може містити більше 1 млн рядків
  4. Обсяг оброблюваних даних не може перевищувати 20 Gb
  5. Повторний запит на перевірку статусу звіту надсилати не раніше ніж через 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);