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

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

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

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

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

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

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

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

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

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

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

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

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

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

Нет комментариев
новости,api5
В API Директа появятся данные о новых позициях спецразмещения
15 июня, 18:03

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

Расширенное спецразмещение будет показываться только для 2-3% запросов пользователей, поэтому интерфейс управления ставками в Директе не изменится. В API мы добавим данные для прицельной настройки ваших приложений: в ближайшее время сервис Bids начнет возвращать цены для новых позиций в спецразмещении.

Нет комментариев
новости
Корректировки ставок по региону показа
3 мая, 16:27

В сервис BidModifiers добавлена поддержка корректировок ставок по региону показа. Такие корректировки можно задать только на уровне кампании, указав в методе BidModifiers.add в RegionalAdjustments регион и значение коэффициента к ставке для показа объявлений в указанном регионе.

Нет комментариев
новости,api5
Сервис KeywordsResearch
18 апреля, 19:00

В API версии 5 появился сервис KeywordsResearch для получения прогноза наличия показов по ключевым фразам. С помощью метода hasSearchVolume для заданных ключевых фраз и регионов можно сформировать предварительный прогноз наличия показов по этим фразам в разбивке по типам устройств.

Нет комментариев
новости,api5
API 5: Статистика по всему аккаунту, кастомные отчёты и не только
22 марта, 18:09

В API Директа появился долгожданный сервис Reports для выгрузки статистики по рекламным кампаниям.

Описания параметров и инструкции по работе с сервисом подробно описаны в документации. Мы разработали несколько типов отчетов: от статистики по отдельным объявлениям до сводки по всему аккаунту рекламодателя. Есть и возможность получения статистики по поисковым запросам. А с помощью отчета CUSTOM_REPORT вы можете собрать отчет с любой комбинацией полей и условий отбора данных.

Отзывы и вопросы, как и всегда, можно отправить через форму обратной связи.

Успешной работы!

Нет комментариев
новости,api5
22 марта вступит в силу новый минимальный платеж
15 марта, 12:55

Хотим еще раз напомнить вам, что 22 марта в Директе изменится размер минимального платежа: новый порог составит 1 000 рублей без учета НДС вместо текущих 300 рублей. Значения для других валют вы можете посмотреть в таблице ниже.

Обратите внимание: речь идет только о новом пороге минимального платежа для пополнения баланса (например, пополнение общего счета, минимальная сумма кредитных зачислений и минимального переноса средств между кампаниями и клиентами), все остальные финансовые показатели Директа никак не изменятся. Например, минимальная цена клика и минимальный недельный бюджет останутся прежними.

Введение нового порога затронет работу «балансеров», или «биллингов», — инструментов на базе API Директа, которые позволяют распределять деньги (в том числе и с кредитной линии) между кампаниями и клиентами. Нередко приложения распределяют бюджет между Директом и другими рекламными платформами, используя минимально возможные платежи.

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

Валюта: Новая сумма — Старая сумма
Рубли РФ 1 000 руб. (до НДС) — 300 руб.
Гривны 250 грн. (до НДС) — 80 грн.
Белорусские рубли  30 BYN (до НДС) — 9 BYN
Тенге  5000 тенге (до НДС) — 1300 тенге
Турецкие лиры 50 TRY (до НДС) — 17 TRY
Доллары США 15 — 10
Евро 15 — 10
Швейц. франки 15 — 10
Уе 15 c НДС — 10 c НДС

В документации вы можете найти описание работы с финансовыми методами и общим счетом.

Нет комментариев
новости
Сервис AgencyClients для управления клиентами агентства
6 марта, 18:04

В API версии 5 появился сервис AgencyClients. Этот сервис предназначен для агентств.

Метод get сервиса AgencyClients возвращает список рекламодателей — клиентов агентства, их параметры и настройки главных представителей рекламодателя.

Обратите внимание: в запросе к этому сервису в HTTP-заголовке Authorization надо указать токен, полученный для представителя агентства. При этом HTTP-заголовок Client-Login указывать не нужно. Подробнее о ролях пользователей Директа можно узнать в разделе руководства в документации.

Нет комментариев
новости,api5
Таргетинг по интересам в API
28 февраля, 19:17

В API версии 5 появилась возможность таргетинга по интересам для рекламы мобильных приложений:

  • В метод Dictionaries.get добавлена возможность получать справочник интересов к категориям мобильных приложений.
  • В методе Changes.checkDictionaries добавлен параметр ответа InterestsChanged.
  • В методах сервиса AudienceTargets появился параметр InterestId (идентификатор интереса к категории мобильных приложений).
Нет комментариев
новости,api5
Добавлена поддержка минус-фраз
15 февраля, 14:46

Теперь вы сможете добавлять в кампании и группы объявлений не только минус-слова, но и минус-фразы — словосочетания длиной от 2 до 7 слов, разделенных пробелами. Поддержка появилась:

  • в сервисе AdGroups — в параметре группы объявлений NegativeKeywords;
  • в сервисе Campaigns — в параметре кампании NegativeKeywords.

