API Яндекс.Директа

Здесь мы будем рассказывать о новостях и тонкостях использования нашего API.

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

Чтобы начать работу с API Яндекс.Директа, ознакомьтесь с информацией о доступе. Посмотрите рекомендации и требования к приложениям, если вы хотите написать на основе API свою программу.

Вопросы об API можно задавать через форму обратной связи.

Другие полезные ссылки:
Обучающий онлайн-курс Как начать работать с API
Руководство по переходу с версий 4 и Live 4 на версию 5
Коды ошибок и предупреждений
Форма для отзывов и предложений
Английская версия блога
RSS-канал блога

Команда API Яндекс.Директа

Скоро: изменения в справочнике регионов
4 декабря, 20:24

Забайкальский край и Республика Бурятия, прежде входившие в Сибирский федеральный округ, теперь относятся к Дальневосточному. В ближайшее время административные изменения отразятся в справочнике регионов, который возвращают методы Dictionaries.get (в API версии 5) и GetRegions (в API версии 4 и Live 4).

Если ваше приложение не поддерживает автоматическое обновление справочника регионов, вам необходимо будет внести изменения вручную. О доступности обновленного справочника мы сообщим дополнительно.

Отключаем поддержку у. е. в справочнике валют
29 ноября, 19:46

Условные единицы (у. е.) больше не используются, клиенты Директа ведут рекламные кампании в реальной валюте.

Приблизительно через неделю метод Dictionaries.get перестанет возвращать данные об у. е. в справочнике Currencies:

  • из справочника будет исключена валюта YND_FIXED;
  • для остальных валют не будет возвращаться курс у. е. — параметры Rate и RateWithVAT.

Пожалуйста, убедитесь, что ваши приложения не используют эти данные. Любые вопросы вы можете задать специалистам службы поддержки API Директа.

новости,api5
Новое в API: поведенческие признаки и другие изменения
14 ноября, 14:33

Для нацеливания медийной рекламы стали доступны сегменты Крипты по поведенческим признакам:

  • Сервис RetargetingLists поддерживает использование сегментов по поведенческим признакам в условии нацеливания по профилю пользователей.
  • Метод Dictionaries.get возвращает поведенческие признаки в справочнике AudienceCriteriaTypes и сегменты по поведенческим признакам в справочнике AudienceDemographicProfiles.

В справочник Currencies, возвращаемый методом Dictionaries.get, добавлены минимальная и максимальная ставка или цена за тысячу показов для медийной рекламы.

Для рекламы мобильных приложений добавлено ограничение: во всех группах объявлений одной кампании должна быть указана одинаковая ссылка на приложение.

новости,api5
API версии 4 и Live 4: отключаем поддержку у. е.
8 ноября, 10:53

Перевод аккаунтов в реальные валюты, начавшийся в 2013 году, завершается. Большинство рекламодателей и агентств уже ведут рекламные кампании в той валюте, в которой оплачивают счета, и скоро аккаунтов в условных единицах не останется совсем.

В течение переходного периода ряд методов API позволяли приложению оперировать денежными значениями, выраженными в у. е., даже если кампания и аккаунт работают в реальной валюте. С 3 декабря мы планируем ограничить работу таких методов. Пожалуйста, подготовьте свои приложения к предстоящим изменениям.

Методы, которые будут полностью отключены:

  • Методы версии 4: GetBalance, GetSummaryStat, CreateNewReport, CreateNewForecast, GetForecast, CreateInvoice, PayCampaigns, TransferMoney.
  • Методы версии Live 4: GetBalance (Live), GetClientInfo (Live), GetClientsList (Live).

Методы, которые будут работать только в реальной валюте кампании или аккаунта:

  • Retargeting (Live), операции Add, Update, Get
  • CreateInvoice (Live)
  • PayCampaigns (Live)
  • TransferMoney (Live)
  • AccountManagement (Live), операции Deposit, Invoice и TransferMoney
  • CreateNewForecast (Live)
  • GetEventsLog (Live)

