Статистика v2

API-методы статистики v2 позволяют получать различную статистику по рекламным объектам.

Ограничения и фильтры в этих методах задаются с помощью GET-параметров, а не в теле адреса, как это происходит в API v1.

Ограничения запросов

  • Статистика с разбивкой по дням возвращается не более чем за последние 92 дня. 
  • В одном запросе можно получить статистику не более чем по 200 объектам. 

Обработка ошибок

В случае ошибки возвращается ответ вида:

{
    "error":
    {
        "message": "message_text",
        "code": "CODE"
    }
}

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

HTTP-код Code Описание
400 ERR_WRONG_PARAMETER Некорректное значение параметра, либо не указан обязательный параметр
400 ERR_LIMIT_EXCEEDED Превышен лимит запрашиваемых дат или количества объектов
400 ERR_WRONG_DATE Указана некорректная дата
400 ERR_WRONG_BANNERS Запрашиваемые баннеры не существуют или недоступны для данного API-пользователя
400 ERR_WRONG_CAMPAIGNS Запрашиваемые кампании не существуют или недоступны для данного API-пользователя
400 ERR_WRONG_USERS Пользователя не существует или статистика по нему недоступна для данного API-пользователя
403 ERR_ACCESS_DENIED Нет прав для доступа к API-методу
404 ERR_WRONG_RESOURCE API-метода не существует
500 ERR_INTERNAL Внутренняя ошибка сервера

 

Методы

Общая статистика

GET {host}/api/v2/statistics/{banners|campaigns|users}/{day|summary}.json

Ресурс возвращает суммарную за все время открутки или подневную за выбранный период статистику по аккаунтам, кампаниям, баннерам.

Ограничения и фильтры задаются с помощью GET-параметров:

Параметр Формат Значение по умолчанию Описание
date_from YYYY-MM-DD[THH:MM[:SS]]   Начальная дата. Только для day.json.
date_to YYYY-MM-DD[THH:MM[:SS]]   Конечная дата (включительно). Только для day.json.
id список идентификаторов, разделенных запятой   Список идентификаторов баннеров, кампаний или пользователей.
metrics список текстовых идентификаторов, разделенных запятой base Список наборов метрик. Доступные варианты: all, base, events, video, viral, uniques, tps.

