Live 4 version (deprecated)

Development version based on the stable version 4. Released in January, 2012.

Attention.

Use of the Live 4 version is restricted.

The following Live 4 methods have been disabled:

ArchiveBanners (Live) GetBanners (Live) ModerateBanners (Live)
ArchiveCampaign (Live) GetBannersStat (Live) ResumeBanners (Live)
CreateNewReport (Live) GetCampaignParams (Live) ResumeCampaign (Live)
CreateNewSubclient (Live) GetCampaignsList (Live) Retargeting (Live)
CreateOfflineReport (Live) GetCampaignsListFilter (Live) RetargetingCondition (Live)
CreateOrUpdateBanners (Live) GetCampaignsParams (Live) SetAutoPrice (Live)
CreateOrUpdateCampaign (Live) GetChanges (Live) StopBanners (Live)
DeleteBanners (Live) GetClientInfo (Live) StopCampaign (Live)
DeleteCampaign (Live) GetClientsList (Live) UnArchiveBanners (Live)
DeleteOfflineReport (Live) GetOfflineReportList (Live) UnArchiveCampaign (Live)
DeleteReport GetReportList UpdateClientInfo (Live)
GetBalance (Live) GetSubClients UpdatePrices (Live)
GetBannerPhrases (Live) GetSummaryStat (Live)
GetBannerPhrasesFilter (Live) Keyword (Live)

For information about the compatibility of methods between versions Live 4 and 5, see the Migration guide.

Address for requests in JSON format:

https://api.direct.yandex.ru/live/v4/json/

Address of the WSDL (for using the SOAP protocol):

https://api.direct.yandex.ru/live/v4/wsdl/

Address for SOAP requests:

https://api.direct.yandex.ru/live/v4/soap/

New in the Live 4 version

December 10, 2018

Changes in the reference list of regions: the parent region of the Zabaykalsky Krai administrative area and the Republic of Buryatia is now the Far Eastern Federal District (Dalny Vostok), instead of Siberia.

We recommend calling the GetRegions (Live) method to get an updated list of regions.

December 4, 2018

There are upcoming changes in the reference list of regions: the parent region of the Zabaykalsky administrative area and the Republic of Buryatia will be the Far Eastern Federal District (Dalny Vostok), instead of Siberia.

After the reference list is updated, we recommend calling the GetRegions (Live) method to request the new list.

December 3, 2018

Disabled the ability to pass monetary values in units via the API for campaigns and advertisers that use a real currency.

The Currency input parameter is now required in the following methods:

The Currency input parameter is required in the following methods in order to obtain statistics for campaigns that use a real currency:

The Currency value must match the campaign or advertiser's currency for all methods except CreateNewForecast (Live) and GetEventsLog (Live).

There is an additional restriction for the GetSummaryStat (Live) method: all campaigns specified in a single method call must be in the same currency.

October 17, 2017

The CreateNewReport (Live) and GetBannersStat (Live) methods now allow you to receive report data on impressions for auto-targeting.

October 9, 2017
The AccountManagement (Live) method now supports a daily limit on the shared account: the input parameters AccountDayBudget, PausedByDayBudgetSms (nested in SmsNotification), PausedByDayBudget (nested in EmailNotification) for the Update operation, and the same output parameters for the Get operation.
July 4, 2017

For the CreateNewReport (Live) and GetBannersStat (Live) methods, the report can now include data about impressions for video ads.

March 22, 2017

Changed the amounts of the minimum payment and the minimum transfer between campaigns.

February 14, 2017

The CreateNewWordstatReportand CreateNewForecast (Live) methods now support negative keywords that contain up to 7 words in the Phrases parameter.

November 1, 2016

Added support for a new currency: the Belarusian ruble (BYN).

October 17, 2016
Attention.

Account access may be suspended for advertisers using Yandex units who haven't made payments for over a year. In this case, calling API methods results in the error 54, and the web interface doesn't allow access to any operations except switching to a currency.

