API
Contents
- 1 Статистика по кампании
- 2 Статистика по всем материалам кампании
- 3 Статистика по материалу
- 4 Создание рекламной кампании
- 5 Редактирование рекламных кампаний
- 6 Список кампаний рекламного кабинета
- 7 Архивирование клиентов рекламного агенства
- 8 Возвращение кодов для СРА кампаний
- 9 Возврат списка категорий по заданому фильтру
- 10 Возврат списка форматов объявлений
- 11 Возврат списка платформ
- 12 Возврат списка браузеров
- 13 Возврат списка уведомлений о конверсиях для СРА
- 14 Возврат списка возврастов
- 15 Создание клиентов рекламного агенства
- 16 Редактирование клиентов рекламного агенства
- 17 Получение списка клиентов рекламного агенства
- 18 Архивирование клиентов рекламного агенства
- 19 Подвязывание клиента к рекламному агенству
- 20 Открепление клиента от рекламного агенства
- 21 Пополнение счета клиента
- 22 Создание рекламных объявлений
- 23 Обновление данных рекламных объявлений
- 24 Архивирование данных рекламных объявлений
- 25 Получение списка рекламных объявлений
Статистика по кампании
Для получения статистики по кампании используется метод ads.analytic.campaign.get
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
campaign_id | id кампании | int (числовое значение), обязательный параметр |
region_id | id региона | int (числовое значение), необязательный параметр |
period | Способ группировки данных по датам:
day — статистика по дням; month - статистика по месяцам Временные ограничения задаются параметрами date_from и date_to |
обязательный параметр, строка |
date_from | Начальная дата выводимой статистики. Используется разный формат дат для разного значения параметра period:
day: YYYY-MM-DD, пример: 2011-09-27; month: YYYY-MM, пример: 2011-09 |
обязательный параметр, строка |
date_to | Конечная дата выводимой статистики. Используется разный формат дат для разного значения параметра period:
day: YYYY-MM-DD, пример: 2011-09-27; month: YYYY-MM, пример: 2011-09 |
обязательный параметр, строка |
Результат:
Возвращает объект с данными
{ response: { count: %total items% items: { shows clicks ctr cpm money } } }
Статистика по всем материалам кампании
Для получения статистики по всем материалам кампании используется метод ads.analytic.materials.get
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
campaign_id | id кампании | int (числовое значение), обязательный параметр |
period | Способ группировки данных по датам:
1. day — статистика по дням; 2. month — статистика по месяцам; Временные ограничения задаются параметрами date_from и date_to |
обязательный параметр, строка |
date_from | Начальная дата выводимой статистики. Используется разный формат дат для разного значения параметра period:
1. day: YYYY-MM-DD, пример: 2011-09-27 2. month: YYYY-MM, пример: 2011-09 |
обязательный параметр, строка |
date_to | Конечная дата выводимой статистики. Используется разный формат дат для разного значения параметра period:
1. day: YYYY-MM-DD, пример: 2011-09-27 2. month: YYYY-MM, пример: 2011-09 |
обязательный параметр, строка |
Результат:
Возвращает объект с данными
{ response: { count: %total items% items: { teaser_id date shows clicks ctr cpm money } } }
Статистика по материалу
Для получения статистики по материалу используется метод ads.analytic.material.get
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
material_id | id материала | int (числовое значение), обязательный параметр |
period | Способ группировки данных по датам:
1. day — статистика по дням; 2. month — статистика по месяцам; Временные ограничения задаются параметрами date_from и date_to |
обязательный параметр, строка |
date_from | Начальная дата выводимой статистики. Используется разный формат дат для разного значения параметра period:
1. day: YYYY-MM-DD, пример: 2011-09-27 2. month: YYYY-MM, пример: 2011-09 |
обязательный параметр, строка |
date_to | Конечная дата выводимой статистики. Используется разный формат дат для разного значения параметра period:
1. day: YYYY-MM-DD, пример: 2011-09-27 2. month: YYYY-MM, пример: 2011-09 |
обязательный параметр, строка |
Результат:
Возвращает объект с данными
{ response: { count: %total items% items: { date shows clicks ctr cpm money } } }
Создание рекламной кампании
Для для создания новой рекламной кампании используется метод ads.campaigns.put. Допустимое количество кампаний, создаваемых с помощью одного запроса — 50.
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
campaign_id | id кампании | int (числовое значение), обязательный параметр |
client_specification | ||
client_id | id клиента, в рекламном кабинете которого будет создаваться кампания. Так же может принимать значение app_id (самого себя) | обязательный параметр, int (числовое значение) |
ad_format | Формат объявления:
10 - Тизерная; 20 - Баннерная; 30 - VK-message; 40 - Clickunder; 50 - Контекстная |
обязательный параметр, int (числовое значение) |
cost_type | Способ оплаты:
0 - СРС; 1 - СРА; 2 - СРМ |
обязательный параметр, int (числовое значение) |
Link_url | ссылка на рекламируемый объект в формате: http://yoursite.cоm | обязательный параметр, строка |
sex | Пол:
3 - любой; 2 - мужской; 1 - женский |
int (числовое значение) |
age | Возвраст, /data.ages | последовательность чисел, разделенных запятой |
cpa_mode | Тип уведомлений о конверсий для CPA, /ads.targeting.modes.get | int (числовое значение), обязательное для CPA кампании |
categories | идентификаторы категорий: /data.categories.get?ad_format=% category_id: {region_id: cost} |
|
tags | таргетинг по ключевым словам | последовательность ключевых слов, разделенных запятой: [“key1”, “key2”, .., “keyN”] Ключевые слова с ценой. Только для оплаты - за клики или за показы: {“key1”: “cost”, “key2”: “cost”, .., “keyN”: “cost”} cost - float |
day_limit | Дневной лимит в рублях. Для все типов кроме clickunder | положительное число |
all_limit | Общий лимит в рублях. Для все типов кроме clickunder | положительное число |
click_limit | Максимальное кол. переходов в день. Для все типов кроме clickunder. За показы и за клики. | положительное число |
conversion_limit | Максимальное кол. конверсий в день. Для все типов кроме clickunder. Только для CPA | положительное число |
adult_content | присутсвие контента для взрослых в рекламной кампании:
0 - Нет; 1 - Да |
необязательный параметр, int (числовое значение), по умолчанию 0 |
adult_site | Отображать объявления кампании на сайтах с контентом для взрослых:
0 - Нет; 1 - Да |
необязательный параметр, int (числовое значение), по умолчанию 0 |
time_show | Временной таргетинг:
* - отображение в любые часы и дни недели {} - массив, где ключ имя дня недели ["Sn","Mn","Tu","Wd","Th","Fr","Sa"]: {} - ‘mn’: ‘*’ - все часы понендельника {} - ‘mn’: [0, .., 23] - часы через запятую |
необязательный параметр, * по умолчанию |
platforms | таргетинг по платформам: /data.platforms | последовательность чисел, разделенных запятой |
browsers | таргетинг по браузерам: /data.browsers | последовательность чисел, разделенных запятой |
black_list | черный список площадок на которых не будет показана реклама | последовательность чисел ID площадок, разделенных запятой |
white_list | белый список площадок на которых не будет показана реклама | последовательность чисел ID площадок, разделенных запятой |
black_list_ip | блокировка по ip | последовательность ip адресов, разделенных запятой |
Результат:
Возвращает массив ответов на запросы в массиве data. Соответствующий объект в выходном массиве содержит id созданной кампании, и поля error_code и error_descв случае возникновения ошибки.
Errors:
102 - unknown client 103 - overlimit campaigns
Редактирование рекламных кампаний
Для редактирования рекламных кампаний используется метод ads.campaigns.update. Максимальное допустимое количество кампаний, редактируемых с помощью одного запроса — 50.
Version log: 1.0.1 - добавлен параметр status
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
data | сериализованный JSON-массив объектов, описывающих изменения в кампаниях. Описание объектов client_mod_specification см. ниже. | обязательный параметр, строка |
client_specification | ||
campaign_id | id редактируемой кампании | обязательный параметр, положительное число |
name | название кампании | необязательный параметр, строка длиной от 3 до 60 символов |
link_url | ссылка на рекламируемый объект в формате http://yoursite.cоm | необязательный параметр, строка |
sex | Пол:
3 - любой; 2 - мужской; 1 - женский |
необязательный параметр, int (числовое значение) |
age | возраст, /data.ages | необязательный параметр, int (числовое значение) |
categories | идентификаторы категорий
/data.categories.get?ad_format=% category_id: {region_id: cost} |
необязательный параметр |
tags | таргетинг по ключевым словам | необязательный параметр, последовательность ключевых слов, разделенных запятой |
day_limit | дневной лимит в рублях. для всех типов кроме clickunder | необязательный параметр, положительное число |
adult_content | присутсвие контента для взрослых в рекламной кампании:
0 - Нет; 1 - Да |
необязательный параметр, int (числовое значение), по умолчанию 0 |
adult_site | отображать объявления кампании на сайтах с контентом для взрослых:
0 - Нет; 1 - Да |
необязательный параметр, int (числовое значение), по умолчанию 0 |
time_show | Временной таргетинг:
* - отображение в любые часы и дни недели {} - массив, где ключ имя дня недели ["Sn","Mn","Tu","Wd","Th","Fr","Sa"]: {} - ‘mn’: ‘*’ - все часы понендельника {} - ‘mn’: [0, .., 23] - часы через запятую |
необязательный параметр, * по умолчанию |
platforms | таргетинг по платформам: /data.platforms | последовательность чисел, разделенных запятой |
browsers | таргетинг по браузерам: /data.browsers | последовательность чисел, разделенных запятой |
black_list | черный список площадок на которых не будет показана реклама | последовательность чисел ID площадок, разделенных запятой |
white_list | белый список площадок на которых не будет показана реклама | последовательность чисел ID площадок, разделенных запятой |
black_list_ip | блокировка по ip | последовательность ip адресов, разделенных запятой |
status | запуск/приостановка кампании:
0 - приостановлена; 1 - запущена |
необязательный параметр, int (числовое значение), по умолчанию 1 |
Результат:
Возвращает массив ответов на каждый запрос в массиве data. Соответствующий объект в выходном массиве содержит id изменяемого клиента и, в случае возникновения ошибки, поля error_code и error_desc.
Errors:
100 - unknown campaign 102 - unknown client
Список кампаний рекламного кабинета
Для получения списка кампаний рекламного кабинета используется метод ads.campaigns.get.
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
client_id | Идентификатор клиента, у которого запрашиваются рекламные кампании | int (числовое значение) |
include_archive | Флаг, задающий необходимость вывода архивных объявлений:
0 - выводить только активные кампании; 1 - выводить все кампании |
Флаг, может принимать значения 1 или 0 |
campaign_ids | Фильтр выводимых рекламных кампаний.
Сериализованный JSON-массив, содержащий id кампаний. Выводиться будут только кампании, присутствующие в campaign_ids и являющиеся кампаниями указанного рекламного кабинета. Если параметр равен null, то выводиться будут все кампании. |
Строка |
limit | ограничение на количество возвращаемых кампаний. Используется, только если параметр campaign_ids равен null | int (числовое значение) |
offset | смещение. Используется в тех же случаях, что и параметр limit | int (числовое значение) |
Результат:
Возвращает массив объектов campaign, каждый из которых содержит следующие поля:
response: { count: %total%, items: [{ id — идентификатор кампании name — название кампании status — статус кампании (0 — кампания остановлена, 1 — кампания запущена, 2 — кампания удалена) day_limit — дневной лимит кампании в рублях (0 — лимит не задан) all_limit — общий лимит кампании в рублях (0 — лимит не задан) ad_format — формат объявления cost_type — тип оплаты link_url - ссылка на рекламируемый объект sex - пол age - возраст regions - идентификаторы регионов categories - идентификаторы категорий. adult_content - присутсвие контент для взрослых adult_site - отображение объявлений кампании на сайтах с контентом для взрослых },..] }
Errors:
102 - unknown client
Архивирование клиентов рекламного агенства
Для архивирования клиентов рекламного агенства используется метод ads.campaigns.delete. Максимальное допустимое количество клиентов, редактируемых с помощью одного запроса — 10.
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
ids | Список id кампаний через запятую или массив с id кампаниями.
Например: “id1, id2, …, idn“ или [id1, id2, …, idn] |
обязательный параметр, строка |
Результат:
Возвращает массив ответов на каждый запрос. Каждый ответ является либо 0, что означает успешное удаление, либо массив error.
Errors:
100 - unknown campaign 101 - campaign already archive 102 - unknown client
Возвращение кодов для СРА кампаний
Для возврата кодов по СРА кампаниям используется метод ads.campaigns.cpa.mode.get
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
campaign_id | id кампании | int (числовое значение), обязательный параметр |
Результат:
Возвращает объект с данными.
{ response: { url: %url% } }
Возврат списка категорий по заданому фильтру
Для возврата списка категорий по заданому фильтру используется метод ads.campaigns.categories.get
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
ad_format | формат объявления | обязательный параметр, int (числовое значение) |
category_id | id категории. ограничивает отображение только по id категории | необязательный параметр, int (числовое значение) |
Результат:
Возвращает массив ответов на запросы в массиве response.
response: { count: %total%, items: [{ %category_id%: { %region_id%: { min: %min_cost%, max: %max_cost% } } },..] }
Возврат списка форматов объявлений
Для возврата списка форматов объявлений используется метод ads.campaigns.formats.get
Результат:
Возвращает массив ответов на запросы в массиве response.
response: { count: %total%, items: [{ id: %format_id%, title: ‘%format title%’ },..] }
Возврат списка платформ
Для возврата списка платформ используется метод ads.targeting.platforms.get
Результат:
Возвращает массив ответов на запросы в массиве response.
response: { count: %, items: [{ id: %platform_id%, title: %platform_name%, mobile: %is mobile% },..] }
Возврат списка браузеров
Для возврата списка браузеров используется метод ads.targeting.browsers.get
Результат:
Возвращает массив ответов на запросы в массиве response.
response: { count: %, items: [{ id: %browser_id%, title: %browser_name%, },..] }
Возврат списка уведомлений о конверсиях для СРА
Для возврата списка уведомлений о конверсиях для СРА используется метод ads.targeting.cpa.modes.get
Результат:
Возвращает массив ответов на запросы в массиве response.
response: { count: %, items: [{ id: %mode_id%, title: ‘%mode title%’ },..] }
Возврат списка возврастов
Для возврата списка возврастов используется метод ads.targeting.ages.get
Результат:
Возвращает массив ответов на запросы в массиве response.
response: { count: %, items: [{ id: %age_id%, title: %age_name% },..] }
Создание клиентов рекламного агенства
Для создания клиентов рекламного агенства используется метод ads.clients.put
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
name | название клиента | строка от 3 до 60 символов, обязательный параметр |
day_limit | day_limit | int (числовое значение) |
Результат:
Возвращает массив ответов на запросы в массиве data. Соответствующий объект в выходном массиве содержит информацию клиента или массив error в случае возникновения ошибки (для каждого клиента отдельно).
{ client_id — идентификатор клиента; name — название клиента; day_limit — дневной лимит клиента в рублях; }
Редактирование клиентов рекламного агенства
Для редактирования клиентов рекламного агенства используется метод ads.clients.update.
Максимальное допустимое количество клиентов, редактируемых с помощью одного запроса — 50.
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
data | сериализованный JSON-массив объектов, описывающих изменения в клиентах. Описание объектов client_mod_specification см. ниже. | обязательный параметр, строка |
client_mod_specification | ||
client_id | идентификатор редактируемого клиента | обязательный параметр, положительное число |
name | название клиента | строка длиной от 3 до 60 символов |
day_limit | дневной лимит в рублях | положительное число |
Результат:
Возвращает массив ответов на каждый запрос в массиве data. Соответствующий объект в выходном массиве содержит id изменяемого клиента и, в случае возникновения ошибки, поля error_code иerror_desc.
Получение списка клиентов рекламного агенства
Для возврата списка клиентов рекламного агенства используется метод ads.clients.get
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
client_ids | Список id клиентов через запятую. Например: “id1, id2, …, idn“ | необязательный параметр, строка |
Результат:
Возвращает массив объектов client — клиентов агентства, каждый из которых содержит следующие поля:
response: { count: %total%, items: [{ client_id — идентификатор клиента; name — название клиента; day_limit — дневной лимит клиента в рублях; balance - баланс клиента },..] }
Архивирование клиентов рекламного агенства
Для архивирования клиентов рекламного агенства используется метод ads.clients.delete.
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
ids | Список id клиентов через запятую или массив с id клиентами.
Например: “id1, id2, …, idn“ или [id1, id2, …, idn] |
обязательный параметр, строка |
Результат:
Возвращает массив ответов на каждый запрос. Каждый ответ является либо 0, что означает успешное удаление, либо массив error.
Подвязывание клиента к рекламному агенству
Для подвязывания клиента к рекламному агенству используется метод ads.clients.bind.put
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
email адрес клиента | строка от 3 до 60 символов, обязательный параметр | |
password | пароль клиента (от кабинета) | строка от 3 до 60 символов, обязательный параметр |
Результат:
Возвращает:
{ “bind”: true }
в случае успеха. Или error в случае возникновения ошибки.
Открепление клиента от рекламного агенства
Для открепления клиента от рекламного агенства используется метод ads.clients.unbind.put.
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
client_id | id клиента | int (числовое значение) |
Результат:
Возвращает:
{ “unbind”: true }
в случае успеха. Или error в случае возникновения ошибки.
Пополнение счета клиента
Для пополнения счета клиента используется метод ads.clients.balance.put.
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
client_id | id клиента для пополнения | int (числовое значение), обязательный параметр |
sum | сума в рублях | int (числовое значение) |
back_url | url куда переадресует клиента система пополнения | string (строка) |
system_id | id системы пополнения
data.balance.systems.get |
int (числовое значение), обязательный параметр |
Результат:
Возвращает url для оплаты:
{ response: { url: %url% } }
Создание рекламных объявлений
Для создания рекламных объявлений используется метод ads.materials.put.
Максимальное допустимое количество объявлений, создаваемых с помощью одного запроса — 20.
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
data | сериализованный JSON-массив объектов, описывающих создаваемые объявления. Описание объектов ad_specification см. ниже. | обязательный параметр, строка |
ad_specification | ||
campaign_id | id кампании, в которой будет создаваться объявление | обязательный параметр, int (числовое значение) |
title | заголовок объявления | обязательный параметр |
text | описание объявления | обязательно |
link_url | ссылка рекламируемого объекта в формате: http://yoursite.cоm | |
link_media | загруженный ранее медиа объект (jpg, gif, swf)
data.upload.media |
|
pause_after_moderate | установка объвление на паузу после модерации | |
size | только для банеров
ads.materials.banner.sizes |
Обновление данных рекламных объявлений
Для обновления данных рекламных объявлений используется метод ads.materials.update.
Максимальное допустимое количество объявлений, создаваемых с помощью одного запроса — 20.
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
data | сериализованный JSON-массив объектов, описывающих создаваемые объявления. Описание объектов ad_specification см. ниже | обязательный параметр, строка |
ad_specification | ||
material_id | id объявления | обязательный параметр, int (числовое значение) |
status | запуск/приостановка материала:
0 - приостановлена; 1 - запущена |
необязательный параметр, int (числовое значение), по умолчанию 1 |
Архивирование данных рекламных объявлений
Для архивирования данных рекламных объявлений используется метод ads.materials.delete.
Максимальное допустимое количество клиентов, редактируемых с помощью одного запроса — 50.
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
account_id | идентификатор рекламного кабинета | обязательный параметр, int (числовое значение) |
ids | сериализованный JSON-массив, содержащий идентификаторы объявлений | обязательный параметр, строка |
Результат:
Возвращает массив ответов на каждый запрос. Каждый ответ является либо 0, что означает успешное удаление, либо массив error.
Получение списка рекламных объявлений
Для получения списка рекламных объявлений используется метод ads.materials.get.
Параметры | Значение | Дополнительные атрибуты |
---|---|---|
account_id | идентификатор рекламного кабинета | обязательный параметр, int (числовое значение) |
client_id | Для рекламных агентств. Идентификатор клиента, у которого запрашиваются рекламные объявления. | int (числовое значение) |
archive | Флаг, задающий необходимость вывода архивных объявлений:
0 - выводить только активные объявления; 1 - выводить все объявления |
Флаг, может принимать значения 1 или 0 |
campaign_ids | фильтр по рекламным кампаниям.
Сериализованный JSON-массив, содержащий id кампаний. Если параметр равен null, то будут выводиться рекламные объявления всех кампаний. |
строка |
material_ids | фильтр по рекламным кампаниям.
Сериализованный JSON-массив, содержащий id объявлений. Если параметр равен null, то будут выводиться все рекламные объявления. |
строка |
limit | ограничение на количество возвращаемых объявлений. Используется, только если параметр ad_ids равен null, а параметр campaign_ids содержит id только одной кампании. | int (числовое значение) |
offset | смещение. Используется в тех же случаях, что и параметр limit | int (числовое значение) |
ad_format | формат объявления: ads.campaigns.formats.get | обязательный параметр, int (числовое значение) |
Результат:
Возвращает массив объектов ad, каждый из которых содержит следующие поля:
- id — идентификатор объявления
- name — название объявления
- campaign_id — идентификатор кампании
- link_url
- arhive
- ad_format — формат объявления
- cost_type — тип оплаты
- all_limit — общий лимит объявления в рублях
- 0 — лимит не задан
- status — статус объявления:
- 0 — объявление остановлено;
- 1 — объявление запущено;
- 2 — объявление удалено
- approved — статус модерации объявления:
- 0 — объявление ожидает модерации;
- 10 — объявление одобрено;
- 20 — объявление отклонено