А в методах CreateNewWordstatReport и CreateNewForecast (Live) добавлена поддержка минус-фраз в параметре Phrases.

Нет комментариев
новости,api5,api4live
Добавлена поддержка статуса «Мало показов»
26 января, 11:06
Добавлена поддержка статуса «Мало показов»: в методы AdGroups.get, Keywords.get и Bids.get добавлен параметр запроса ServingStatuses и параметр ответа ServingStatus.

В группах со статусом «Мало показов» (значение RARELY_SERVED) отключена возможность получать следующие данные по ключевым фразам:

  • StatisticsSearch и StatisticsNetwork в методе Keywords.get;
  • CompetitorsBids, SearchPrices, ContextCoverage, AuctionBids, MinSearchPrice, CurrentSearchPrice в методе Bids.get.
Нет комментариев
новости,api5
Подготовьтесь к изменению минимального платежа
19 января, 19:54

В марте в Директе изменится размер минимального платежа: новый порог составит 1 000 рублей без учета НДС вместо текущих 300 рублей. Значения для других валют вы можете посмотреть в таблице ниже.

Обратите внимание: речь идет только о новом пороге минимального платежа для пополнения баланса (например, пополнение общего счета, минимальная сумма кредитных зачислений и минимального переноса средств между кампаниями и клиентами), все остальные финансовые показатели Директа никак не изменятся. Например, минимальная цена клика и минимальный недельный бюджет останутся прежними.

Введение нового порога затронет работу «балансеров», или «биллингов», — инструментов на базе API Директа, которые позволяют распределять деньги (в том числе и с кредитной линии) между кампаниями и клиентами. Нередко приложения распределяют бюджет между Директом и другими рекламными платформами, используя минимально возможные платежи.

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

Валюта: Новая сумма — Сейчас
Рубли РФ 1 000 руб, до НДС — 300
Гривны 250 грн. до НДС — 80
Белорусские рубли  30 BYN до НДС — 9
Тенге  5000 тенге до НДС — 1300
Турецкие лиры 50 TRY до НДС — 17
Доллары США 15 — 10
Евро 15 — 10
Швейц. франки 15 — 10
Уе 15 c НДС — 10 c НДС

За несколько недель до вступления изменений в силу мы обязательно предупредим об этом всех рекламодателей Директа.

В документации вы можете найти описание работы с финансовыми методами и общим счетом.

Нет комментариев
новости
Статус RARELY_SERVED и другие изменения в API
20 декабря 2016, 16:54

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

Вот подробный список изменений в методах:

  1. Статус показов ServingStatus со значениями ELIGIBLE и RARELY_SERVED появится у групп в сервисе AdGroups (в методе get), а также будет доступен при запросе данных по ключевым фразам и ставкам в методе get сервисов Keywords и Bids.
  2. При статусе RARELY_SERVED — «Мало показов» — по ключевым фразам группы в Keywords.get не будут доступны данные StatisticsSearch и StatisticsNetwork.
    Также при таком статусе в Bids.get не будут возвращаться массивы CompetitorsBids, SearchPrices, AuctionBids. При этом значения параметров ContextCoverage, MinSearchPrice, CurrentSearchPrice в ответе сервера при запросе Bids.get вернутся пустыми.
  3. Третье изменение не связано напрямую с внедрением нового статуса, но тоже убирает ненужные сущности. Для ключевых фраз в кампаниях, работающих без раздельного управления ставками или только на поиске, в Bids.get не будет отдаваться «охват в сетях» — значение параметра ContextCoverage вернется пустым.
Нет комментариев
новости,api5
В API Директа появится поддержка минус-фраз
5 декабря 2016, 23:28

В ближайшее время мы планируем запустить в Директе минус-фразы: этот инструмент позволит отсекать нецелевые показы рекламы не только по отдельным словам, но и по словосочетаниям длиной от 2 до 7 слов. Например, к ключевой фразе строительство дома можно будет добавить минус-фразу своими руками вместо минус-слов свои, руки. Добавлять минус-фразы можно будет на уровне кампаний или групп объявлений.

Поддержка минус-фраз появится и в API Директа. В сервисах Campaigns и AdGroups в параметре NegativeKeywords можно будет указывать до семи слов, разделенных пробелами, в качестве элемента массива. Метод get этих сервисов тоже начнет возвращать минус-фразы.

Обратите внимание: запуск минус-фраз никак не повлияет на минус-слова, которые уже используются в ваших кампаниях. Однако после запуска при добавлении к минус-словам списка <быстро своими руками недорого> система будет считать его не набором отдельных минус-слов, а единой минус-фразой — объявление не покажется, только если в запросе пользователя есть сразу все эти слова.

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

Нет комментариев
новости,api5
Закрыты устаревшие методы API Live 4
5 декабря 2016, 16:05

