Table Of Content

API Яндекс.Директа Руководство разработчика 11.12.2013 API Яндекс.Директа. Руководство разработчика. Версия 4 Дата сборки документа: 11.12.2013. Этот документ является составной частью технической документации Яндекса. Сайт справки к сервисам Яндекса: http://help.yandex.ru © 2008—2013 ООО «ЯНДЕКС». Все права защищены. Предупреждение об исключительных правах Яндексу (а также указанному им правообладателю) принадлежат исключительные права на все результаты интеллектуальной деятельности и приравненные к ним средства индивидуализации, используемые при разработке, поддержке и эксплуатации сервиса API Яндекс.Директа. К таким результатам могут относиться, но не ограничиваясь указанными, программы для ЭВМ, базы данных, изображения, тексты, другие произведения, а также изобретения, полезные модели, товарные знаки, знаки обслуживания, коммерческие обозначения и фирменные наименования. Эти права охраняются в соответствии с Гражданским кодексом РФ и международным правом. Вы можете использовать сервис API Яндекс.Директа или его составные части только в рамках полномочий, предоставленных вам Пользовательским соглашением сервиса API Яндекс.Директа или специального соглашения. Нарушение требований по защите исключительных прав правообладателя влечет за собой дисциплинарную, гражданско-правовую, административную или уголовную ответственность в соответствии с российским законодательством. Контактная информация ООО «ЯНДЕКС» http://www.yandex.ru Тел.: +7 495 739 7000 Email: [email protected] Главный офис: 119021, Россия, г. Москва, ул. Льва Толстого, д. 16 Содержание Введение ............................................................................................................................................................................................. 7 Версии API ......................................................................................................................................................................................... 8 Версия Live 4 .............................................................................................................................................................................. 9 Версия 4 .................................................................................................................................................................................... 12 Версия 3 (отключена) .............................................................................................................................................................. 14 Версия 2 (отключена) .............................................................................................................................................................. 15 Версия 1 (отключена) .............................................................................................................................................................. 16 Доступ ............................................................................................................................................................................................... 17 Формат JSON ............................................................................................................................................................................ 17 Протокол SOAP ........................................................................................................................................................................ 19 Авторизационные токены ....................................................................................................................................................... 23 Цифровые сертификаты .......................................................................................................................................................... 23 Первоначальные сведения ........................................................................................................................................................... 26 Клиент (Client) ......................................................................................................................................................................... 27 Общий счет (Account) .............................................................................................................................................................. 28 Кампания (Campaign) ............................................................................................................................................................. 28 Группа объявлений (AdGroup) ............................................................................................................................................... 30 Объявление (Banner) ............................................................................................................................................................... 32 Фраза (Phrase) .......................................................................................................................................................................... 34 Ретаргетинг (Retargeting) ......................................................................................................................................................... 35 Изображение (AdImage) .......................................................................................................................................................... 37 Таргетинг .................................................................................................................................................................................. 37 Ставки и цены ........................................................................................................................................................................... 39 Стратегии показа ...................................................................................................................................................................... 41 Подбор ставок .......................................................................................................................................................................... 42 Статистика и аналитика ........................................................................................................................................................... 44 Метки объявлений ................................................................................................................................................................... 45 Финансовые операции ............................................................................................................................................................. 45 Практика использования ............................................................................................................................................................. 48 Ограничения на использование .............................................................................................................................................. 48 Ведение рекламных кампаний ................................................................................................................................................ 49 Создание и редактирование групп объявлений .................................................................................................................... 50 Изображения в объявлениях ................................................................................................................................................... 53 Получение статистики ............................................................................................................................................................. 54 Получение SSL-сертификата .................................................................................................................................................. 55 Доступ к финансовым методам .............................................................................................................................................. 58 Реальные валюты вместо у. е. ............................................................................................................................................. 60 Курсы валют и ограничения ........................................................................................................................................... 61 Поддержка валют в API версии Live 4 ........................................................................................................................... 62 Работа с общим счетом ............................................................................................................................................................ 66 Песочница ........................................................................................................................................................................................ 68 Адрес Песочницы ..................................................................................................................................................................... 68 Управление Песочницей ......................................................................................................................................................... 69 Особенности Песочницы ......................................................................................................................................................... 70 Методы ............................................................................................................................................................................................. 72 Кампании ................................................................................................................................................................................. 72 ArchiveCampaign .............................................................................................................................................................. 72 CreateOrUpdateCampaign ............................................................................................................................................. 73 CreateOrUpdateCampaign (Live) .............................................................................................................................. 81 DeleteCampaign ................................................................................................................................................................. 93 GetCampaignParams ...................................................................................................................................................... 94 GetCampaignParams (Live) ..................................................................................................................................... 100 API Яндекс.Директа Руководство разработчика Содержание 4 GetCampaignsList ......................................................................................................................................................... 111 GetCampaignsList (Live) ......................................................................................................................................... 113 GetCampaignsListFilter ................................................................................................................................................ 118 GetCampaignsListFilter (Live) ................................................................................................................................ 122 GetCampaignsParams ................................................................................................................................................... 129 GetCampaignsParams (Live) ................................................................................................................................... 135 ResumeCampaign ............................................................................................................................................................ 146 StopCampaign .................................................................................................................................................................. 147 UnArchiveCampaign ....................................................................................................................................................... 148 Объявления ........................................................................................................................................................................... 149 ArchiveBanners .............................................................................................................................................................. 149 ArchiveBanners (Live) ............................................................................................................................................. 150 CreateOrUpdateBanners .............................................................................................................................................. 152 CreateOrUpdateBanners (Live) ............................................................................................................................... 159 DeleteBanners ................................................................................................................................................................. 170 DeleteBanners (Live) ............................................................................................................................................... 171 GetBanners ..................................................................................................................................................................... 173 GetBanners (Live) .................................................................................................................................................... 183 GetBannerPhrases ......................................................................................................................................................... 197 GetBannerPhrases (Live) ......................................................................................................................................... 200 GetBannerPhrasesFilter ................................................................................................................................................ 204 GetBannerPhrasesFilter (Live) ................................................................................................................................ 208 ModerateBanners ........................................................................................................................................................... 214 ModerateBanners (Live) .......................................................................................................................................... 215 ResumeBanners .............................................................................................................................................................. 217 ResumeBanners (Live) ............................................................................................................................................. 218 StopBanners .................................................................................................................................................................... 220 StopBanners (Live) .................................................................................................................................................. 221 UnArchiveBanners ......................................................................................................................................................... 223 UnArchiveBanners (Live) ........................................................................................................................................ 224 Ставки .................................................................................................................................................................................... 226 SetAutoPrice ................................................................................................................................................................... 226 SetAutoPrice (Live) ................................................................................................................................................. 229 UpdatePrices ................................................................................................................................................................... 237 UpdatePrices (Live) ................................................................................................................................................. 239 Отчеты ................................................................................................................................................................................... 242 Статистика .................................................................................................................................................................... 242 GetBalance .............................................................................................................................................................. 242 GetBalance (Live) ............................................................................................................................................ 243 GetBannersStat (Live) ............................................................................................................................................. 245 GetSummaryStat .................................................................................................................................................... 249 GetSummaryStat (Live) ................................................................................................................................... 252 CreateNewReport .................................................................................................................................................. 256 CreateNewReport (Live) .................................................................................................................................. 263 DeleteReport ............................................................................................................................................................ 272 GetReportList ........................................................................................................................................................... 272 API Яндекс.Директа Руководство разработчика Содержание 5 Ключевые слова ........................................................................................................................................................... 274 CreateNewWordstatReport ...................................................................................................................................... 274 DeleteWordstatReport .............................................................................................................................................. 275 GetWordstatReport .................................................................................................................................................. 276 GetWordstatReportList ............................................................................................................................................ 277 GetKeywordsSuggestion .......................................................................................................................................... 278 Прогноз бюджета .......................................................................................................................................................... 280 CreateNewForecast ................................................................................................................................................ 280 CreateNewForecast (Live) ............................................................................................................................... 281 DeleteForecastReport ............................................................................................................................................... 284 GetForecast ............................................................................................................................................................. 284 GetForecast (Live) ........................................................................................................................................... 286 GetForecastList ........................................................................................................................................................ 290 Метки объявлений ............................................................................................................................................................... 291 GetBannersTags (Live) .................................................................................................................................................... 291 GetCampaignsTags (Live) ............................................................................................................................................... 292 UpdateBannersTags (Live) .............................................................................................................................................. 293 UpdateCampaignsTags (Live) ......................................................................................................................................... 295 Изображения в объявлениях .............................................................................................................................................. 298 AdImage (Live) ............................................................................................................................................................... 298 Upload ...................................................................................................................................................................... 298 CheckUploadStatus .................................................................................................................................................. 301 UploadRawData ....................................................................................................................................................... 303 Delete ....................................................................................................................................................................... 306 Get ............................................................................................................................................................................ 307 GetLimits ................................................................................................................................................................. 310 AdImageAssociation (Live) ........................................................................................................................................... 312 Get ............................................................................................................................................................................ 312 Set ............................................................................................................................................................................ 315 Ретаргетинг ........................................................................................................................................................................... 318 GetRetargetingGoals (Live) ............................................................................................................................................. 318 RetargetingCondition (Live) ......................................................................................................................................... 319 Add ........................................................................................................................................................................... 319 Update ...................................................................................................................................................................... 323 Delete ....................................................................................................................................................................... 327 Get ............................................................................................................................................................................ 329 Retargeting (Live) .......................................................................................................................................................... 332 Add ........................................................................................................................................................................... 332 Update ...................................................................................................................................................................... 336 Delete ....................................................................................................................................................................... 339 Get ............................................................................................................................................................................ 341 Финансовые операции ........................................................................................................................................................ 344 CreateInvoice .................................................................................................................................................................. 344 CreateInvoice (Live) ................................................................................................................................................ 346 GetCreditLimits ............................................................................................................................................................... 349 PayCampaigns ................................................................................................................................................................ 350 PayCampaigns (Live) ............................................................................................................................................... 352 TransferMoney ............................................................................................................................................................... 355 TransferMoney (Live) .............................................................................................................................................. 357 Общий счет ............................................................................................................................................................................ 360 API Яндекс.Директа Руководство разработчика Содержание 6 EnableSharedAccount (Live) ........................................................................................................................................... 360 AccountManagement (Live) .......................................................................................................................................... 361 Deposit ..................................................................................................................................................................... 362 Invoice ...................................................................................................................................................................... 365 TransferMoney ......................................................................................................................................................... 368 Get ............................................................................................................................................................................ 371 Update ...................................................................................................................................................................... 374 Клиенты ................................................................................................................................................................................. 378 CreateNewSubclient ...................................................................................................................................................... 378 CreateNewSubclient (Live) ..................................................................................................................................... 379 GetClientInfo .................................................................................................................................................................. 382 GetClientInfo (Live) ................................................................................................................................................ 384 GetClientsList ................................................................................................................................................................. 387 GetClientsList (Live) ............................................................................................................................................... 389 GetClientsUnits ................................................................................................................................................................ 393 GetSubClients .................................................................................................................................................................. 394 UpdateClientInfo .............................................................................................................................................................. 395 Прочие методы ..................................................................................................................................................................... 398 GetAvailableVersions ...................................................................................................................................................... 398 GetChanges ...................................................................................................................................................................... 398 GetEventsLog (Live) ....................................................................................................................................................... 404 GetRegions ...................................................................................................................................................................... 408 GetRegions (Live) .................................................................................................................................................... 409 GetRubrics ....................................................................................................................................................................... 410 GetStatGoals ................................................................................................................................................................... 411 GetStatGoals (Live) ................................................................................................................................................. 412 GetTimeZones .................................................................................................................................................................. 415 GetVersion ....................................................................................................................................................................... 416 PingAPI ............................................................................................................................................................................ 416 Коды ошибок и предупреждений ......................................................................................................................................... 417 Примеры приложений ................................................................................................................................................................ 422 Perl .......................................................................................................................................................................................... 422 SOAP::Lite ....................................................................................................................................................................... 422 JSON ................................................................................................................................................................................ 425 PHP .......................................................................................................................................................................................... 427 SOAP (класс NuSOAP) .................................................................................................................................................. 427 SOAP (класс SOAPClient) ............................................................................................................................................ 431 JSON ................................................................................................................................................................................ 435 Python ..................................................................................................................................................................................... 439 SOAP (библиотека Suds) ............................................................................................................................................... 439 JSON ................................................................................................................................................................................ 444 Работа с отчетами ................................................................................................................................................................ 447 Получение файла отчета ............................................................................................................................................... 447 Пример отчета о статистике кампании ........................................................................................................................ 448 C# ............................................................................................................................................................................................. 452 JSON ................................................................................................................................................................................ 452 API Яндекс.Директа Руководство разработчика Руководство разработчика 7 Введение В документе описан программный интерфейс сервиса Яндекс.Директ (далее — «API»). Через API внеш- ние приложения добавляют и редактируют кампании, объявления, фразы, задают ставки, получают ста- тистику показов. Документ адресован разработчикам приложений по управлению контекстной рекламой в Яндекс.Директе. Разделы документа: • Версии API — изменения в стабильной и развиваемой версии Live; • Доступ — взаимодействие с API в формате JSON и по протоколу SOAP, авторизация; • Первоначальные сведения — информационная модель и функции API; • Практика использования — инструкции по решению задач в API, ограничения на использование; • Песочница — тестовая среда для отладки приложений; • Методы — входные и результирующие данные, примеры вызова; • Примеры приложений — учебные приложения на Perl, PHP, Python. Предполагается, что читатель владеет терминологией и понимает принципы работы Яндекс.Директа. Эта информация содержится в справке сервиса. API Яндекс.Директа Руководство разработчика 8 Версии API Стабильные и развиваемые версии API. Стабильные версии API выпускаются один-два раза в год и после выпуска не меняются. На основе стабильной версии создается отдельная версия с обозначением «Live», например «Live 4». Ее развитие оперативно следует за новыми возможностями Яндекс.Директа, поэтому примерно раз в месяц в вер- сию Live вносятся изменения. Примечание: Переход со стабильной версии на Live безопасен, поскольку Live поддерживает форматы стабильной версии. После выпуска стабильной версии предыдущая стабильная версия остается доступной в течение не- скольких месяцев, а затем отключается вместе с версией Live. Метод GetAvailableVersions возвращает список поддерживаемых стабильных версий. Выбор между Live и стабильной версией В большинстве случаев рекомендуется использовать последнюю стабильную версию и переходить на нее с предыдущих версий. Версия Live предназначена для пользователей, которые заинтересованы в скорейшем получении новых возможностей Яндекс.Директа через API и могут адаптировать про- граммное обеспечение под меняющийся формат запросов и ответов. Переход со стабильной версии на Live не сложен, поскольку с версией Live можно взаимодействовать в формате стабильной версии. API автоматически определяет, на какую версию ориентирован клиент, и выбирает подходящий алгоритм обработки данных. Ответы версии Live имеют самый новый актуальный формат. Однако в Live строго соблюдается принцип «ответ понятен клиенту стабильной версии». Поэтому любые изменения в ответах Live дополняют фор- мат стабильной версии, но не нарушают его. Это гарантирует, что клиент стабильной версии получит ожидаемые параметры, хотя их значения могут быть ему не известны. Также в ответах Live могут при- сутствовать новые параметры, которые клиент стабильной версии может игнорировать. Рекомендации по использованию версии Live Источником информации об изменениях версии Live является новостная рассылка (подписка в интер- фейсе Яндекс.Директа на странице «Управление доступом к API Директа»). Ниже перечислены харак- терные изменения и даны рекомендации, повышающие адаптивность программ. Новое значение параметра Неизвестное значение может привести программу к неверной обработке данных. Рекомендуется за- кладывать в алгоритм проверку, которая в указанном случае прерывает обработку и уведомляет о но- вом значении. Новый параметр Если программа знакома с форматом Live, она корректно обрабатывает новые параметры, иначе про- пускает их. Игнорирование новых параметров не приводит к ошибкам, поскольку лишь выражает отказ от использования новых возможностей (они добавляются в версию Live таким образом, чтобы не повлиять на существующие функции). Если программа не указывает параметры версии Live в запросе, значит программа ориентирована на формат стабильной версии. В этом случае API не меняет параметры Live, если они были заданы, например, через веб-интерфейс. Однако если программа указывает одни параметры Live и не указы- вает другие, неуказанным параметрам могут быть присвоены предустановленные значения версии Live. Избежать сброса значений помогает техника, описанная в разделе Техника редактирования объектов. API Яндекс.Директа Руководство разработчика 9 Версия Live 4 Развиваемая версия на основе стабильной версии 4. Выпущена в январе 2012 г. Адрес для запросов в формате JSON: https://api.direct.yandex.ru/live/v4/json/ Адрес WSDL (для взаимодействия по протоколу SOAP): http://api.direct.yandex.ru/live/v4/wsdl/ Адрес для SOAP-запросов: https://api.direct.yandex.ru/live/v4/soap/ Новое в версии Live 4 Декабрь 2013 г. Добавлены методы работы с общим счетом (см. раздел Общий счет (Account)). Возможность подключить общий счет будет предоставлена в ближайшее время. Внимание! В методе SetAutoPrice (Live) входной параметр CampaignID станет обязательным. 5 декабря 2013 г. Метод CreateNewSubclient (Live) теперь позволяет агентствам, работающим в реальной валюте, соз- давать клиентов в валюте. Внимание! • В операциях Add, Delete и Update метода Retargeting (Live) добавлен входной параметр Login, обязательный при запросе от лица рекламного агентства. • Поместить кампанию в архив можно не ранее чем через час после последнего показа. 14 ноября 2013 г. Отключена поддержка рубрик Каталога: • Методы CreateOrUpdateBanners (Live), SetAutoPrice (Live) и UpdatePrices (Live) игнорируют входящие данные по рубрикам. Методы GetBanners (Live), GetBannerPhrases (Live) и GetBannerPhrasesFilter (Live) не возвращают рубрики. • Прогноз бюджета (методы CreateNewForecast (Live) и GetForecast (Live)) не формируется по рубрикам. • Методы GetBannersStat (Live) и CreateNewReport (Live) позволяют получать статистику по ранее использовавшимся рубрикам. Метод GetRubrics работает без изменений. API Яндекс.Директа Руководство разработчика 10 Внимание! В методе UpdatePrices (Live) входной параметр CampaignID стал обязательным. 31 октября 2013 г. • Добавлена поддержка групп объявлений (см. раздел Группа объявлений (AdGroup)). • При авторизации по OAuth-токенам не требуется указывать в запросе ключи login и application_id. • Добавлен параметр кампании ClickTrackingEnabled в методы CreateOrUpdateCampaign (Live), GetCampaignParams (Live), GetCampaignsParams (Live). 27 августа 2013 г. • Добавлена поддержка ведения рекламных кампаний в реальных валютах клиентов. Методы, в которые добавлены новые параметры, перечислены в разделе Реальные валюты вместо у. е. • Добавлено ограничение на длительность отчетного периода в методе CreateNewReport (Live). 24 июня 2013 г. • Добавлены методы AdImage (Live) и AdImageAssociation (Live), предназначенные для работы с изображениями (см. раздел Изображения в объявлениях). В методы GetBannersStat (Live) и CreateNewReport добавлена возможность получать в отчете данные о показе объявлений с изображениями и без. В метод GetBanners (Live) добавлен входной параметр StatusAdImageModerate и результирующие параметры StatusAdImageModerate, AdImageHash. 20 июня 2013 г. • Добавлена поддержка следующих подстановочных переменных в ссылке объявления: идентификатор рекламной кампании, идентификатор объявления, идентификатор ключевой фразы (см. подраздел Ссылки на сайт, а также раздел Учет параметров объявления в ссылке помощи Яндекс.Директа). Таким образом, появилась возможность анализировать статистику показов и кликов, конверсию и другие параметры визитов на сайт по каждой фразе в отдельности. 21 мая 2013 г. • Добавлены методы GetRetargetingGoals (Live), RetargetingCondition (Live), Retargeting (Live), предназначенные для настройки ретаргетинга (см. раздел Ретаргетинг (Retargeting)). API Яндекс.Директа Руководство разработчика