Table Of ContentAPI Яндекс.Директа. Версия 5
API Яндекс.Директа. Версия 5
12.04.2019
API Яндекс.Директа. Версия 5. Версия 5
Дата подготовки документа: 12.04.2019
Этот документ является составной частью технической документации Яндекса.
© 2008—2019 ООО «ЯНДЕКС». Все права защищены.
Предупреждение об исключительных правах и конфиденциальной
информации
Исключительные права на все результаты интеллектуальной деятельности и приравненные к ним средства индивидуализации юридических
лиц, товаров, работ, услуг и предприятий, которым предоставляется правовая охрана (интеллектуальную собственность), используемые
при разработке, поддержке и эксплуатации службы , включая, но не ограничиваясь, программы для ЭВМ, базы данных, изображения,
тексты, другие произведения, а также изобретения, полезные модели, товарные знаки, знаки обслуживания, коммерческие обозначения и
фирменные наименования, принадлежат ООО «ЯНДЕКС» либо его лицензиарам.
Использование результатов интеллектуальной деятельности и приравненных к ним средств индивидуализации в целях, не связанных
с разработкой, поддержкой и эксплуатацией службы , не допускается без получения предварительного согласия правообладателя.
Настоящий документ содержит конфиденциальную информацию ООО «ЯНДЕКС». Использование конфиденциальной информации в
целях, не связанных с разработкой, поддержкой и эксплуатацией службы , а равно как и разглашение таковой, не допускается. При этом
под разглашением понимается любое действие или бездействие, в результате которых конфиденциальная информация в любой возможной
форме (устной, письменной, иной форме, в том числе с использованием технических средств) становится известной третьим лицам без
согласия обладателя такой информации либо вопреки трудовому или гражданско-правовому договору.
Отношения ООО «ЯНДЕКС» с лицами, привлекаемыми для разработки, поддержки и эксплуатации службы , регулируются
законодательством Российской Федерации и заключаемыми в соответствии с ним трудовыми и/или гражданско-правовыми договорами
(соглашениями). Нарушение требований об охране результатов интеллектуальной деятельности и приравненных к ним средств
индивидуализации, а равно как и конфиденциальной информации, влечет за собой дисциплинарную, гражданско-правовую,
административную или уголовную ответственность в соответствии с законодательством Российской Федерации.
Контактная информация
ООО «ЯНДЕКС»
https://www.yandex.ru
Тел.: +7 495 739 7000
Email: [email protected]
Главный офис: 119021, Россия, г. Москва, ул. Льва Толстого, д. 16
Содержание
Как начать работу с API: обучающий курс.............................................................................8
Урок 1. Что такое API Директа....................................................................................................................8
Урок 2. Доступ к API: как зарегистрировать приложение на Яндекс.OAuth..........................................14
Урок 3. Доступ к API: как подать заявку..................................................................................................18
Урок 4. Как получить OAuth-токен............................................................................................................22
Урок 5. Как включить Песочницу..............................................................................................................25
Урок 6. Как выполнить запрос к API.........................................................................................................28
Урок 7. Как получать данные через API..................................................................................................32
Урок 8. Как вносить изменения через API...............................................................................................38
Урок 9. Как перейти к реальной работе...................................................................................................42
Урок 10. Как использовать API эффективно: ограничения и рекомендации.........................................45
API версии 5. История изменений.........................................................................................49
О руководстве..........................................................................................................................57
Обзор API Директа версии 5.....................................................................................................................57
Структура API...................................................................................................................................58
Доступ к API.....................................................................................................................................58
Формат взаимодействия.................................................................................................................58
Варианты использования...........................................................................................................................58
Начните разрабатывать свое приложение...............................................................................................59
Регистрация приложения................................................................................................................59
Отладка на тестовых данных.........................................................................................................59
Переход к работе с данными реальных пользователей..............................................................60
Основные объекты.....................................................................................................................................60
Кампания (Campaign)......................................................................................................................61
Группа объявлений (AdGroup)........................................................................................................66
Объявление (Ad)..............................................................................................................................69
Набор быстрых ссылок (SitelinksSet).............................................................................................73
Визитка (VCard)................................................................................................................................74
Изображение (AdImage)..................................................................................................................74
Расширение (AdExtension)..............................................................................................................75
Креатив (Creative)............................................................................................................................76
Ключевая фраза (Keyword).............................................................................................................77
Ставка и приоритет (KeywordBid)..................................................................................................81
Корректировка ставок (BidModifier)................................................................................................82
Условие нацеливания на аудиторию (AudienceTarget).................................................................84
Условие ретаргетинга и подбора аудитории (RetargetingList).....................................................85
Условие нацеливания для динамических объявлений (DynamicTextAdTarget — Webpage).....90
Клиент (Client)..................................................................................................................................92
Общий счет (SharedAccount)..........................................................................................................93
Доступ и авторизация................................................................................................................................94
Регистрация приложения................................................................................................................94
Авторизационные токены................................................................................................................95
Роли и доступы пользователей Директа.......................................................................................96
Формат взаимодействия............................................................................................................................99
HTTP-заголовки................................................................................................................................99
Формат JSON.................................................................................................................................101
Протокол SOAP..............................................................................................................................102
Обработка ошибок.........................................................................................................................104
Ограничения, баллы.................................................................................................................................105
Технические ограничения.............................................................................................................105
Баллы..............................................................................................................................................105
Общие свойства методов API версии 5.................................................................................................108
Получение данных: метод get......................................................................................................108
Операции над массивом объектов..............................................................................................110
Редактирование отдельных параметров.....................................................................................112
Значение null (nil)...........................................................................................................................112
Практика использования..........................................................................................................................113
Ведение рекламной кампании......................................................................................................113
Минус-фразы..................................................................................................................................114
Автотаргетинг..................................................................................................................................114
Отслеживание изменений.............................................................................................................116
Статистика и аналитика................................................................................................................116
Как работать с медийными кампаниями.....................................................................................117
Как работать с динамическими объявлениями...........................................................................118
Рекомендации по созданию представителей..............................................................................120
Агентствам......................................................................................................................................120
Песочница..................................................................................................................................................121
Адрес Песочницы..........................................................................................................................122
Управление Песочницей...............................................................................................................122
Список терминов......................................................................................................................................124
О справочнике.......................................................................................................................125
AdExtensions..............................................................................................................................................126
add...................................................................................................................................................126
delete...............................................................................................................................................128
get....................................................................................................................................................129
AdGroups....................................................................................................................................................131
add...................................................................................................................................................131
delete...............................................................................................................................................137
get....................................................................................................................................................138
update..............................................................................................................................................145
AdImages....................................................................................................................................................148
add...................................................................................................................................................149
delete...............................................................................................................................................150
get....................................................................................................................................................151
Ads..............................................................................................................................................................153
add...................................................................................................................................................153
archive.............................................................................................................................................162
delete...............................................................................................................................................163
get....................................................................................................................................................164
moderate..........................................................................................................................................179
resume.............................................................................................................................................180
suspend...........................................................................................................................................181
unarchive.........................................................................................................................................182
update..............................................................................................................................................183
AgencyClients.............................................................................................................................................193
add...................................................................................................................................................194
get....................................................................................................................................................197
update..............................................................................................................................................201
AudienceTargets.........................................................................................................................................204
add...................................................................................................................................................204
delete...............................................................................................................................................207
get....................................................................................................................................................208
resume.............................................................................................................................................210
setBids.............................................................................................................................................211
suspend...........................................................................................................................................214
Bids.............................................................................................................................................................215
get....................................................................................................................................................215
set....................................................................................................................................................219
setAuto.............................................................................................................................................222
BidModifiers................................................................................................................................................228
add...................................................................................................................................................228
delete...............................................................................................................................................233
get....................................................................................................................................................234
set....................................................................................................................................................238
toggle...............................................................................................................................................239
Campaigns..................................................................................................................................................241
add...................................................................................................................................................241
archive.............................................................................................................................................268
delete...............................................................................................................................................269
get....................................................................................................................................................271
resume.............................................................................................................................................296
suspend...........................................................................................................................................297
unarchive.........................................................................................................................................299
update..............................................................................................................................................300
Changes.....................................................................................................................................................327
checkDictionaries.............................................................................................................................328
checkCampaigns.............................................................................................................................329
check................................................................................................................................................331
Clients.........................................................................................................................................................335
get....................................................................................................................................................335
update..............................................................................................................................................340
Creatives.....................................................................................................................................................343
get....................................................................................................................................................343
Dictionaries.................................................................................................................................................345
get....................................................................................................................................................345
DynamicTextAdTargets...............................................................................................................................351
add...................................................................................................................................................352
delete...............................................................................................................................................355
get....................................................................................................................................................356
resume.............................................................................................................................................358
setBids.............................................................................................................................................360
suspend...........................................................................................................................................362
KeywordBids...............................................................................................................................................363
get....................................................................................................................................................363
set....................................................................................................................................................366
setAuto.............................................................................................................................................369
Keywords....................................................................................................................................................373
add...................................................................................................................................................373
delete...............................................................................................................................................376
get....................................................................................................................................................377
resume.............................................................................................................................................380
suspend...........................................................................................................................................381
update..............................................................................................................................................382
KeywordsResearch.....................................................................................................................................384
deduplicate.......................................................................................................................................384
hasSearchVolume............................................................................................................................387
Leads..........................................................................................................................................................389
get....................................................................................................................................................389
RetargetingLists..........................................................................................................................................391
add...................................................................................................................................................391
delete...............................................................................................................................................393
get....................................................................................................................................................394
update..............................................................................................................................................397
Sitelinks......................................................................................................................................................400
add...................................................................................................................................................400
delete...............................................................................................................................................401
get....................................................................................................................................................403
VCards........................................................................................................................................................404
add...................................................................................................................................................404
delete...............................................................................................................................................409
get....................................................................................................................................................410
Ошибки и предупреждения......................................................................................................................414
Справочные данные.................................................................................................................................425
Типы стратегий...............................................................................................................................425
Настройки кампаний (параметр Option)......................................................................................426
Сервис Reports......................................................................................................................431
Как сформировать отчет..........................................................................................................................431
Период отчета................................................................................................................................432
Тип отчета.......................................................................................................................................433
Поля отчета....................................................................................................................................433
Вывод денежных значений...........................................................................................................434
Фильтрация данных.......................................................................................................................434
HTTP-заголовки.........................................................................................................................................437
Заголовки запроса.........................................................................................................................437
Заголовки ответа............................................................................................................................438
Запрос: спецификация отчета.................................................................................................................438
Допустимые поля...........................................................................................................................441
Несовместимые поля и зависимости..........................................................................................445
Содержание отчета..................................................................................................................................445
Онлайн- и офлайн-отчет..........................................................................................................................451
Выбор режима................................................................................................................................451
Как проверить готовность офлайн-отчета...................................................................................452
Как получить актуальную статистику......................................................................................................454
C помощью метода Changes.check..............................................................................................454
С помощью DateRangeType: AUTO.............................................................................................455
Коды ответов и ошибки...........................................................................................................................455
Ограничения..............................................................................................................................................456
Примеры....................................................................................................................................................457
Пример: клики и стоимость..........................................................................................................457
Пример: данные Яндекс.Метрики................................................................................................458
Примеры использования API Директа версии 5................................................................459
Примеры для утилиты cURL...................................................................................................................460
Настройка временного таргетинга...............................................................................................460
Изменение стратегии.....................................................................................................................461
Добавление метки в ссылку объявлений....................................................................................461
Остановка и запуск объявлений..................................................................................................462
Назначение ставок.........................................................................................................................463
Примеры на PHP версии 5......................................................................................................................463
Получение токена..........................................................................................................................464
Примеры на PHP для JSON.........................................................................................................466
Примеры на PHP для JSON.........................................................................................................470
Примеры на PHP для SOAP........................................................................................................477
Примеры на Python версии 2 или 3.......................................................................................................480
Получение токена..........................................................................................................................481
Примеры на Python для JSON.....................................................................................................483
Примеры на Python для SOAP.....................................................................................................493
Примеры на Python для XML.......................................................................................................496
О руководстве........................................................................................................................500
Что изменилось в версии 5.....................................................................................................................500
Адреса.............................................................................................................................................500
Заявка на доступ к API.................................................................................................................501
Авторизация...................................................................................................................................501
Работа с клиентами агентств.......................................................................................................501
Структура объектов.......................................................................................................................501
Принципы работы с данными.......................................................................................................501
Валюта............................................................................................................................................502
Технические ограничения.............................................................................................................502
Баллы..............................................................................................................................................502
Идентификатор запроса................................................................................................................502
Соответствие методов..............................................................................................................................502
Соответствие параметров........................................................................................................................507
Параметры кампаний....................................................................................................................507
Параметры групп и объявлений...................................................................................................510
Параметры фраз, ставки, цены позиций.....................................................................................511
Параметры визиток........................................................................................................................512
Статистика......................................................................................................................................513
Параметры ретаргетингов и условий ретаргетинга....................................................................515
Параметры клиентов.....................................................................................................................516
Пример: Reports вместо GetBannersStat (Live)......................................................................................517
О чем вы хотите спросить у службы поддержки?............................................................. 518
При вызове метода API Яндекс.Директа возникает ошибка................................................................522
Заявка на доступ......................................................................................................................................522
Ограничения при работе с API Яндекс.Директа....................................................................................523
Доступ к регистрации новых клиентов агентства через API................................................................523
Внести предложение или оставить отзыв.............................................................................................524
Другие вопросы по API Яндекс.Директа................................................................................................524
Индекс...................................................................................................................................................................525
Как начать работу с API: обучающий курс 8
Как начать работу с API: обучающий курс
В этом курсе вы научитесь работать с API Директа — даже с нуля. Вместе с нами вы пройдете все
подготовительные этапы: полýчите доступ к API и настроите тестовую среду. Мы расскажем, какие
возможности предоставляет API Директа, подробно рассмотрим структуру и основные параметры
запросов. Мы также предоставим множество примеров, которые вы сможете выполнить, используя ваш
язык программирования или утилиту cURL.
Урок 1. Что такое API Директа
В этом уроке мы расскажем, зачем Директу API, и познакомим вас с основными принципами работы.
Урок 2. Доступ к API: как зарегистрировать приложение на Яндекс.OAuth
В этом уроке мы расскажем о первом шаге получения доступа к API Директа для приложения —
о регистрации приложения на Яндекс.OAuth.
Урок 3. Доступ к API: как подать заявку
В этом уроке мы расскажем о втором шаге получения доступа к API Директа для приложения — подаче
заявки.
Урок 4. Как получить OAuth-токен
В этом уроке мы подробнее расскажем об OAuth-токенах, их получении и использовании.
Урок 5. Как включить Песочницу
В этом уроке мы расскажем, как научиться работать с Директом через API без риска запустить реальную
рекламную кампанию с настоящим бюджетом.
Урок 6. Как выполнить запрос к API
В этом уроке мы расскажем о форматах взаимодействия с API Директа и покажем, как выполнить первый
запрос.
Урок 7. Как получать данные через API
В этом уроке мы расскажем о структуре API и рассмотрим несколько примеров получения данных.
Урок 8. Как вносить изменения через API
В этом уроке мы расскажем, как редактировать данные с помощью API.
Урок 9. Как перейти к реальной работе
В это уроке мы расскажем, что нужно сделать, чтобы ваше приложение могло работать не только на
тестовой площадке, но и с реальными данными пользователей Директа.
Урок 10. Как использовать API эффективно: ограничения и рекомендации
В этом уроке мы расскажем, какие ограничения применяются в API Директа и как рационально
организовать работу приложения с учетом этих ограничений.
Урок 1. Что такое API Директа
В этом уроке вы узнаете:
API Яндекс.Директа. Версия 5
Как начать работу с API: обучающий курс 9
1. Что такое API
2. Для чего нужен API Директа
3. С чего начать
4. Объекты в веб-интерфейсе и в API
5. Задание
6. Как выглядит запрос к API
7. Полезные ссылки
8. Вопросы
В этом уроке мы расскажем, зачем Директу API, и познакомим вас с основными принципами работы.
Яндекс.Директ — это единая платформа для размещения контекстной и медийной рекламы. Директ
покажет объявления целевой аудитории вашего бизнеса, заинтересованной в ваших товарах или услугах.
Чтобы работать с Директом, достаточно открыть веб-интерфейс, создать аккаунт и разместить
объявления. В дальнейшем управлять рекламой в Директе можно не только в веб-интерфейсе, но и через
API.
Совет: Если вы еще не работали с Директом, рекомендуем предварительно пройти обучающий курс Как
разместить рекламу в Директе и ознакомиться с Помощью. Это позволит вам понять общие принципы
создания и ведения рекламных кампаний и лучше освоить наш курс по API.
Что такое API
API (англ. Application Programming Interface) — это интерфейс программирования приложений. API
сервиса предоставляет набор готовых процедур, функций и структур, с помощью которых разработчики
могут создавать свои программы, приложения, скрипты (далее — приложения) для работы с сервисом.
Другими словами, API — это конструктор, в котором есть набор деталей (функций, методов) и правил их
использования. Из этих деталей вы можете построить собственное приложение.
API Яндекс.Директа. Версия 5
Как начать работу с API: обучающий курс 10
При работе через API приложение отправляет запрос к сервису и получает ответ, содержащий
запрошенные данные. API предоставляет возможность автоматизировать процессы, аналогичные вашей
работе в веб-интерфейсе.
Для чего нужен API Директа
Используя API Директа, вы можете управлять теми же рекламными материалами, что и в веб-интерфейсе.
API позволяет автоматизировать рутинные операции, ускорить их выполнение и тем самым повысить
эффективность управления аккаунтом. API полезен для тех, кто работает с большими объемами данных,
не хочет зависеть от интерфейса в браузере и предпочитает тонкую настройку рекламы.
Вы можете создать приложение для решения своих задач — как независимый разработчик,
рекламодатель или рекламное агентство. Например, вы можете написать скрипт, который будет через
API автоматически обновлять ставки по вашему собственному алгоритму. Вы можете интегрировать
с Директом информационную систему вашей компании — загрузить в Директ большое количество
объявлений из вашей базы данных, автоматически обновлять тексты объявлений при изменении цены
товара, останавливать и возобновлять показы в зависимости от наличия товара на складе. Вы можете
API Яндекс.Директа. Версия 5
Description:В метод .get добавлена возможность получать количество показов и кликов по ключевой фразе за 28 дней. В метод .add добавлена возможность назначать ставку
