Адрес сервиса статистики: https://stats.terratraf.com/api/

Спецификация

Обращение к сервису выполняется по протоколу JSON-RPC 2.0. Подробнее о спецификации протокола можете прочитать в официальных источниках.

При обращении к API в GET-параметрах необходимо передавать метод из тела запроса, например:

curl -X POST -d '{
  "jsonrpc": "2.0",
  "method":"namespace.method",
  "params": {
    "param1": "value1",
    "param2": "value2"
  },
  "id": 1
}' https://localhost/?namespace.method

Получение статистики для источника

Для получения статистики необходимо вызвать метод "stat.getForSource".

Параметры запроса

Название	Описание	Тип
token	Токен источника	string
filter	Фильтр	object

Токен источника

Список доступных токенов находится на странице Source access. Если у вас нет в меню данного раздела, то обратитесь за доступом к Администратору.

Для каждого источника существует свой токен доступа. Если в запросе Вы не зададите фильтр "sourсe", то в результате вернется статистика по источнику, которому принадлежит указанный в параметрах запроса токен.

Если Вы хотите получить статистику сразу по всем источникам, то можете использовать любой доступный вам токен, но дополнительно задать фильтр "source": ["all"].

Параметры объекта filter

В таблице ниже описаны все возможные фильтры. В зависимости прав пользователя могут быть не доступны некоторые фильтры, группировки или срезы.

Название	Описание	Тип
date_from	Дата начала. В формате Год-месяц-день. (Обязательное поле).	date
date_to	Дата окончания. В формате Год-месяц-день. (Обязательное поле).	date
timezone	Смещение времени по GMT. Возможные значения: Etc/GMT+0 Etc/GMT-1 Etc/GMT+3	string
main_group	Группировка значений. "date_day" - группировка по дню, "date_hour" - по часам, "date_week" - по неделям, "date_month" - по месяцам, "partner" - по партнерам, "camp" - по кампаниям, "creative" - по креативам, "source" - по источникам, "country" - по странам, "format" - по форматам, "os" - по операционным системам, "browser" - по браузерам, "network" - по рекламным сетям (площадкам).	array of string
side_group	Срез данных по: "source" - по источникам, "source_geo" - источник + ГЕО, "source_format" - источник + формат, "source_placement" - источник + площадка, "source_os" - источник + ОС, "source_browser" - источник + браузер.	array of string
format	Формат креатива, задается только для среза данных по источникам + формат. Возможные значения: "v", "t" и "b" (видео, тизер и баннер соответственно).	string
source	Список доступных источников. Для отображения всех источников указывается значение: ["all"]	array of string
country	Список стран. Для отображения всех стран указывается значение: ["all"]	array of string
placement	Список площадок. Для отображения всех площадок указывается значение: ["all"]	array of string
os	Список операционных систем. Для отображения всех ОС указывается значение: ["all"]	array of string
browser	Список браузеров. Для отображения всех браузеров указывается значение: ["all"]	array of string
network	Список рекламных сетей (площадок). Для отображения всех площадок указывается значение: ["all"]	array of string

Параметры ответа

В ответе будет возвращен массив объектов. Объекты могут содержать следующие поля:

"source" - наименование источника,
"creative" - уникальный ID креатива,
"bid" - идентификатор ответа (response),
"shows" - количество показов,
"win_rate" - показатель выигрыша, т.е. процентное соотношение количества выигранных показов к количеству всех показов,
"clicks" - количество кликов,
"avg_cpm" - среднее значение CPM,
"request" - количество запросов,
"date_day" - день, для срезов по дням,
"date_hour" - час, для срезов по часам,
"date_week" - неделя, для срезов по неделям,
"date_month" - месяц, для срезов по месяцам,
"fill_rate" - наполняемость, т.е. процентное соотношение количества выполненных показов к количеству запросов,
"format" - тип креатива: баннер, видео, тизер. Например, "b728x90" - это баннер размера 728x90px,
"placement" - ID площадки,
"os" - название операционной системы,
"browser" - название браузера,
"network" - название рекламной сети (площадки).

🚧
Обратите внимание
Набор полей в ответе индивидуален для пользователя и зависит от выставленных в запросе фильтров.

Пример использования метода