Все параметры кроме metrics являются обязательными.

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

    • shows - количество показов;
    • clicks - количество кликов;
    • goals - количество достижений целей (цели Top@Mail.ru для сайтов и установок для мобильных приложений);
    • spent - списания;
    • cpm - среднее списание за 1000 просмотров;
    • cpc - среднее списание за 1 клик;
    • cpa - среднее списание за достижение 1 цели;
    • ctr - процентное отношение количества кликов к количеству просмотров;
    • cr - процентное отношение количества достижений целей к количеству кликов.
    • opening_app - количество открытий рекламируемого приложения соцсетей;
    • opening_post - количество открытий рекламируемого сообщения в ленте соцсетей;
    • moving_into_group - количество переходов на страницу группы из рекламируемого сообщения;
    • clicks_on_external_url - количество кликов по внешней ссылке в рекламируемом сообщении;
    • launching_video - количество запусков видео в рекламируемом сообщении;
    • comments - количество оставленных комментариев в рекламируемом сообщении;
    • joinings - количество присоединений к группе через рекламируемое сообщение;
    • likes - количество лайков рекламируемого сообщения;
    • shares - количество действий "Поделиться" для рекламируемого сообщения;
    • votings - количество действий голосования в рекламируемом сообщении.
    • reach - количество уникальных пользователей, увидевших объявление за указанный период;
    • total - общее количество уникальных пользователей, увидевших объявление за всё время;
    • increment - количество новых уникальных пользователей, увидевших объявление за указанный период;
    • frequency - средняя частота показа объявлений одному уникальному пользователю.
    • started - количество стартов воспроизведения видео;
    • paused - количество пауз воспроизведения видео;
    • resumed_after_pause - количество воспроизведения видео после паузы;
    • fullscreen_on - количество включений полноэкранного режима воспроизведения видео;
    • fullscreen_off - количество выключений полноэкранного режима воспроизведения видео;
    • sound_turned_off - количество выключений звука видео;
    • sound_turned_on - количество включений звука видео;
    • viewed_10_seconds - количество просмотров первых 10 секунд видео;
    • viewed_25_percent - количество просмотров первых 25% длительности видео;
    • viewed_50_percent - количество просмотров первых 50% длительности видео;
    • viewed_75_percent - количество просмотров первых 75% длительности видео;
    • viewed_100_percent - количество просмотров 100% длительности видео;
    • viewed_10_seconds_rate - процент просмотров с достижением первых 10 секунд видео;
    • viewed_25_percent_rate - процент просмотров с достижением первых 25% длительности видео;
    • viewed_50_percent_rate - процент просмотров с достижением первых 50% длительности видео;
    • viewed_75_percent_rate - процент просмотров с достижением первых 75% длительности видео;
    • viewed_100_percent_rate - процент просмотров с достижением 100% длительности видео;
    • depth_of_view - средняя глубина просмотра видео (в процентах);
    • view_10_seconds_cost - средняя стоимость просмотра первых 10 секунд видео;
    • viewed_25_percent_cost - средняя стоимость просмотра первых 25% длительности видео;
    • viewed_50_percent_cost - средняя стоимость просмотра первых 50% длительности видео;
    • viewed_75_percent_cost - средняя стоимость просмотра первых 75% длительности видео;
    • viewed_100_percent_cost - средняя стоимость просмотра 100% длительности видео.
    • impressions - количество показов расшаренного рекламного сообщения в социальных сетях;
    • reach - количество уникальных пользователей, увидивших расшаренное рекламное сообщение за указанный период;
    • total - общее количество уникальных пользователей, увидевших расшаренное рекламное сообщение за всё время;
    • increment - количество новых уникальных пользователей, увидевших расшаренное рекламное сообщение за указанный период;
    • frequency - средняя частота показа расшаренного рекламного сообщения одному уникальному пользователю;
    • opening_app - количество открытий рекламируемого приложения из расшаренного рекламного сообщения;
    • opening_post - количество открытий расшаренного рекламируемого сообщения в ленте соцсетей;
    • moving_into_group - количество переходов на страницу группы из расшаренного рекламируемого сообщения;
    • clicks_on_external_url - количество кликов по внешней ссылке в расшаренном рекламируемом сообщении;
    • launching_video - количество запусков видео в расшаренном рекламируемом сообщении;
    • comments - количество оставленных комментариев в расшаренном рекламируемом сообщении;
    • joinings - количество присоединений к группе через расшаренное рекламируемое сообщение;
    • likes - количество лайков расшаренного рекламируемого сообщения;
    • shares - количество действий "Поделиться" для расшаренного рекламируемого сообщения;
    • votings - количество действий голосования в расшаренном рекламируемом сообщении.
    • slide_N_shows - количество показов слайда N;
    • slide_N_clicks - количество кликов по слайду N;
    • slide_N_ctr - процентное отношение количества кликов к количеству просмотров по слайду N;
    • tps - дополнительные списания за использование сервиса moat;
    • tpd - дополнительные списания за использование сторонних данных (от dmp). 
    • impressions - количество показов;
    • in_view - количество видимых показов;
    • never_focused - количество показов в неактивной вкладке;
    • never_visible - количество показов вне зоны видимости;
    • never_50_perc_visible - количество показов с зоной видимости объявления менее 50%;
    • never_1_sec_visible - количество показов с длительностью видимости менее 1 секунды;
    • human_impressions - количество верифицированных показов;
    • impressions_analyzed - количество анализируемых показов;
    • in_view_percent - процент видимых показов;
    • human_and_viewable_perc - процент верифицированных показов;
    • never_focused_percent - процент показов в неактивной вкладке;
    • never_visible_percent - процент показов вне зоны видимости;
    • never_50_perc_visible_percent - процент оказов с зоной видимости объявления менее 50%;
    • never_1_sec_visible_percent - процент показов с длительностью видимости менее 1 секунды;
    • in_view_diff_percent - разница в количестве видимых показов;
    • active_in_view_time - среднее время нахождения объявления в зоне видимости;
    • attention_quality - уровень вовленчения;

Структура ответа:

  • items - массив статистики за запрашиваемый период
    • id - идентификатор объекта
    • rows - массив статистики за конкретную дату
      • date - дата
      • metrics - массивы запрошенных метрик
    • total - суммарная статистика по объекту за запрашиваемый период
  • total - суммарная статистика по всем объектам за запрашиваемый период

Пример запроса:

