Live 4 version (deprecated)
Development version based on the stable version 4. Released in January, 2012.
Use of the Live 4 version is restricted.
The following Live 4 methods have been disabled:
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.
- 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 regionsDeleted 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 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 deletionRegion 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 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):
Added the CreateOfflineReport (Live), DeleteOfflineReport (Live), and GetOfflineReportList (Live) methods for getting reports on dynamic text ads.
The CreateNewReport (Live) and GetBannersStat (Live) methods now have the ability to get report data on targeting conditions for dynamic text ads.
- 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
-
TheCreateNewReport (Live) method now allows getting the user age group and gender in the report.
Fixed the default behavior for the methods CreateNewReport (Live), GetBannersStat (Live), and GetSummaryStat (Live): if the client uses a real currency and the Currency parameter was omitted, the report will show the CPC before applying the discount, converted from the currency to Yandex units.
- September 1, 2015
-
It is now possible to get bidding results for a new auction: the minimum bid for each position and the actual CPC for each position.
Added the AuctionBids input parameter to the GetBanners (Live) method. If this parameter is set to Yes, the method returns the AuctionBids array.
GetBannerPhrasesFilter (Live)returns the AuctionBids array if the FieldsNames parameter is set to the value "AuctionBids".
Added the AuctionBids input parameter to the CreateNewForecast (Live) method. If this parameter is set to Yes, the report returned by the GetForecast (Live) method will contain the AuctionBids array.
- Added the MaintainNetworkCPC campaign parameter to the methods CreateOrUpdateCampaign (Live), GetCampaignParams (Live), and GetCampaignsParams (Live).
- 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
-
- Added support for mobile ads: the Type ad parameter in the CreateOrUpdateBanners (Live) and GetBanners (Live). methods.
- Added the ExtendedAdTitleEnabled campaign parameter to the methodsCreateOrUpdateCampaign (Live), GetCampaignParams (Live), GetCampaignsParams (Live), GetCampaignsList (Live), andGetCampaignsListFilter (Live).
- 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.
- February 26, 2015
- Added the Get operation to the Keyword (Live) method for getting keyword productivity values.
- 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
-
- Introduced the procedure for registering applications.
- Established requirements for applications that access the API.
- 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
- 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:
- The CreateOrUpdateBanners (Live), SetAutoPrice (Live), and UpdatePrices (Live) methods ignore input data on categories. The GetBanners (Live), GetBannerPhrases (Live) andGetBannerPhrasesFilter (Live) methods do not return categories.
- The budget forecast (CreateNewForecast (Live) and GetForecast (Live) methods) is not generated for categories.
- The GetBannersStat (Live) and CreateNewReport (Live) methods allow getting statistics for previously used categories. The GetRubrics method works the same way as previously.
- October 31, 2013
-
- Added support for groups of ads (see the section Ad group).
- When using OAuth tokens, it is not necessary to specify the login and application_id keys in the request.
- Added the ClickTrackingEnabled campaign parameter to the methods CreateOrUpdateCampaign (Live), GetCampaignParams (Live), and GetCampaignsParams (Live).
- August 27, 2013
-
- Added support for running advertising campaigns in clients' actual currencies. The methods that have the new parameters added are listed in the section Real currencies instead of Yandex units.
- Added a restriction on the duration of the report period in the CreateNewReport (Live) method.
- June 24, 2013
-
Added the AdImage (Live) and AdImageAssociation (Live) methods for working with images (see the section Images in ads).
For the GetBannersStat (Live) and CreateNewReport methods, the report can now contain data about ad impressions with images and without images.
For the GetBanners (Live) method, added the input parameter StatusAdImageModerate and the output parameters StatusAdImageModerate and AdImageHash.
- 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
-
Added the GetRetargetingGoals (Live), RetargetingCondition (Live), and Retargeting (Live) methods for setting up retargeting (see the section Retargeting).
For the GetBannersStat (Live) and CreateNewReport methods, report output can now include data about impressions for retargeting conditions.
- Added the parameter DontWaitForPriceUpdate to the SetAutoPrice (Live) method. Now the method can be called asynchronously.
- February 10, 2013
-
- Added the GetBannersStat (Live) method. Recommended to use for getting statistics, instead of generating a report using the CreateNewReport method.
- Added the AdditionalMetrikaCounters campaign parameter to the methods CreateOrUpdateCampaign (Live), GetCampaignParams (Live), and GetCampaignsParams (Live).
In the ModerateBanners (Live) method, it is sufficient to set either one of the parameters CampaignID or BannerIDS.
The input parameter CampaignID can be omitted in the StopBanners (Live), ResumeBanners (Live), ArchiveBanners (Live), UnArchiveBanners (Live), DeleteBanners (Live) methods.
- December 17, 2012
-
- Added the parameters BannerIDS, PhraseIDS, BannersType, Price, and ContextPrice to the SetAutoPrice (Live) method. Now this method can set bids separately for the search and the Yandex Advertising Network.
- Added the AgeLabel parameter to the GetBanners (Live) and CreateOrUpdateBanners (Live) methods. This makes it possible to set an age category for informational products, as required by the federal law “About advertising” of the Russian Federation.
- November 7, 2012
-
Removed the limit on the number of withdrawals from a campaign using the TransferMoney method. As previously, there is a limitation on adding funds to a campaign — no more than 30 times per day.
Added the StatusPaused, ContextClicks, and ContextShows output parameters in the methods GetBanners (Live), GetBannerPhrases (Live), and GetBannerPhrasesFilter (Live).
- September 5, 2012
-
- Added the FieldsNames input parameter to the GetBanners (Live) method.
- In the response for the SetAutoPrice method, the AutoBudgetPriority parameter was removed.
- Added the WithTextDescription input parameter and the TextDescription output parameter to the GetEventsLog (Live) method.
- June 9, 2012
-
Added the methods GetCampaignsTags, UpdateCampaignsTags, GetBannersTags, and UpdateBannersTags, which are used for assigning tags to ads (see Ad tags).
For the GetBanners method, added the input parameters Tag and TagIDS for filtering ads by tags and tag IDs.
Direct clients can pay for campaigns by overdraft (see the PayMethod parameter in the PayCampaigns method). The available overdraft amount is returned by the GetClientInfo method (OverdraftSumAvailable parameter).
- April 19, 2012
-
- Automatic strategies for managing bids are available for the Yandex Advertising Network (see the StrategyName parameter in the CampaignContextStrategy object).
- Added the AutoMinusWords parameter in the CreateOrUpdateBanners (Live) method.
- March 6, 2012
-
- The report on campaign statistics includes the phrase_id keyword IDs (see Sample report).
New GetEventsLog (Live) method.
The methods GetCampaignsListFilter (Live) and GetBanners (Live). Added the Limit and Offset parameters for paginated selection from the database.
The GetStatGoals (Live) method. Added output parameters AvailableForStrategy and AvailableForContextStrategy.
The CreateOrUpdateCampaign (Live) method. Added the ContextStrategy input parameter, which sets the display strategy in the Yandex Advertising Network. The ContextLimit, ContextLimitSum and ContextPricePercent parameters moved under the ContextStrategy parameter.
Added the BidCoefs parameter to the time targeting settings; use this parameter to lower the CPC during certain time periods. Also added the parameter WorkingHolidays.
The GetCampaignParams (Live) and GetCampaignsParams (Live) methods return the ContextStrategy and BidCoefs parameters.
The methods GetCampaignsList (Live) and GetCampaignsListFilter (Live). Added output parameters StrategyName and ContextStrategyName.
The GetRegions (Live) method. Added the RegionType parameter.
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.