API глобальной статистики
В этом разделе описаны параметры запроса API глобальной статистики и данные о результатах.
Примечание: Маршруты API статистики были переименованы:
- /statistics/advertiser/... -> /statistics/a/...
- /statistics/publisher/... -> /statistics/p/...
Примечание: API глобальной статистики показывает только пропущенные RTB-запросы для даты, сайтов, зон, стран, регионов и суб-идентификаторов.
Параметр | Описание | Примечания | Тип |
---|---|---|---|
считать | Возвращает только общее количество результатов. | целое число | опция |
подробно | По возможности узнайте больше деталей. | целое число | опция |
часовой пояс | Настройка часового пояса для фильтра 'hour' и 'group_by' | строка | опция |
итоги | Указывает, добавлять ли итоги в ответ или нет. | целое число | опция |
фильтр | Фильтры для ограничения возвращаемых значений статистического запроса | объект | опция |
группировать_по | Список значений группировки по, которые должны быть применены к данным. Допускается не более четырех. | массив | обязательный |
порядок_по | Упорядочивание результатов по определенному полю (полям). Допускается не более двух. | массив | опция |
проекция | Отдельные подструктуры, которые пользователь хочет получить в ответ. | массив | опция |
ограничение | Количество записей, возвращаемых в этом ответе. | целое число | опция |
смещение | Позиция, из которой будут получены записи. | целое число | опция |
Количество параметров
Недвижимость | считать |
Тип | опция |
Переменный тип | целое число |
Значение по умолчанию | 0 |
Доступные значения | [0, 1] |
Описание | Возвращает только общее количество результатов. |
Пример:
{
"count": 1
}
Детальный параметр
Недвижимость | подробно |
Тип | опция |
Переменный тип | целое число |
Значение по умолчанию | 0 |
Доступные значения | [0, 1] |
Описание | Возвращать ли подробную информацию или нет. |
Пример:
{
"detailed": 1
}
Параметр часовой пояс
Настройка часового пояса для фильтра hour
и group_by
.
Недвижимость | часовой пояс |
Тип | опция |
Переменный тип | строка |
Значение по умолчанию | Америка/Новый_Йорк |
Доступные значения | Установите поле часового пояса в / коллекции / часовые пояса |
Описание | ПРИМЕЧАНИЕ: Часовые пояса имеют значение только при запросе на основе почасовых данных, для нечасовых данных это не имеет значения. |
Пример:
{
"timezone": "Europe/Dublin"
}
Итоговые значения параметров
Недвижимость | итоги |
Тип | опция |
Переменный тип | целое число |
Значение по умолчанию | 0 |
Доступные значения | [0,1] |
Описание | Указывает, добавлять ли итоги в ответ или нет. |
Пример:
{
"totals": 1
}
Фильтр параметров
Недвижимость | фильтр |
Тип | опция |
Переменный тип | объект |
Доступная опция для рекламодателей | ["adblock", "advertiser_ad_type_id", "browser_id", "carrier_id", "category_id", "country_iso", "date_from", "date_to", "device_id", "device_type_id", hour", "language_id", "operating_system_id", "region_id", "site_hostname", "site_id", "size", "sub", "zone_id", "campaign_id", "exclude_deleted", "offer_id", "offer_landing_page_id", "variation_id"] |
Доступная опция для издателей | ["adblock", "browser_id", "carrier_id", "category_id", "country_iso", "date_from", "date_to", "device_id", "device_type_id", "hour", "language_id", "operating_system_id", "region_id", "site_hostname", "site_id", "zone_id", "publisher_ad_type_id", "size", "sub"] |
Описание | Фильтр по определенным параметрам. |
Фильтр: страна_изо
Недвижимость | страна_изо |
Тип | опция |
Переменный тип | строка |
Значение по умолчанию | - |
Доступные значения | См. свойство /collections/countries конечной точки iso3 |
Описание | Список кодов ISO 3 |
Пример:
{
"filter": {
"country_iso": ["ESP", "IRL"]
}
}
Фильтр дата_от
, дата_до
Параметры date_from
и date_to
управляют окном, за которое вы хотите получить информацию о статистике.
- date_from: Дата из диапазона для статистики, (По умолчанию начало месяца),
- date_to: Диапазон дат для статистики, (По умолчанию сегодня)
Недвижимость | датаот, датадо |
Тип | опция |
Переменный тип | строка |
Значение по умолчанию | Даты по умолчанию соответствуют текущему месяцу. |
Доступные значения | ГГГГ-мм-дд |
Описание | Диапазон дат от/до для статистики. Формат ГГГГ-мм-дд |
Пример:
{
"filter": {
"date_from": "2019-02-25",
"date_to": "2019-02-28"
}
}
Часовые пояса имеют значение только при запросе на основе почасовых данных, для нечасовых данных это не имеет значения.
Фильтр: advertiser_ad_type_id, campaign_id, browser_id, carrier_id, category_id, device_id, device_type_id, language_id, offer_id, offer_landing_page_id, operating_system_id, hour, region_id, site_id, sub, variation_id, zone_id, publisher_ad_type_id
Недвижимость | advertiser_ad_type_id, campaign_id, browser_id, carrier_id, category_id, device_id, device_type_id, language_id, offer_id, offer_landing_page_id, operating_system_id, hour, region_id, site_id, sub, variation_id, zone_id, advertiser_ad_type_id, publisher_ad_type_id |
Тип | опция |
Переменный тип | массив |
Тип предметов | целое число |
Значение по умолчанию | - |
Доступные значения | Относительные свойства ИЛИ коллекции |
Описание | Список идентификаторов сущностей |
Пример:
{
"filter": {
"campaign_id": [123, 456],
"browser_id": [789]
}
}
Фильтр: exclude_deleted
Недвижимость | исключить_удаленные |
Тип | опция |
Переменный тип | целое число |
Значение по умолчанию | 0 |
Доступные значения | [0, 1] |
Описание | Нужно ли исключать удаленные кампании или нет. |
Пример:
{
"filter": {
"exclude_deleted": 1
}
}
Фильтр: adblock
Недвижимость | adblock |
Тип | опция |
Переменный тип | строка |
Значение по умолчанию | "все" |
Доступные значения | "adblock", "all", "standard" |
Описание | Включать или не включать зоны adblock. |
Пример:
{
"filter": {
"adblock": "standard"
}
}
Фильтр: site_hostname
Недвижимость | имя_хоста сайта |
Тип | опция |
Переменный тип | строка |
Значение по умолчанию | - |
Доступные значения | Допустимыми символами для имен хостов являются буквы от a до z, цифры от 0 до 9, дефис и точка. |
Описание | Фильтр по имени хоста сайта. |
Пример:
{
"filter": {
"site_hostname": ["www.example.com", "www.example-site.org"]
}
}
Фильтр: размер
Недвижимость | размер |
Тип | опция |
Переменный тип | строка |
Значение по умолчанию | - |
Доступные значения | Допустимыми символами для размера являются цифры от 0 до 9 и символ x. Пример 300x100 |
Описание | Фильтр по размеру |
Пример:
{
"filter": {
"size": ["300x100"]
}
}
Параметр group_by
Недвижимость | группировать_по |
Тип | обязательный |
Переменный тип | массив |
Тип предметов | строка |
Значение по умолчанию | - |
Доступные значения для рекламодателей | ["adblock", "advertiser_ad_type_id", "browser_id", "campaign_id", "carrier_id", "category_id", "country_iso", "date", "hour", "device_id", "device_type_id", "language_id", "operating_system_id", "region_id", "site_id", "sub", "zone_id", "week", "month", "quarter", "year", "offer_id", "offer_landing_page_id", "site_hostname", "size", "variation_id"] |
Доступные значения для издателей | ["adblock", "browser_id", "carrier_id", "category_id", "country_iso", "date", "device_id", "device_type_id", "hour", "language_id", "operating_system_id", "publisher_ad_type_id" "region_id", "site_id", "size", "sub", "zone_id", "week", "month", "quarter", "year"] |
Описание | Список подзапросов для включения дополнительных данных в ответ. |
Пример:
{
"group_by": [
"browser",
"date"
]
}
Параметр order_by
Недвижимость | порядок_по |
---|---|
Тип | опция |
Переменный тип | массив |
Тип предметов | строка |
Значение по умолчанию | - |
Доступные значения полей метрик | ["cpc", "cpc", "cpm", "cpv", "ctr", "clicks", "impressions", "video_impressions", "video_views", "vtr", "rtb_win_ratio", "rtb_avg_total_time", "rtb_skipped", "rtb_bid_response_ratio", "rtb_avg_cpm", "rtb_timeouts_ratio", "rt_errors_ratio", "rtb_no_bid_ratio", "rtb_skipped_ratio"] |
Доступные значения полей зависят от `group_by' для рекламодателей | ["adblock", "browser_id", "campaign_id", "carrier_id", "category_id", "country_iso", "device_id", "date", "device_type_id", "hour", "ecpa1", "g1", "language_id", "month", "offer_id", "offer_landing_page_id", "operating_system_id", "quarter", "region_id", "site_hostname", "site_id", "sub", "variation_id", "week", "year" , "zone_id"] |
Доступные значения полей зависят от `group_by' для издателей | ["adblock", "browser_id", "carrier_id", "category_id", "country_iso", "device_id", "date", "device_type_id" , "hour", "language_id", "month", "operating_system_id", "quarter", "region_id", "site_id", "sub", "week", "year", "zone_id"] |
Доступные значения заказа | ["asc", "desc"] |
Описание | Список доступных вариантов заказа |
Подсказки:
- Поля метрик постоянно доступны для использования в качестве полей порядка по.
- Чтобы упорядочить по определенному значению (например, по "browser_id"), нужно включить его в параметр "group_by".
Значения "g1", "ecpa1" доступны только в том случае, если у пользователя настроено отслеживание конверсии (цели). Все цели ассоциируются с порядковым номером (g1, g2, ...gx). Значения eCPA, соответственно, ecpa1, ecpa2, ...ecpax.
Пример:
{
"order_by": [
{
"field": "impressions",
"order": "desc"
}
]
}
Например, чтобы упорядочить результаты кампании в хронологическом порядке, "дата" должна быть включена как в "group_by", так и в "order_by":
{
"group_by": [
"campaign_id",
"date"
],
"order_by":[
{
"field": "date",
"order": "asc"
}
]
}
Проекция параметров
Параметр projection отражает то, что будет возвращено в результирующей полезной нагрузке. Если параметр не указан, будут возвращены все вложенные структуры.
Недвижимость | проекция |
---|---|
Тип | опция |
Переменный тип | объект |
Тип предметов | массив |
Значение по умолчанию | все варианты, см. ниже |
Доступные значения полей для рекламодателей | ["base", "rtb", "video", "goals*"] |
Доступные значения полей для издателей | ["base", "rtb", "video", "wpn"] |
*Некоторые поля "цели", такие как "прибыль" и "доход", рассчитываются на основе стоимости кампании, поэтому вы должны также использовать поле "база", если хотите получить правильные метрики "целей".
Примеры:
Чтобы получить все возможные показатели в качестве рекламодателя, используйте:
{
"projection": {
"base": ["*"],
"video": ["*"],
"goals": ["*"],
"rtb": ["*"]
}
}
Чтобы получить все возможные метрики как издатель, используйте:
{
"projection": {
"base": ["*"],
"video": ["*"],
"wpn": ["*"],
"rtb": ["*"]
}
}
Вы также можете указать метрики в каждом поле проекции:
{
"projection": {
"base": ["impressions","clicks","cost","revenue","cpc","cpm","ctr"],
"video": ["impressions","views","cpv","vtr"],
"rtb": ["total_time","queries","value","success","no_bid","skipped","errors","timeouts","wins","win_ratio"],
//only for Publishers
"wpn": ["subscriptions","unsubscriptions","sent"]
}
}
Единственное поле, которое не позволяет проецировать конкретные метрики, - это "голы"
Ограничение параметров
Количество записей, возвращаемых в этом ответе.
Недвижимость | ограничение |
Тип | опция |
Переменный тип | целое число |
Значение по умолчанию | 50 |
Пример:
{
"limit": 25
}
Смещение параметров
Позиция, из которой будут получены записи.
Недвижимость | смещение |
Тип | опция |
Переменный тип | целое число |
Значение по умолчанию | 0 |
Пример
{
"offset": 150
}
Пример 1
Статистика кампаний рекламодателей с фильтрацией.
Запрос:
{
"detailed": true,
"totals": 1,
"filter": {
"date_from": "2019-03-10",
"date_to": "2019-03-11",
"country_iso": ["USA"]
},
"group_by": ["campaign_id"],
"order_by": [
{
"field": "campaign_id",
"order": "desc"
}
]
"projection": {
"base": ["*"],
"video": ["*"],
"rtb": ["*"]
},
"limit": 2,
"offset": 0
}
Ответ:
{
"request_metadata": {
"count": 4,
"limit": 2,
"offset": 0
},
"result": [
{
"clicks": 0,
"cost": 1.3302,
"cpc": 0,
"cpm": 0.45586017820425,
"ctr": 0,
"group_by": {
"campaign_id": {
"active": "1",
"campaign_ad_type_name": "Popunders",
"id": "1234567",
"name": "Ron Mainstream Campaign "
}
},
"impressions": 2918,
"rtb": {
"avg_cpm": 0.15582967823432,
"avg_total_time": 89.522714492492,
"errors": 112,
"errors_ratio": 0.011368411650186,
"no_bid": 870594,
"no_bid_ratio": 88.368490823053,
"queries": 985186,
"response_ratio": 11.57101298638,
"skipped": 0,
"skipped_ratio": 0,
"success": 984590,
"timeouts": 484,
"timeouts_ratio": 0.049127778916875,
"total_time": 88196525,
"value": 1776.396,
"win_ratio": 0.29842080581738,
"wins": 2940
},
"video": {
"cpv": 0,
"impressions": 0,
"views": 0,
"vtr": 0
}
},
{
"clicks": 0,
"cost": 18.1621655,
"cpc": 0,
"cpm": 1.8273634671496,
"ctr": 0,
"group_by": {
"campaign_id": {
"active": "1",
"campaign_ad_type_name": "Popunders",
"id": "7654321",
"name": "Ron Mainstream Campaign Test"
}
},
"impressions": 9939,
"rtb": {
"avg_cpm": 1.4753505300475,
"avg_total_time": 88.777190144965,
"errors": 46,
"errors_ratio": 0.0014192869995779,
"no_bid": 3209674,
"no_bid_ratio": 99.031490893114,
"queries": 3241064,
"response_ratio": 0.8964340105595,
"skipped": 0,
"skipped_ratio": 0,
"success": 3238728,
"timeouts": 2290,
"timeouts_ratio": 0.070655809326814,
"total_time": 287732555,
"value": 4286.48343,
"win_ratio": 0.30665855410445,
"wins": 9939
},
"video": {
"cpv": 0,
"impressions": 0,
"views": 0,
"vtr": 0
}
}
],
"result_total": {
"clicks": 0,
"cost": 74.0473595,
"cpc": 0,
"cpm": 2.0864288391096,
"ctr": 0,
"impressions": 35490,
"rtb": {
"avg_cpm": 0.23441613972984,
"avg_total_time": 87.995789332859,
"errors": 539,
"errors_ratio": 0.0049868154705264,
"no_bid": 9771471,
"no_bid_ratio": 90.405422546568,
"queries": 10808501,
"response_ratio": 9.5135301370653,
"skipped": 0,
"skipped_ratio": 0,
"success": 10799741,
"timeouts": 8221,
"timeouts_ratio": 0.07606050089647,
"total_time": 951102577,
"win_ratio": 0.32861171035651,
"wins": 35518
},
"video": {
"cpv": 0,
"impressions": 0,
"views": 0,
"vtr": 0
}
}
}
Пример 2
Статистика рекламодателей по датам за текущий месяц, упорядоченная по показам.
Запрос:
{
"group_by": ["date"],
"order_by": [
{
"field": "impressions",
"order": "desc"
}
]
"projection": {
"base": ["*"],
"video": ["*"],
"rtb": ["*"]
}
}
Ответ:
{
"request_metadata": {
"count": 3,
"limit": 50,
"offset": 0
},
"result": [
{
"clicks": 0,
"cost": 624.2439917,
"cpc": 0,
"cpm": 1.0978015474007,
"ctr": 0,
"group_by": {
"date": {
"date": "2019-03-02"
}
},
"impressions": 568631,
"rtb": {
"avg_cpm": 0.31273156270632,
"avg_total_time": 114.34705591799,
"errors": 4143,
"errors_ratio": 0.0076578188576312,
"no_bid": 48085697,
"no_bid_ratio": 88.8804144989,
"queries": 54101567,
"response_ratio": 10.971772776933,
"skipped": 0,
"skipped_ratio": 0,
"success": 54021598,
"timeouts": 75826,
"timeouts_ratio": 0.14015490530986,
"total_time": 6186354907,
"value": 185634.35958,
"win_ratio": 1.1633248996281,
"wins": 629377
},
"video": {
"cpv": 0,
"impressions": 0,
"views": 0,
"vtr": 0
}
},
{
"clicks": 0,
"cost": 622.1688691,
"cpc": 0,
"cpm": 1.1800128762878,
"ctr": 0,
"group_by": {
"date": {
"date": "2019-03-01"
}
},
"impressions": 527256,
"rtb": {
"avg_cpm": 0.27775587567531,
"avg_total_time": 118.91585420372,
"errors": 2954,
"errors_ratio": 0.0078196779097434,
"no_bid": 32641750,
"no_bid_ratio": 86.407573260111,
"queries": 37776492,
"response_ratio": 13.412992397494,
"skipped": 0,
"skipped_ratio": 0,
"success": 37708708,
"timeouts": 64830,
"timeouts_ratio": 0.17161466448499,
"total_time": 4492223815,
"value": 140737.73563,
"win_ratio": 1.4077723257099,
"wins": 531807
},
"video": {
"cpv": 0,
"impressions": 0,
"views": 0,
"vtr": 0
}
},
{
"clicks": 0,
"cost": 441.843491,
"cpc": 0,
"cpm": 0.96186339096399,
"ctr": 0,
"group_by": {
"date": {
"date": "2019-03-03"
}
},
"impressions": 459362,
"rtb": {
"avg_cpm": 0.26462497173837,
"avg_total_time": 116.9210100884,
"errors": 2183,
"errors_ratio": 0.0059889808787451,
"no_bid": 32174177,
"no_bid_ratio": 88.268681100486,
"queries": 36450275,
"response_ratio": 11.500815837466,
"skipped": 0,
"skipped_ratio": 0,
"success": 36366256,
"timeouts": 81836,
"timeouts_ratio": 0.22451408116948,
"total_time": 4261802971,
"value": 110932.87869,
"win_ratio": 1.2852029237091,
"wins": 468460
},
"video": {
"cpv": 0,
"impressions": 0,
"views": 0,
"vtr": 0
}
}
]
}
Пример 3
Статистика издателя по дате и region_id, упорядоченная по количеству показов.
Запрос:
{
"detailed": true,
"filter": {
"date_from": "2019-03-10",
"date_to": "2019-03-11",
"country_iso": ["USA"]
},
"group_by": ["date", "region_id"],
"order_by": [
{
"field": "impressions",
"order": "desc"
}
],
"projection": {
"base": ["*"],
"video": ["*"],
"wpn": ["*"],
"rtb": ["*"]
}
"limit": 30,
"offset": 0
}
Ответ:
{
"request_metadata": {
"count": 2,
"limit": 30,
"offset": 0
},
"result": [
{
"clicks": 3087,
"cpc": 0.033842716164561,
"cpm": 0.069188574849649,
"ctr": 0.20444155402072,
"group_by": {
"date": {
"date": "2019-03-11"
},
"region_id": {
"country_iso": "USA",
"country_long_name": "United States of America",
"country_short_name": "United States",
"id": 5332921,
"name": "California"
}
},
"impressions": 1494954,
"revenue": 104.4724648,
"rtb": {
"avg_cpm": 0,
"avg_total_time": 0,
"bid_response_ratio": 0,
"errors": 0,
"errors_ratio": 0,
"no_bid": 0,
"no_bid_ratio": 0,
"queries": 0,
"skipped": 0,
"skipped_ratio": 0,
"success": 0,
"timeouts": 0,
"timeouts_ratio": 0,
"total_time": 0,
"value": 0,
"win_ratio": 0,
"wins": 0
},
"video": {
"cpv": 0.038451404048583,
"impressions": 15013,
"views": 2717,
"vtr": 18.097648704456
},
"wpn": {
"subscriptions": 0,
"unsubscriptions": 0
}
},
{
"clicks": 3071,
"cpc": 0.03151133555845,
"cpm": 0.066658890819906,
"ctr": 0.21153940205505,
"group_by": {
"date": {
"date": "2019-03-10"
},
"region_id": {
"country_iso": "USA",
"country_long_name": "United States of America",
"country_short_name": "United States",
"id": 5332921,
"name": "California"
}
},
"impressions": 1436818,
"revenue": 96.7713115,
"rtb": {
"avg_cpm": 0,
"avg_total_time": 0,
"bid_response_ratio": 0,
"errors": 0,
"errors_ratio": 0,
"no_bid": 0,
"no_bid_ratio": 0,
"queries": 0,
"skipped": 0,
"skipped_ratio": 0,
"success": 0,
"timeouts": 0,
"timeouts_ratio": 0,
"total_time": 0,
"value": 0,
"win_ratio": 0,
"wins": 0
},
"video": {
"cpv": 0.036216808196108,
"impressions": 14921,
"views": 2672,
"vtr": 17.907646940554
},
"wpn": {
"subscriptions": 0,
"unsubscriptions": 0
}
}
]
}
Пример 4
Статистика издателя по site_id с прогнозом.
Запрос:
{
"detailed": true,
"projection": {
"base": ["*"],
"video": ["*"],
"wpn": ["*"],
"rtb": ["*"]
},
"filter": {
"date_from": "2019-03-10",
"date_to": "2019-03-11",
"country_iso": ["USA"]
},
"group_by": ["site_id"],
"order_by": [
{
"field": "impressions",
"order": "desc"
}
],
"limit": 30,
"offset": 0
}
Ответ
{
"request_metadata": {
"count": 2,
"limit": 30,
"offset": 0
},
"result": [
{
"clicks": 14320,
"cpc": 0.028298959692737,
"cpm": 0.057945765404939,
"ctr": 0.20476288186597,
"group_by": {
"site_id": {
"id": "11223344",
"name": "nice-example.com"
}
},
"impressions": 6916414,
"revenue": 405.2411028,
"rtb": {
"avg_cpm": 0,
"avg_total_time": 0,
"bid_response_ratio": 0,
"errors": 0,
"errors_ratio": 0,
"no_bid": 0,
"no_bid_ratio": 0,
"queries": 0,
"skipped": 0,
"skipped_ratio": 0,
"success": 0,
"timeouts": 0,
"timeouts_ratio": 0,
"total_time": 0,
"value": 0,
"win_ratio": 0,
"wins": 0
},
"video": {
"cpv": 0.031519102652252,
"impressions": 77041,
"views": 12857,
"vtr": 16.688516504199
},
"wpn": {
"subscriptions": 0,
"unsubscriptions": 0
}
},
{
"clicks": 14148,
"cpc": 0.028769196296296,
"cpm": 0.063791981699323,
"ctr": 0.22173710048179,
"impressions": 6314909,
"revenue": 407.0265892,
"rtb": {
"avg_cpm": 0,
"avg_total_time": 0,
"bid_response_ratio": 0,
"errors": 0,
"errors_ratio": 0,
"no_bid": 0,
"no_bid_ratio": 0,
"queries": 0,
"skipped": 0,
"skipped_ratio": 0,
"success": 0,
"timeouts": 0,
"timeouts_ratio": 0,
"total_time": 0,
"value": 0,
"win_ratio": 0,
"wins": 0
},
"video": {
"cpv": 0.036406671663685,
"impressions": 65620,
"views": 11180,
"vtr": 17.037488570558
},
"wpn": {
"subscriptions": 0,
"unsubscriptions": 0
}
}
]
}