{
    "items": [{
        "id": 857683,
        "rows": [{
            "date": "2017-09-20",
            "base": {
                "shows": 123757,
                "clicks": 672,
                "goals": 9,
                "spent": "155.8",
                "cpm": "1.25",
                ...
            },
            "events": {
                "opening_app": 0,
                "opening_post": 0,
                "moving_into_group": 0,
                "clicks_on_external_url": 0,
                ...
            },
            "uniques": {...},
            "video": {...},
            "viral": {...},
            "tps": {...}
        },
        {
            "date": "2017-09-21",
            "base": {...},
            "events": {...},
            "uniques": {...},
            "video": {...},
            "viral": {...},
            "tps": {...}
        }],
        "total": {
            "base": {...},
            "events": {...},
            "uniques": {...},
            "video": {...},
            "viral": {...},
            "tps": {...}
        }
    }],
    "total": {
        "base": {...},
        "events": {...},
        "video": {...},
        "viral": {...},
        "tps": {...}
    }
}

Статистика по целям

GET {host}/api/v2/statistics/goals/{banners|campaigns|users}/day.json

Ресурс возвращает статистику по конверсиям Top@Mail.ru и установкам мобильных приложений по кампаниям и баннерам в разрешении 1 день. 

Ограничения и фильтры задаются с помощью GET-параметров:

Параметр Формат Описание
date_from YYYY-MM-DD[THH:MM[:SS]] Начальная дата 
date_to YYYY-MM-DD[THH:MM[:SS]] Конечная дата (включительно)
id список идентификаторов, разделенных запятой Список идентификаторов баннеров или кампаний

Все параметры являются обязательными.

Структура ответа:

  • items - массив статистики за запрашиваемый период
    • id - идентификатор объекта
    • rows - массив статистики за конкретную дату
      • date - дата
      • goals - массивы данных статистики по целям
        • source - тип события: topmail - конверсии счётчика, mobile - мобильные конверсии
        • goal - название цели счётчика или тип для мобильных (сейчас только install)
        • counter_id - идентификатор счётчика
        • count - количество конверсий
        • cr - коэффициент конверсии
        • cpa - стоимость одной конверсии
    • total - суммарная статистика по объекту за весь запрашиваемый период
  • total - суммарная статистика по всем объектам за весь запрашиваемый период

Пример запроса:

{
    "items": [
        {
            "id": 1247539,
            "rows": [
                {
                    "date": "2017-09-20",
                    "goals": [
                        {
                            "source": "topmail",
                            "goal": "my-goal",
                            "counter_id": 1335,
                            "count": 150,
                            "cr": 0.83,
                            "cpa": "39.15"
                        },
                        ...
                    ]
                },
                {
                    "date": "2017-09-21",
                    "goals": [
                        ...
                    ]
                }
            ],
            "total": {
                "goals": [
                    ...
                ]
            }
        },
        {
            "id": 1268343,
            "rows": [
                {
                    "date": "2017-09-20",
                    "goals": [
                        {
                            "source": "mobile",
                            "goal": "install",
                            "counter_id": 0,
                            "count": 112,
                            "cr": 0.15,
                            "cpa": "53.53"
                        },
                        ...
                    ]
                },
                {
                    "date": "2017-09-21",
                    "goals": [
                        ...
                    ]
                }
            ],
            "total": {
                "goals": [
                    ...
                ]
            }
        }
    ],
    "total": {
        "goals": [
            {
                "source": "topmail",
                "goal": "my-goal",
                "counter_id": 1335,
                "count": 195,
                "cr": 0.79,
                "cpa": "43.13"
            },
            {
                "source": "mobile",
                "goal": "install",
                "counter_id": 0,
                "count": 198,
                "cr": 0.19,
                "cpa": "48.95"
            }
        ]
    }
}

Статистика по событиям внутри приложения

GET {host}/api/v2/statistics/inapp/{banners|campaigns|users}/day.json

Ресурс возвращает статистику по аттрибуцированным с рекламными показами myTarget событиями мобильных приложений по кампаниям и баннерам в разрешении 1 день. 

Ограничения и фильтры задаются с помощью GET-параметров:

Параметр Формат Описание
date_from YYYY-MM-DD[THH:MM[:SS]] Начальная дата 
date_to YYYY-MM-DD[THH:MM[:SS]] Конечная дата (включительно)
id список идентификаторов, разделенных запятой Список идентификаторов пользователей, баннеров или кампаний

Все параметры являются обязательными.

Структура ответа:

  • items - массив статистики за запрашиваемый период
    • id - идентификатор объекта
    • rows - массив статистики за конкретную дату
      • date - дата
      • inapps - массивы данных статистики по событиям
        • tracker - идентификатор трекера мобильных приложений
        • app - идентификатор мобильного приложения
        • event - название события
        • count - количество конверсий
        • cr - коэффициент конверсии
        • cpa - стоимость одной конверсии
    • total - суммарная статистика по объекту за весь запрашиваемый период
  • total - суммарная статистика по всем объектам за весь запрашиваемый период