Входной параметр Currency в этих методах станет обязательным. Его значение должно совпадать с валютой кампании или аккаунта — для всех методов, кроме CreateNewForecast (Live) и GetEventsLog (Live).

Методы, которые будут формировать статистику только в валюте кампании:

  • GetBannersStat (Live)
  • GetSummaryStat (Live)
  • CreateNewReport (Live)

В этих методах входной параметр Currency станет обязательным, если кампания ведется в реальной валюте. Для кампаний в у. е., перемещенных в специальный архив, параметр Currency можно не указывать или передавать NULL.

Изменения не затронут методы API версии 5, поскольку все эти методы уже сейчас принимают и возвращают денежные значения в валюте рекламодателя.

Обратите внимание: для получения статистики, управления ретаргетингами и клиентами мы рекомендуем использовать методы API версии 5. В Руководстве по переходу вы найдете подробную информацию о том, какие методы версии 5 можно использовать, и о соответствии параметров в разных версиях.

Если у вас появились вопросы, вы можете задать их специалистам службы поддержки API Директа.

новости,api4,api4live
Видеообъявления и получение креативов
3 октября, 16:13

Видеорекламу в Директе теперь можно запустить не только как видеодополнение к текстово-графическому объявлению, но и как отдельное видеообъявление. Для этого в сервис Ads добавлен новый тип объявления — CPC_VIDEO_AD.

Размещать видеообъявления можно в группах текстово-графических объявлений. Для создания или редактирования видеообъявления его параметры необходимо передавать в структуре CpcVideoAdBuilderAd методов add, update.

Узнать идентификаторы креативов можно с помощью метода Creatives.get. Создание креативов доступно только в веб-интерфейсе.

Подробности работы с видеообъявлениями в API вы можете найти в документации.

новости,api5
Кросс-минусовка и склейка дублей ключевых фраз в API
1 октября, 17:04

Новый метод KeywordsResearch.deduplicate позволяет оптимизировать набор ключевых фраз:

  • Исправить пересекающиеся фразы, соответствующие одному и тому же поисковому запросу. Если две фразы отличаются на одно слово, к одной из них добавляется минус-слово. Например, фразы шуба и шуба норковая будут преобразованы во фразы шуба -норковая и шуба норковая.
  • Объединить несколько фраз, отличающихся только минус-словами. Объединенная фраза будет содержать минус-слова всех исходных фраз.
  • Отбросить фразы, которые невозможно сохранить из-за ошибок.

На вход метода можно подать как фразы, уже имеющие идентификатор в Директе или внешней базе данных, так и новые фразы без идентификатора. Метод возвращает рекомендации, какие фразы нужно добавить, изменить или удалить. Формат ответа максимально приближен к формату запроса для методов addupdate и delete сервиса Keywords.

Подробнее о методе KeywordsResearch.deduplicate читайте в документации.

api5,новости
Медийные кампании в API Директа
27 сентября, 11:34

Медийные кампании идеально работают на укрепление лояльности к бренду. Они привлекают целевую аудиторию и поставляют ее на следующие этапы воронки продаж, передавая эстафету вашим контекстным объявлениям, а затем ретаргетингу.

Чтобы вам было удобнее автоматизировать закупки для всего медиамикса, мы добавили возможность управлять медийными кампаниями в API Директа:

  • Сервис Campaigns поддерживает новый тип кампаний — CPM_BANNER_CAMPAIGN.
  • Cервис AdGroups поддерживает новый тип группы — CPM_BANNER_AD_GROUP.
  • Сервис Ads поддерживает новый тип объявлений — CPM_BANNER_AD. Креативы можно сконструировать и загрузить в веб-интерфейсе, а затем использовать их для создания объявлений в API.
  • В группу медийных объявлений можно добавить ключевые фразы с помощью сервиса Keywords или условие нацеливания по профилю пользователей с помощью сервиса AudienceTargets.
  • Настроить профиль пользователей можно с помощью сервиса RetargetingLists: профиль реализован как условие ретаргетинга и подбора аудитории с типом AUDIENCE.
  • В профиле можно использовать сегменты по социально-демографическим характеристикам и по интересам пользователя — получить их можно с помощью сервиса Dictionaries.

