Получение статистики по API
Адрес сервиса статистики: 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 | Подробнее смотрите в [спецификации протокола] (https://www.jsonrpc.org/specification). |
| 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 | Указана некорректная дата окончания |
Updated over 1 year ago