Пример запроса:

{
    items: [{
        id: 9720236,
        rows: [{
            date: "2018-05-10",
            inapps: [{
                tracker: 1,
                app: 4764245,
                event: "app_opened",
                count: 9160,
                cr: 62.745098039215684,
                cpa: "22.16",
                
            },
            {
                tracker: 2,
                app: 4764245,
                event: "content_view",
                count: 1990,
                cr: 130.0653594771242,
                cpa: "10.84",
            }
            ]
            
        },
        {
            date: "2018-05-11",
            inapps: [
                        ...
                    ],
            
        }
        ],
        total: {
            inapps: [
                ...
            ]
        }        
    }],
    total: {
        inapps: [
            ...
        ]
    }
}

Оффлайн конверсии

Ресурс возвращает статистику по аттрибуцированным с рекламными показами myTarget событиями из списков оффлайн конверсий по кампаниям в разрешении 1 день.

GET api/v2/statistics/offline_conversions/campaigns/day.json

Параметр Формат Описание
date_from YYYY-MM-DD[THH:MM[:SS]] Начальная дата 
date_to YYYY-MM-DD[THH:MM[:SS]] Конечная дата (включительно)
id список идентификаторов, разделенных запятой Список идентификаторов кампаний


Фильтры даты учитывают дату события к которой атрибутирована конверсия

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

"rate" conversion rate = пользователи, которые сконвертировались и видели РК / все пользователи, видевшие РК
в процентах
"cost" фактическая стоимость привлечения = стоимость РК / пользователи, которые сконвертировались и видели рекламу 
"offline" Количество конверсий 

Быстрая статистика

GET {host}/api/v2/statistics/{faststat|uniquestat}/{banners|campaigns|users}.json

Ресурс возвращает базовую статистику по рекламным объектам в режиме реального времени, без учёта фильтрации некорректного траффика. Значения в итоговой статистике могут значительно отличаться. 

Запрос uniquestat возвращает в том числе инормацию по уникальному охвату и его приросту, но при этом работает дольше чем faststat. Не используйте uniquestat, если нет необходимости в информации по уникальному охвату. 

Ограничения и фильтры задаются с помощью GET-параметров:

Параметр Формат Описание
id список идентификаторов, разделенных запятой Список идентификаторов баннеров или кампаний

Все параметры являются обязательными.

Структура ответа:

  • campaigns|banners|advertisers - массив статистики по запрашиваемому объекту
    • campaign_id|banner_id|user_id - массив статистики по конкретному объекту
      • timestamp - время последнего учтенного события по данному объекту
      • daily||hourly|minutely|total - подневный|почасовой|поминутный|суммарный массивы данных статистики по объекту. Для подневного массива в подмассивах возвращаются отдельные значения за последние 7 дней, для почасового - за последние 24 часа, для минутного - 60 минут. Последний элемент каждого массива со статистикой соответствует временному интервалу с указанным таймстэмпом, остальные элементы - история за предыдущие временные интервалы.
        • clicks - количество кликов;
        • shows - количество показов;
        • goals - количество достижений целей;
        • uniques (значения только для uniquestat) - количество уникальных пользователей;
        • deltas (значения только для uniquestat) - прирост уникальных пользователей;
        • customs - количество специальных событий.
  • last_seen_msg_time - время (в разных форматах) обработки последнего массива статистики. 

Пример запроса:

{
    last_seen_msg_time: {
        timestamp: 1550072300,
        string: "2019-02-13 18:38:20",
        ago: 5267        
    },
    banners: {},
    campaigns: {
        12121212: {
            timestamp: 1550071760,
            total: {
                clicks: [10311],
                shows: [72332],
                goals: [0],
                uniques: [57329],
                customs: {
                    1000: {
                        events: [7617],
                        uniques: [7322]
                        
                    },
                    1001: {
                        events: [2637],
                        uniques: [2637]                        
                    }                    
                }                
            },
            daily: {
                clicks: [140,
                92,
                176,
                275,
                237,
                151,
                192
                ],
                shows: [1253,
                ...,
                2331
                ],
                goals: [...],
                uniques: [...],
                deltas: [...],
                customs: {...}                
            },
            hourly: {...},
            minutely: {...}            
        },
        21212121: {
            timestamp: 1550071333,
            total: {...},
            dayly: {...},
            hourly: {...},
            minutely: {...}
        }
    },
    advertisers: {}    
}