Для получения статистики по медийным кампаниям можно воспользоваться типом отчета REACH_AND_FREQUENCY_PERFORMANCE_REPORT в сервисе Reports.

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

новости,api5
Возрастные группы 45–54 и 55+ доступны в API
21 августа, 23:41

Изменения, о которых мы писали ранее, вступили в силу: в корректировках ставок и статистике Директа появились две новые возрастные группы.

В сервисе BidModifiers мы рекомендуем создавать отдельные корректировки ставок для срезов AGE_45_54 и AGE_55. Старый срез AGE_45 останется доступным в течение нескольких месяцев.

В отчётах сервиса Reports новые срезы появятся в статистике за даты начиная с 21 августа 2018 года.

новости,api5
Объём трафика и взвешенный CTR в статистике
8 августа, 17:30

В сервисе Reports появились поля, которые ранее были доступны только в Мастере отчётов:

  • AvgTrafficVolume — средний объём выкупаемого трафика;
  • WeightedCtr — взвешенный CTR: показатель кликабельности, скорректированный с учётом объёмов трафика на позициях, где показываются объявления;
  • WeightedImpressions — взвешенные показы: каждый показ учитывается с весом, пропорциональным объёму трафика с позиции.
новости,api5
Новые возрастные группы в корректировках ставок и статистике
7 августа, 10:49

Хотим предупредить вас о предстоящих изменениях в Директе, чтобы вы могли заранее подготовить к ним свои приложения.

Сейчас Директ делит пользователей на пять возрастных групп: 0–17, 18–24, 25–34, 35–44 и старше 45 лет. В группу 45+ попадают слишком разные пользователи, поэтому мы разделим её на две: 45–54 и старше 55. Переход на шесть возрастных групп планируется во второй половине августа.

Зачем это нужно

Новые возрастные группы позволят более гибко нацеливать показы объявлений на нужную аудиторию, управляя ставками в сервисе BidModifiers: вы сможете настроить отдельные корректировки ставок для срезов AGE_45_54 и AGE_55.

Старый срез AGE_45 останется доступным в течение нескольких месяцев. Мы рекомендуем поддержать в приложениях новые срезы — пользователи могут выбрать их при создании корректировок в веб-интерфейсе.

А что со статистикой?

В отчётах сервиса Reports одни и те же пользователи могут быть отнесены к разным возрастным группам в зависимости от даты показа или клика:

  • до перехода на новую классификацию в поле Age выводится значение AGE_45,
  • после перехода — AGE_45_54 или AGE_55.

Если дата перехода попадает в период отчёта, в нём могут появиться все три значения. Обратите внимание: как именно будет определена возрастная группа пользователя в отчёте, зависит не от даты, когда отправлен запрос на формирование отчёта, а от даты, за которую собрана статистика.

Если вы используете в отчётах отбор данных по значению поля Age, то для получения статистики по всем пользователям 45+ мы рекомендуем указать в фильтре все три значения — AGE_45, AGE_45_54 и AGE_55:

"Filter": [{
   "Field": "Age",
   "Operator": "IN",
   "Values": ["AGE_45", "AGE_45_54", "AGE_55"]
}]

Если в фильтре указан срез AGE_45 и не указаны новые срезы AGE_45_54 и AGE_55, а период отчета целиком следует после даты перехода, то будет выдано сообщение об ошибке, поскольку такой запрос не позволяет получить корректные данные.

Если в фильтре указаны не все срезы, то статистика за период, включающий дату перехода, может оказаться неполной. Например, если указаны только новые срезы, в отчёт не попадут пользователи, чья возрастная группа определена по старой классификации как 45+.

При запросе отчёта за период после даты перехода достаточно указать в фильтре только новые срезы. Допустимо также указать все три значения — AGE_45, AGE_45_54 и AGE_55. Новые срезы AGE_45_54 и AGE_55 можно добавить в фильтр по полю Age уже сейчас. 