// Запрос
curl -X POST -d '{
    "jsonrpc": "2.0",
    "method":"stat.getForSource",
    "params":{
        "token": "FNhw...KZc",
        "filter": {
            "date_from":"2023-08-01",
            "date_to":"2023-08-11",
            "timezone":"Etc/GMT+3",
            "main_group": ["network","source","placement"],
            "side_group": ["source_placement"],
            "network": ["demosite.ru"]
        }
    },
    "id": 1
}' "http://localhost/?stat.getForSource"


// Ответ
{
    "jsonrpc": "2.0",
    "result": [
        {
            "source": "name",
            "placement": 111111,
            "network": "demosite.ru",
            "bid": 591397,
            "shows": 14716,
            "win_rate": 2.49,
            "clicks": 3,
            "avg_cpm": 30.48
        },
        {
            "source": "name",
            "placement": 111112,
            "network": "demosite.ru",
            "bid": 252685,
            "shows": 14598,
            "win_rate": 5.78,
            "clicks": 50,
            "avg_cpm": 31.88
        }
    ],
    "id": 1
}

Так как в примере указали "main_group": ["network","source","placement"], то в результате есть группировка и по рекламной сети, и по источнику, и по площадке. Если в "main_group" не указывать, например, "placement", то данный столбец будет отсутствовать в ответе несмотря на "side_group": ["source_placement"].

Пример использования метода с выдачей формата креатива

Статистику по форматам креатива можно получить только в разбивке по дням и в GMT+0.

// Запрос
curl -X POST -d '{
    "jsonrpc": "2.0",
    "method":"stat.getForSource",
    "params":{
        "token": "EJa...kDy",
        "filter": {
            "date_from":"2023-01-01",
            "date_to":"2023-07-31",
            "timezone":"Etc/GMT+0",
            "main_group": ["format"],
            "side_group": ["source_format"],
            "source": ["all"],
            "format": "b"
        }
    },
    "id": 1
}' "http://localhost/?stat.getForSource"

// Ответ
{
    "jsonrpc": "2.0",
    "result": [
        {
            "format": "b300x250",
            "bid": "0",
            "shows": 1739412,
            "win_rate": 0,
            "clicks": 1341,
            "avg_cpm": 27.28
        },
        {
            "format": "b300x600",
            "bid": "0",
            "shows": 348468,
            "win_rate": 0,
            "clicks": 267,
            "avg_cpm": 24.52
        },
        {
            "format": "b240x400",
            "bid": "0",
            "shows": 336885,
            "win_rate": 0,
            "clicks": 94,
            "avg_cpm": 23.12
        },
        {
            "format": "b970x250",
            "bid": "0",
            "shows": 162341,
            "win_rate": 0,
            "clicks": 133,
            "avg_cpm": 21.24
        },
        {
            "format": "b160x600",
            "bid": "0",
            "shows": 59196,
            "win_rate": 0,
            "clicks": 38,
            "avg_cpm": 25.41
        },
        {
            "format": "b728x90",
            "bid": "0",
            "shows": 15539,
            "win_rate": 0,
            "clicks": 7,
            "avg_cpm": 25.11
        }
    ],
    "id": 1
}

Возможные ошибки

Код ошибки	Описание	Комментарий
-32768 по -32099	Ошибки JSON-RPC 2.0	Подробнее смотрите в спецификации протокола.
0	Неопределенная внутренняя ошибка.
1	Неопределенная внутренняя ошибка.
300	account not found	Аккаунт не найден
600	source token not found or not available	Токен источника не найден или недоступен
601	invalid timezone	Указано некорректное смещение по времени
602	invalid date_from	Указана некорректная дата начала
603	invalid date_to	Указана некорректная дата окончания

Получение статистики по API

Спецификация

Получение статистики для источника

Параметры запроса

Токен источника

Параметры объекта filter

Параметры ответа

🚧
Обратите внимание

Пример использования метода

Пример использования метода с выдачей формата креатива

Возможные ошибки

Спецификация

Получение статистики для источника

Параметры запроса

Токен источника

Параметры объекта filter

Параметры ответа

🚧Обратите внимание

Пример использования метода

Пример использования метода с выдачей формата креатива

Возможные ошибки

🚧
Обратите внимание