To continue using the API, you need to switch your account to a payment currency. To do this, click Switch now in the Yandex.Direct web interface. For more information about switching to a currency, see the Help for Yandex.Direct: Russian rubles or other currency.

October 13, 2016

Changes in the reference list of regions. We recommend calling the GetRegions (Live) method to get an updated list of regions.

In particular, the regions listed below have been removed from the list:
  • These regions can no longer be used when creating or editing ad groups.

  • In groups that used these regions, they have been automatically replaced with lower-level regions.

  • Statistics for these regions have been moved to higher-level regions.

List of deleted regions
Deleted region Replaced by regions in the group settings Statistics moved to the region
ID Region name (with higher levels)
20524 West/Ukraine/CIS (excluding Russia) 20529, 20530, 20531, 20532, 20533, 20534, 20535, 20550 187
20525 East/Ukraine/CIS (excluding Russia) 20536, 20537, 20538, 20539, 20540 187
20526 South/Ukraine/CIS (excluding Russia) 20541, 20542, 20543 187
20527 Central/Ukraine/CIS (excluding Russia) 20544, 20545, 20546, 20547, 20548, 20549 187
20528 North/Ukraine/CIS (excluding Russia) 20551, 20552 187
980 Baltic States/Europe 117, 179, 206 111
1004 Middle East/Asia 181, 210, 1056 183
October 12, 2016

Added a restriction for keywords: the maximum length of each word or negative keyword in a keyword is 35 characters.

October 10, 2016
Attention. As of October 10, 2016, advertising agencies can only register clients who are using a real currency. Registration of clients who use Yandex units has been disabled. Accordingly, the logic of the CreateNewSubclient (Live) method has changed. Details
October 3, 2016

In statistics provided by methods GetBannersStat (Live) and CreateNewReport (Live), the period for which data is available for the average position of the ad and the type of device is changed. Data is now available beginning from November 1, 2014.

September 21, 2016
Attention. In one week, there will be a new range of dates for the availability of average ad position statistics generated by the CreateNewReport (Live) method. The data on the average position will be available starting from November 1, 2014. Data is currently available starting from July 1, 2014. If you need average position statistics for the period from July 1, 2014 to October 31, 2014, we recommend that you request it within the next few days.
September 20, 2016

Changes will be made to the regions reference list in approximately two to three weeks. After the reference list is updated, we recommend calling the GetRegions (Live) method to request the new list.

In particular, the regions listed below will be removed from the list:
  • You won't be able to specify these regions when creating or editing ad groups.

  • In groups that use these regions, they will be automatically replaced with lower-level regions.

  • Statistics for these regions will be moved to higher-level regions.

List of regions planned for deletion
Region to be deleted To be replaced by regions in the group settings Statistics will be moved to the region
ID Region name (with higher levels)
20524 West/Ukraine/CIS (excluding Russia) 20529, 20530, 20531, 20532, 20533, 20534, 20535, 20550 187
20525 East/Ukraine/CIS (excluding Russia) 20536, 20537, 20538, 20539, 20540 187
20526 South/Ukraine/CIS (excluding Russia) 20541, 20542, 20543 187
20527 Central/Ukraine/CIS (excluding Russia) 20544, 20545, 20546, 20547, 20548, 20549 187
20528 North/Ukraine/CIS (excluding Russia) 20551, 20552 187
980 Baltic States/Europe 117, 179, 206 111
1004 Middle East/Asia 181, 210, 1056 183
September 8, 2016

You can now use the CreateNewReport (Live) method to get report data on a retargeting condition used for applying a bid adjustment for site users (see Корректировка ставок (BidModifier) in the API version 5 documentation).

September 8, 2016

The GetBanners (Live) method has the new value "project_declaration" for the AdWarnings output parameter.

August 30, 2016
Attention. Statistics provided by the GetSummaryStat (Live) and GetBannersStat (Live), CreateNewReport (Live) methods are available for the three years prior to the current month. For example, on September 15, 2016, you can get data starting from September 1, 2013.
August 29, 2016