О переходе на шесть возрастных групп в корректировках ставок и статистике мы сообщим отдельно — следите за новостями.

Если у вас появились вопросы, вы можете задать их специалистам службы поддержки API Директа.

новости,api5
Перезагрузка Песочницы — 17 июля
3 июля, 16:58

17 июля мы планируем перезагрузку данных в тестовой среде для отладки приложений — Песочнице. В этот день Песочница будет выключена, а тестовые данные удалены. После перезагрузки вы сможете включить её снова, она будет работать как обычно.

Как вы знаете, при включенной Песочнице тестовые данные в аккаунте хранятся некоторое время со дня последнего обращения к ним через API. Вместо этого правила мы вводим механизм периодической очистки тестовых данных — это нужно для стабилизации работы Песочницы.

После обновления вы можете включить Песочницу в веб-интерфейсе Директа на странице «Настройки API» на вкладке «Песочница». А создавать тестовые кампании вы можете так же, как раньше — в веб-интерфейсе при инициализации Песочницы или добавить их позже через API.

В скором времени мы перейдем на регулярную очистку тестовых данных в Песочнице, о чём обязательно предупредим вас заранее.

api5,api4live,api4,новости
Модели атрибуции и цели в Reports
8 июня, 18:48

Мы добавили новые параметры в сервис Reports: Goals — идентификаторы целей Яндекс.Метрики, по которым требуется получить статистику, и AttributionModels — модели атрибуции, используемые при расчете данных по целям. Возможные значения моделей атрибуции: LSC (последний значимый переход), FC (первый переход), LC (последний переход).

Кроме того, был изменен способ расчета значения поля ConversionRate: теперь количество целевых визитов делится не на общее количество визитов, а на количество кликов.

Мы подготовили для вас пример, который демонстрирует получение данных Яндекс.Метрики по выбранным целям и заданной модели атрибуции.

Теперь сервис Reports позволяет получить статистику по цели. В сервисе реализованы все доступные возможности статистических отчетов API прошлых версий, поэтому статистические методы API 4  и Live 4 в ближайшем будущем будут закрыты.

Дополнительное изменение: в методе setAuto сервиса KeywordBids добавлен новый параметр BidCeiling для ограничения ставки.

новости,api5
Сервис KeywordBids: новый метод setAuto
31 мая, 15:12

В сервис KeywordBids добавлен метод setAuto. Метод назначает для фраз ставки на поиске в зависимости от желаемого объема трафика, а также ставки в сетях в зависимости от желаемой частоты показа (доли аудитории).

новости,api5
Cтатистика для медийных кампаний в Reports
3 мая, 18:52

В сервис Reports добавлена возможность получать статистику кампаний с типом «Медийная кампания»:

  • Для поля CampaignType добавлено значение CPM_BANNER_CAMPAIGN.
  • Добавлен новый тип отчета REACH_AND_FREQUENCY_PERFORMANCE_REPORT, в котором доступны новые поля AvgCpm (средняя стоимость тысячи показов), AvgImpressionFrequency (средняя частота показов одному пользователю) и ImpressionReach (охват по показам).
новости,api5
Новый подход к назначению ставок: KeywordBids уже можно тестировать
12 апреля, 13:57

Открытая бета-версия сервиса API KeywordBids, для которого мы недавно опубликовали документацию, уже работает в полной версии API Директа. Вы можете начать тестировать свои приложения, чтобы заранее подготовиться к запуску нового интерфейса назначения ставок в Яндекс.Директе.

