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

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

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

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

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

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

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

Объём трафика и взвешенный 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
Изменения в расчёте баллов: Keywords.get и Bids.get
23 ноября 2017, 02:16

На следующей неделе мы изменим количество списываемых баллов и логику их расчёта в методе get сервисов Keywords и Bids.

Ранее на получение данных по ключевым фразам (Keywords.get) вы тратили 1 балл за каждую фразу и 15 баллов за вызов метода. Мы решили уменьшить затраты в баллах на эти операции и сбалансировать баллы при работе с сервисами Keywords и Bids.

Какими станут значения:

  • Keywords.get – 1 балл за 2000 фраз, если не запрошен ни один из параметров Productivity, StatisticsSearch, StatisticsNetwork и 3 балла за 2000 фраз с запросом любых статистических данных.
  • Bids.get – 3 балла за 2000 фраз.

Если получено менее 2000 фраз, баллы списываются только за вызов метода. Количество баллов за вызов метода get в этих сервисах не изменится.

Таким образом, затраты баллов в целом снизятся, особенно если до этого у вас много баллов уходило на синхронизацию данных по ключевым фразам. К тому же вы сможете с большей гибкостью выбирать, какие именно данные по ключевым фразам вы получите и сколько на это потратите.

Нет комментариев
новости,api5
Поддержка автотаргетинга и другие изменения
18 октября 2017, 12:48
  • В API Директа появилась поддержка автотаргетинга в сервисах Bids, Keywords и Reports. Технология автотаргетинга позволяет показывать объявления по запросам, релевантным тексту объявления и странице, на которую ведет ссылка, без использования ключевых фраз.

    Детальнее узнать об использовании автотаргетинга в API вы можете в новом разделе документации и в описании соответствующих методов.
  • Для общего счета добавлена поддержка дневного ограничения в методе AccountManagement (Live): входные параметры AccountDayBudget, PausedByDayBudgetSms, PausedByDayBudget операции Update и аналогичные результирующие параметры операции Get.
  • В сервис Reports добавлен заголовок ответа reportsInQueue c количеством офлайн-отчетов, находящихся в очереди, и возможность фильтрации по полю CampaignType.
Нет комментариев
новости,api5,api4live
API: Настройка отображения данных об организации при показе объявлений на Яндекс.Картах
19 сентября 2017, 15:05

В API появилась поддержка настройки отображения данных об организации из Яндекс.Справочника при показе объявлений на Яндекс.Картах: в методы сервиса Campaigns (для кампаний с типом «Текстово-графические объявления» и «Динамические объявления») добавлена настройка кампании ENABLE_COMPANY_INFO.

Нет комментариев
новости,api5
Новости и будущие изменения в API Директа
15 сентября 2017, 17:01

В пятой версии API в сервисе статистических отчетов Reports появилась долгожданная поддержка запросов в формате JSON. Кроме того, мы дополнили документацию новыми примерами взаимодействия с методами API.

В сервисы AgencyClients и Clients мы добавили новые методы для работы с настройками клиентов агентств, рекламодателей и их представителей (Clients.update, AgencyClients.add, AgencyClients.update). А в сервисе Campaigns была отключена опция «Не учитывать предпочтения пользователей» (настройка ENABLE_BEHAVIORAL_TARGETING в структуре Settings).

Также мы продолжаем постепенно закрывать устаревшие методы версий API 4 и Live 4:

  1. В декабре 2017 года мы планируем отключить следующие методы: UpdateClientInfo и UpdateClientInfo (Live), GetSubClients, GetClientsList и GetClientsList (Live), GetClientInfo и GetClientInfo (Live), CreateNewSubclient и CreateNewSubclient (Live), GetClientsUnits, RetargetingCondition (Live), Retargeting (Live).
  2. Методы работы со статистикой в версиях 4 и Live 4 будут отключены в феврале 2018 года:
    CreateNewReport и CreateNewReport (Live), GetReportList, DeleteReport, GetBalance и GetBalance (Live), GetSummaryStat (Live), GetBannersStat (Live).

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

В документации в разделе «Руководство по переходу» вы найдете всю информацию о соответствии методов и их параметров в версиях API Live 4 и API 5 — для корректной миграции ваших приложений на пятую версию API.

О каждом из этапов закрытия методов мы сообщим вам дополнительно.

Нет комментариев
новости,api5,api4live,api4
В API появилась поддержка второго заголовка
15 августа 2017, 16:53

Теперь вы сможете использовать два заголовка ― длиной до 35 и до 30 символов ― а также писать тексты объявлений длиной до 81 символа включительно: 

  • В методы сервиса Ads добавлен параметр Title2 для текстово-графических объявлений.
  • Изменены ограничения на количество символов в полях TitleText для текстово-графических объявлений, в поле Text для динамических объявлений. Рекомендуем получить обновленный справочник ограничений с помощью метода Dictionaries.get, указав в запросе имя справочника Constants.
Нет комментариев
api5,новости
Больше данных в отчёте Reports и другие новости
7 августа 2017, 19:07

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

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

Еще новости: теперь автофокус будет работать «из коробки», настройка ENABLE_AUTOFOCUS в структуре Settings больше не поддерживается в сервисе Campaigns.

Нет комментариев
новости,api5
Дополнительные фразы стали проще в настройке
22 июня 2017, 21:15

Мы объединили авторасширение и показы по дополнительным релевантным фразам, чтобы вам было проще их настраивать:

1. В сервисе Campaigns изменены настройки показов по дополнительным релевантным фразам для кампаний с типом «Текстово-графические объявления»:

  • Параметр BudgetPercent структуры RelevantKeywords поддерживает любые целочисленные значения от 1 до 100.
  • Параметр Mode структуры RelevantKeywords не поддерживается, переданное значение игнорируется.
  • Настройка ENABLE_RELATED_KEYWORDS в структуре Settings больше не поддерживается.

2. В сервис Reports добавлены поля MatchedKeyword, Criterion, CriterionId.

Нет комментариев
новости,api5
Данные для новых позиций спецразмещения
20 июня 2017, 15:53

В сервис Bids добавлена поддержка 4-й позиции в спецразмещении. В параметре Position массива AuctionBids, возвращаемого методом Bids.get, добавлено P14 (четвёртое место в спецразмещении) со значениями минимальной ставки и списываемой цены. В массиве SearchPrices для Position="PREMIUMBLOCK" отдается значение P14 — это цена входа в спецразмещение. Также добавлена поддержка P14 в параметре запроса Position метода Bids.setAuto.

Нет комментариев
новости,api5