Daily budget settings are available to all clients with campaign editing rights.

June 29, 2016

The RetargetingCondition (Live) and GetRetargetingGoals (Live) methods now support Yandex.Audience segments. The GetRetargetingGoals (Live) method has the new "audience_segment" value for the Type output parameter.

June 23, 2016

The RetargetingCondition (Live) method can now work with retargeting conditions consisting of just a group of goals with the "not" type. These types of retargeting conditions can only be used in bid adjustments (see Корректировка ставок (BidModifier) in the documentation for version 5 of the API). Creating retargetings with these types of conditions is not allowed.

April 26, 2016

The Time parameter for a retargeting condition now supports values from 1 to 90.

April 25, 2016
Attention.

Introduced changes in data structures: types changed for BannerID, BannerIDS, Banner, Banners, AdID,AdIDS, and AdGroupID. Details

April 14, 2016

Disabled uploading for images sized 150 pixels on the shortest side, and assigning such images to ads.

March 30, 2016

The DisabledDomains campaign parameter now supports ad exchanges (SSPs).

March 24, 2016

For theGetWordstatReportList method, added the Failed value for the StatusReport output parameter.

For the GetForecastList method, added the Failed value for the StatusForecast output parameter.

March 14, 2016

The RelevantPhrasesBudgetLimit campaign parameter no longer supports the value –1. To allow unlimited spending on related keywords (within the campaign budget), use the value 100.

February 29, 2016
Changed the requirements for the size of images in ads:
  • When the aspect ratio is from 1:1 to 3:4/4:3 — from 450 to 5000 pixels on a side.

  • When the aspect ratio is 16:9, each side must be from 1080 × 607 to 5000 × 2812 pixels long.

Attention. Support for uploading the previous size of images (150 pixels on the shortest side) will be continued for a month.
February 9, 2016

Changed the restrictions for keywords. Now an ad group can contain a maximum of 200 keywords, and the maximum length of each keyword is 4096 characters.

December 15, 2015

Added the ability to get statistics on dynamic text ads (see Dynamic ads in the Help for Yandex.Direct):

November 9, 2015

The GetBanners (Live), GetBannerPhrases (Live) andGetBannerPhrasesFilter (Live) methods return restrictions on getting auction results. Details

The CreateNewReport (Live) method now allows you to get report data on the type of OS and connection (only for mobile app ads).

October 22, 2015
Attention.

Beginning October 22, 2015, creating new SSL certificates is no longer available. Certificates created earlier can be used until they expire.

September 30, 2015
The SetAutoPrice (Live) method now allows calculating bids for search based on the minimum bid for second position in Premium Placement.
September 8, 2015
September 1, 2015
July 30, 2015
The Yandex.Direct API will have a new feature for getting bidding results for a new auction: the minimum bid for each position and the actual CPC for each position. Details
July 6, 2015
In the methods CreateNewReport (Live) and GetBannersStat (Live) added the ability to receive in the report data about the display of auto-targeting.
June 29, 2015
Added the OverdraftSumAvailableInCurrency output parameter to the GetClientInfo (Live) andGetClientsList (Live) methods.
June 9, 2015
The RetargetingCondition (Live) and GetRetargetingGoals (Live) methods now support Yandex.Audience segments. Added the Type parameter to the GetRetargetingGoals (Live) method.
May 27, 2015
May 20, 2015
The ROIOptimization bid management strategy is available (see the StrategyName parameter in the CampaignStrategy object).
April 15, 2015
Added the EnableRelatedKeywords campaign parameter to the methods CreateOrUpdateCampaign (Live), GetCampaignParams (Live), GetCampaignsParams (Live), GetCampaignsList (Live), GetCampaignsListFilter (Live).
April 3, 2015
Added the Limit and Offset input parameters to the GetEventsLog (Live) method.
March 23, 2015
TheGetBannersStat (Live) method has an added feature for including the average position of ad displays and the average position of ad clicks in the report. Data is available starting from December 4, 2014.
March 3, 2015
In the methods CreateNewReport (Live) and GetBannersStat (Live) added the ability to receive in the report data about the display of auto-targeting.
Added a coefficient for setting bids on mobile devices:
February 26, 2015
Added the Get operation to the Keyword (Live) method for getting keyword productivity values.