Как вы помните, цены в Директе скоро будут рассчитываться не за позиции на поиске, а за объёмы трафика, которые соответствуют разным местам показа и дизайну объявлений. Перемена важная, но совсем не страшная — вы сможете решать все привычные задачи и при этом будете лучше ориентироваться в ценах аукциона. Вот ответы на несколько частых вопросов о запуске:

  • Аукцион и ранжирование на поиске не меняются. Повышая релевантность и CTR объявлений, вы по-прежнему можете получить показы на более заметных позициях по выгодной цене за клик.
    Запуск нового интерфейса никак не провоцирует рост или снижение стоимости кликов на поиске — ценообразование остаётся прежним. Списываемые цены, как и сейчас, будут рассчитываться по правилам VCG-аукциона.
  • Новый сервис KeywordBids предоставляет больше данных. Он отдаёт весь массив ставок и списываемых цен на поиске. Включая, к примеру, цены за показы объявлений в расширенном виде. Чем больше новых форматов и мест показа будет появляться на поиске, тем выгоднее KeywordBids будет отличаться от постепенно устаревающих методов расчёта цен за позиции.
  • Сервис Bids не отключается, а в ваших приложениях ничего не сломается после запуска. Bids будет по-прежнему доступен на время переходного периода, чтобы у вас была возможность постепенно освоить работу с новым сервисом и изменить логику выставления ставок в приложениях. Это означает, что вы будете видеть ставки для позиций, в том числе, после запуска нового интерфейса назначения ставок — мы будем сопоставлять позиции с примерными объёмами трафика на своей стороне.

Когда ждать изменений в веб-интерфейсе

Мы рассчитываем обновить интерфейс назначения ставок через полторы-две недели, в двадцатых числах апреля. Про это обязательно будет отдельная новость.

16 апреля на конференции Яндекс.Директа расскажем подробности не только об этом запуске, но и о других важных новинках и планах. Посмотрите трансляцию, будет интересно!
Зарегистрироваться

новости,api5
Отключена поддержка стратегии IMPRESSIONS_BELOW_SEARCH
30 марта, 14:50

В  сервисе Campaigns отключена поддержка стратегии IMPRESSIONS_BELOW_SEARCH («Показывать на поиске только под результатами») для всех типов кампаний. Если передать это значение в параметре BiddingStrategyType структуры Search, возвращается ошибка.

Рекламодатели, которые использовали эту стратегию в API Директа, продолжают размещение по своим прежним «ручным» настройкам — получают максимум трафика по заданным ценам, но уже без ограничения в позициях показа.

новости,api5
Корректировки для видео в API
26 февраля, 18:57

Сервис BidModifiers теперь поддерживает корректировку ставок по видео (VideoAdjustment): коэффициент к ставке применяется при показе объявлений с видеодополнением.

api5,новости
Новости API Директа
31 января, 19:03

Метод Clients.get теперь позволяет получить параметры агентства и настройки пользователя — представителя агентства.

А в сервис Reports мы добавили поле CriterionType  — тип условия показа, заданного рекламодателем.

новости,api5
В API появились графические объявления на основе креативов
15 декабря 2017, 13:31

В сервис Ads добавлена поддержка графических объявлений на основе креативов, созданных в конструкторе креативов — новые подтипы типа IMAGE_AD.

Подробнее о работе с типами объявлений в API Директа читайте в документации.

новости,api5
Поддержка графических объявлений на основе креативов
8 декабря 2017, 19:48

На следующей неделе в API появится поддержка графических объявлений на основе креативов, созданных в конструкторе креативов.

В сервисе Ads для таких объявлений будут добавлены новые подтипы типа IMAGE_AD: TEXT_AD_BUILDER_AD (для группы текстово-графических объявлений) и MOBILE_APP_AD_BUILDER_AD (для рекламы мобильных приложений).

Как работать с объявлениями нового подтипа:

  • Для создания или редактирования такого объявления его параметры необходимо передавать в соответствующей структуре TextAdBuilderAd или MobileAppAdBuilderAd методов add, update.
  • Чтобы получить параметры объявления, необходимо перечислить имена параметров во входном параметре TextAdBuilderAdFieldNames или MobileAppAdBuilderAdFieldNames метода get.

Создание креативов доступно только в веб-интерфейсе Директа. Получить список ID своих креативов можно в конструкторе креативов.

Подробности работы с такими объявлениями в API вы можете найти в документации.

новости,api5