Следующие методы API версии Live 4 были отключены в рамках очередного этапа перехода на пятую версию:

  • CreateOrUpdateCampaign (Live), GetCampaignsList (Live), GetCampaignsListFilter (Live), GetCampaignsParams (Live), GetCampaignParams (Live), DeleteCampaign (Live), ResumeCampaign (Live), StopCampaign (Live), ArchiveCampaign (Live), UnArchiveCampaign (Live).
  • CreateOrUpdateBanners (Live), GetBanners (Live), DeleteBanners (Live), ModerateBanners (Live), ResumeBanners (Live), StopBanners (Live), ArchiveBanners (Live), UnArchiveBanners (Live).
  • Keyword (Live), GetBannerPhrases (Live), GetBannerPhrasesFilter (Live), SetAutoPrice (Live), UpdatePrices (Live), GetChanges (Live).

Руководство по переходу и описание отличий API Live 4 и API 5 смотрите в документации.

Нет комментариев
новости,api4live
Закрываем устаревшие методы API Live 4
25 ноября 2016, 11:50

Мы продолжаем развивать API 5 и постепенно ограничивать использование прошлых версий нашего программного интерфейса.

Как вы знаете, этим летом в API 4 была закрыта часть устаревших методов, а в API Live 4 на использование аналогичных методов введено ограничение. Полностью отключить эти методы в API Live 4 мы планируем 5 декабря.

Подробный список методов версии Live 4, которых затронут эти изменения:

CreateOrUpdateCampaign (Live), GetCampaignsList (Live), GetCampaignsListFilter (Live), GetCampaignsParams (Live), GetCampaignParams (Live), DeleteCampaign (Live), ResumeCampaign (Live), StopCampaign (Live), ArchiveCampaign (Live), UnArchiveCampaign (Live), CreateOrUpdateBanners (Live), GetBanners (Live), DeleteBanners (Live), ModerateBanners (Live), ResumeBanners (Live), StopBanners (Live), ArchiveBanners (Live), UnArchiveBanners (Live), Keyword (Live), GetBannerPhrases (Live), GetBannerPhrasesFilter (Live), SetAutoPrice (Live), UpdatePrices (Live), GetChanges (Live).

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

Руководство по переходу на пятую версию.

Нет комментариев
новости,api4live
Сервис Clients для получения сведений о клиентах
9 ноября 2016, 17:07

В API версии 5 появился сервис для получения сведений о клиентах — сервис Clients.

С помощью метода get этого сервиса представитель рекламодателя может получить параметры рекламодателя и собственные настройки. Представитель агентства может получить параметры своего клиента-рекламодателя и настройки пользователя, чей логин указан в HTTP-заголовке Client-Login.

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

Нет комментариев
api5,новости
Переход из условных единиц в валюту платежа
17 октября 2016, 15:54

Мы начинаем постепенно переводить аккаунты рекламодателей в ту валюту, в которой они оплачивают размещение. Для рекламодателей, работающих в у. е. и не осуществлявших оплату более года, доступ к аккаунту может быть приостановлен. В этом случае при попытке вызова методов API выдается ошибка 54, а в веб-интерфейсе недоступны никакие операции, кроме перевода в валюту.

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

Нет комментариев
новости
Дайджест новостей
14 октября 2016, 19:52
  • Внесены изменения в справочник регионов. Рекомендуем получить обновленный справочник с помощью метода get сервиса Dictionaries или метода GetRegions (Live).
  • В методах сервиса Ads расширен набор возможных значений параметра Action для рекламы мобильных приложений. Теперь для надписи на кнопке доступны следующие значения: DOWNLOAD — «Загрузить», GET — «Скачать», INSTALL — «Установить», MORE — «Подробнее», OPEN — «Открыть», UPDATE — «Обновить», PLAY — «Играть», BUY_AUTODETECT — «Купить».
  • На следующей неделе будет добавлено ограничение для ключевых фраз: длина каждого слова и минус-слова в ключевой фразе — не более 35 символов.
  • С 10 октября 2016 г. рекламные агентства могут регистрировать только клиентов, работающих в реальной валюте. Возможность регистрации новых клиентов, работающих в у. е., отключена. В связи с этим изменена логика работы метода CreateNewSubclient (Live).
Нет комментариев
новости,api4live,api5
Скоро: изменения в структуре дерева регионов — Украина и страны Балтии
5 октября 2016, 17:58

Через неделю в структуре дерева регионов в Директе произойдут несколько важных изменений.

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

Схему изменений дерева регионов с ID регионов смотрите в документации.

Планируемые изменения:

1. Удаление дополнительного уровня вложенности в дереве регионов Украины: Центр, Запад, Восток, Юг, Север.
Таким образом, настройка вида: «Украина -> Восток -> Харьков и область» в результате изменений станет такой: «Украина -> Харьков и область».

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

2. Отражение официального переименования некоторых городов Украины.

3. Удаление дополнительного уровня вложенности «страны Балтии»:
Например, настройка вида: «Европа -> Страны Балтии -> Латвия, Литва, Эстония» изменится на «Европа -> Латвия, Литва, Эстония».

4. Добавление в геодерево Румынии и Португалии.

Обратите внимание:  в связи с изменениями у некоторых городов изменится идентификатор родительского региона в API. Например, для города Харьков ParentID станет Украина (вместо текущего «Восток»).

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