AutoBroker is always on for all keywords. Disabling AutoBroker is not supported.

February 11, 2015
Added the AdGroupID output parameter for the Get operation of the Retargeting (Live) method.
January 29, 2015
Added a limitation for the CreateOrUpdateBanners (Live) method: no more than 1000 ads per call.
January 20, 2015
Attention.

All interaction with the API, including getting WSDL descriptions, is performed over the HTTPS protocol. HTTP access is forbidden.

December 17, 2014
Added the DisplayStoreRating client parameter to the GetClientInfo (Live) and UpdateClientInfo (Live) methods.
October 9, 2014
TheCreateNewReport (Live) method has an added feature for including the average position of ad displays and the average position of ad clicks in the report.
September 18, 2014
Changed the behavior of the SetAutoPrice (Live) method: now the method does not consider ad activity when updating bids. The BannersType input parameter is ignored.
August 27, 2014
The CreateNewReport (Live) method has the added ability to get the number of goal visits (conversions) in the report.
July 24, 2014
April 10, 2014

Added the Keyword (Live) method for stopping and restarting displays for keywords.

April 1, 2014
Attention.

On April 1, 2014, changes were made in data structures: the parameter types were changed for PhraseID and PhraseIDS. Details

March 17, 2014
Changes in working with sitelinks: the CreateOrUpdateBanners (Live) method now accepts input of 1 to 4 sitelinks in the Sitelinks array, and the GetBanners (Live) method returns from 1 to 4 sitelinks in the Sitelinks array.
February 27, 2014
Attention. In the SetAutoPrice (Live) method, the CampaignID input parameter is now mandatory.
February 19, 2014
The AverageCPAOptimization bid management strategy is available (see the StrategyName parameter in the CampaignStrategy object).
January 27, 2014

Added methods for working with the shared account (see the section Shared account (Account)).

December 5, 2013

The CreateNewSubclient (Live) method now allows agencies that are using a real currency to create clients in this currency.

Attention.
  • In the actions for the Retargeting (Live) method, the new Login input parameter is mandatory for requests on behalf of an advertising agency.
  • A campaign can be archived no sooner than one hour after the last impression.
November 14, 2013

Discontinued support for Catalog categories:

Attention. In the UpdatePrices (Live) method, the CampaignID input parameter is now mandatory.
October 31, 2013
August 27, 2013
June 24, 2013
June 20, 2013
  • Added support for the following substitution variables in an ad link: the campaign ID, the ad ID, and the keyword ID (see the section Site links, as well as the section Transferring ad data in URLs in the Help for Yandex.Direct). This makes it possible to analyze statistics for impressions and clicks, conversions, and other site visit data separately for each keyword.
May 21, 2013
February 10, 2013
December 17, 2012
November 7, 2012
September 5, 2012
June 9, 2012
April 19, 2012
March 6, 2012

Recommendations for using the Live version

Here we list typical changes and recommendations for improving program adaptability.

New parameter value

An unfamiliar value may cause a program to process data incorrectly. We recommend putting a check in the algorithm that will cancel processing in this case and provide notification of the new value.

New parameter

If the program is familiar with the Live format, it will correctly handle new parameters; otherwise, it ignores them. Ignoring new parameters does not lead to errors, since it is only a refusal to use new features (they are added to the Live version in a way that does not affect existing functions).

If the program does not specify Live version parameters in a request, it means the program is set up to use the stable version format. In this case, the API does not change Live parameters, for example, if they were set via the web interface. However, if the program specifies some of the Live parameters and not others, the predefined values for the Live version may be assigned to the omitted parameters. To avoid having values reset, we recommend using the technique described in the section How to edit objects.