API version 5. Changelog

December 10, 2018

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

We recommend calling the Dictionaries.get method to get an updated list of regions.

December 6, 2018
The Dictionaries.get method no longer supports units.
  • The YND_FIXED currency has been removed from the Currencies list.
  • For other currencies, the Rate and RateWithVAT parameters are no longer returned.
December 4, 2018

There are upcoming changes in the reference list of regions: the parent region of the Zabaykalsky Krai 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 Dictionaries.get method to request the new list.

November 26, 2018
The KeywordsResearch.deduplicate method has a new Operation input parameter. Now you can remove duplicates and overlapping keywords at the same time or in separate operations.
November 12, 2018
The currency reference now shows the minimum and maximum CPM bids for display ads. To get the reference list, use the Dictionaries.get method and specify the Currencies dictionary name in the request.
November 2, 2018

Crypta segments are available for behavioral targeting of display advertising:

  • The RetargetingLists service supports using behavioral segments in audience targets based on user profiles.
  • The Dictionaries.get method returns behavioral characteristics in the AudienceCriteriaTypes reference list and behavioral segments in the AudienceDemographicProfiles reference list.
November 1, 2018
Added restriction: in an “Ads for mobile apps” campaign, all ad groups must have the same app link.
October 3, 2018
Added the Creatives service to get creatives designed in the Ad Builder that are available to the advertiser.
October 3, 2018
Added support for video ads in the Ads service. More about ad types
October 1, 2018
Added the KeywordsResearch.deduplicate method, which detects overlapping and duplicated terms in an array of keywords.
September 26, 2018

The following is now available for display campaigns in the API:

  • The Campaigns service now supports campaigns with the CPM_BANNER_CAMPAIGN type.
  • The AdGroups service now supports ad groups with the CPM_BANNER_AD_GROUP type.
  • The Ads service now supports ads with the CPM_BANNER_AD type.
  • The RetargetingLists service now supports user profiles; see the section Retargeting list (RetargetingList).
  • Now you can use the Dictionaries.get method to obtain reference lists of Crypta segments:
    • list of demographic segments: gender, age, income, family status and profession
    • list of demographic characteristics
    • list of user interest segments

Learn more about managing display campaigns

August 27, 2018

Changed restrictions: the maximum number of gender and age adjustments per campaign or ad group has been increased to 12.

August 21, 2018

The BidModifiers and Reports services now support the age groups AGE_45_54 and AGE_55.

August 8, 2018

The Reports service has the new fields AvgTrafficVolume, WeightedCtr, and WeightedImpressions.

June 8, 2018

The Reports service has the new input parameters Goals and AttributionModels.

Changed how the value of the ConversionRate field is calculated: the number of converted sessions is now divided by the number of clicks instead of the total number of sessions.

May 30, 2018
The new KeywordBids.setAuto method allows you to set bids for keywords on search depending on the desired traffic volume.
May 3, 2018

The Reports service now returns statistics for “Display campaigns”:

April 10, 2018

Added the KeywordBids service for managing bids and priorities of keywords and autotargetings.

April 9, 2018

The Keywords.get method no longer allows getting the Productivity parameter: it always returns null (nil).

The Dictionaries.get method no longer allows getting the list of recommendations for improving productivity: the ProductivityAssertions array is not returned.

Disabled support for the IMPRESSIONS_BELOW_SEARCH strategy (for all types of campaigns) in the Campaigns service. If you pass this value in the BiddingStrategyType parameter for the Search structure, an error is returned.

March 19, 2018

Added the Leads service for getting data that users enter in forms on turbo pages.

February 26, 2018
The BidModifiers service now supports video bid adjustments. More information about bid adjustments
February 8, 2018
In the Reports service, added the values SMART_MULTIPLE and SMART_SINGLE for the AdFormat field.
January 29, 2018

Added the CriterionType field in the Reports service.

January 10, 2018

The Clients.get method now allows you to get agency parameters and user settings for the agency's representative.

December 13, 2017

The Ads service now supports image ads that use creatives created in the Ad Builder. More about ad types

November 27, 2017
Changed the amount of points deducted for calling the Bids.get and Keywords.get methods. More information about points
November 13, 2017

Changed the errors that are returned when the request can't be processed. Instead of error code 53, the following error codes are returned:

  • If the OAuth token is omitted in the request or has an invalid format (for example, it contains invalid characters), error code 8000 is returned.

    Note. If the OAuth token is invalid, it returns error code 53 as previously.
  • If a request on behalf of an agency representative omits the advertiser's username, error code 8000 is returned.

  • If the Client-Login header specifies a non-existing username or a username for an advertiser that doesn't belong to this agency, error code 8800 is returned.

  • If the user doesn't have access to the Yandex.Direct API, error code 3000 is returned.

October 17, 2017
Added support for autotargeting in the Bids, KeywordsandReports services. More information
September 27, 2017

The Reports service now has the reportsInQueue response header and filtration by the CampaignType field.

September 19, 2017

Added the campaign setting ENABLE_COMPANY_INFO to methods for theCampaigns service (for campaigns with the “Text & Image Ads” and “Dynamic ads” types).

September 11, 2017

The Campaigns service has disabled support for the ENABLE_BEHAVIORAL_TARGETING setting in the Settings structure.

August 29, 2017
Added support for JSON requests in the Reports service.
August 29, 2017

Added the AgencyClients.add method for registering new agency clients and the AgencyClients.update method for editing parameters of agency clients.

Added the Clients.update method for editing advertiser parameters and user settings for an advertiser's representative.

August 15, 2017

In the Ads service, added the Title2 parameter for text and image ads.

Changed the restrictions on the number of characters in the Title and Text fields for text and image ads, and in the Text field for dynamic ads.

Changes in the reference list of restrictions. We recommend getting the updated list by calling the Dictionaries.get method with the Constants reference list specified in the request.

August 7, 2017

A report with the SEARCH_QUERY_PERFORMANCE_REPORT type now contains statistics on search queries not only in Yandex search, but also in search engines in the Yandex Advertising Network. This type of report also supports the Placement field now.

August 7, 2017

The Campaigns service has disabled support for the ENABLE_AUTOFOCUS setting in the Settings structure.

July 4, 2017

Video extensions now supported for text and image ads:

For more information about how to assign and unassign video extensions, see the section Adding vCards, images, sitelinks, callouts, and video extensions.

June 28, 2017

Disabled support for the LOWEST_COST, LOWEST_COST_GUARANTEE, and LOWEST_COST_PREMIUM strategies in the Campaigns service (for all types of campaigns). If you pass one of these values in the BiddingStrategyType parameter for the Search structure, an error is returned.

Changes to settings in the Campaigns service for impressions for related keywords in “Text & Image Ads” campaigns:

  • The BudgetPercent parameter in the RelevantKeywords structure supports any integer values from 1 to 100.

  • The Mode parameter in the RelevantKeywords structure is not supported and its value is ignored.

  • The ENABLE_RELATED_KEYWORDS setting in the Settings structure is not supported.

The Reports service has the new fields MatchedKeyword, Criterion, and CriterionId.

June 20, 2017

Support for the 4th position in premium placement has been added to the Bids service: the P14 value in the Position parameter of the AuctionBids array, returned via the Bids.get method, as well as the query parameter Position of the Bids.setAuto method.

May 3, 2017

The BidModifiers service now supports regional bid adjustments. More information about bid adjustments

April 17, 2017
Added the KeywordsResearch service for getting a forecast of impressions for keywords.
April 17, 2017

Added the RestrictedRegionIds response parameter to the AdGroups.get method.

March 21, 2017
Added the Reports service for getting statistics.
March 6, 2017

Added the AgencyClients service for managing agency clients.

February 28, 2017

You can now target mobile app ads by user interests (see Targeting by mobile app interests):

February 14, 2017

Added support for negative keywords containing up to 7 words:

January 25, 2017
December 26, 2016

The ContextCoverage array in the Bids.get method is unavailable for campaigns with the SERVING_OFF or NETWORK_DEFAULT display strategy.

November 9, 2016

Added the Clients service for getting client information.

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

The methods for the Ads service have an extended set of possible values for the Action parameter (for mobile app ads).

October 13, 2016

Changes in the reference list of regions. We recommend calling the Dictionaries.get 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 regionReplaced by regions in the group settingsStatistics moved to the region
IDRegion name (with higher levels)
20524West/Ukraine/CIS (excluding Russia)20529, 20530, 20531, 20532, 20533, 20534, 20535, 20550187
20525East/Ukraine/CIS (excluding Russia)20536, 20537, 20538, 20539, 20540187
20526South/Ukraine/CIS (excluding Russia)20541, 20542, 20543187
20527Central/Ukraine/CIS (excluding Russia)20544, 20545, 20546, 20547, 20548, 20549187
20528North/Ukraine/CIS (excluding Russia)20551, 20552187
980Baltic States/Europe117, 179, 206111
1004Middle East/Asia181, 210, 1056183
October 12, 2016

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

September 28, 2016
Added the AudienceTargets service for managing audience targets, and the RetargetingLists service for managing retargeting lists. More information about audience targeting
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 Dictionaries.get 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 deletedTo be replaced by regions in the group settingsStatistics will be moved to the region
IDRegion name (with higher levels)
20524West/Ukraine/CIS (excluding Russia)20529, 20530, 20531, 20532, 20533, 20534, 20535, 20550187
20525East/Ukraine/CIS (excluding Russia)20536, 20537, 20538, 20539, 20540187
20526South/Ukraine/CIS (excluding Russia)20541, 20542, 20543187
20527Central/Ukraine/CIS (excluding Russia)20544, 20545, 20546, 20547, 20548, 20549187
20528North/Ukraine/CIS (excluding Russia)20551, 20552187
980Baltic States/Europe117, 179, 206111
1004Middle East/Asia181, 210, 1056183
September 8, 2016

In the Ads.get method, added the PROJECT_DECLARATION value for the AdCategories parameter.

September 6, 2016

For the AdGroups.get method, you can now get the parameters of a group of dynamic ads that has a feed as the data source.

August 22, 2016

Added support for image ads in the Ads service. More about ad types

Added the AdImages service for managing images. This service supports image sizes for use in image ads. More information about images

August 11, 2016

Added the ModifiedSince request parameter to the Keywords.get method.

June 2, 2016

In the BidModifiers service, changed the acceptable coefficient values in bid adjustments for gender, age, and website users.

May 23, 2016

Now you can spend the agency's points instead of the advertiser's points for making requests from an agency representative. More information about points

May 10, 2016

For the AdExtensions.get method, added the request parameters States and ModifiedSince and the response parameters State and Associated.

April 18, 2016

Added the DisplayUrlPath parameter to the methods for the Ads service, along with the DisplayUrlPathModeration parameter in the response of the Ads.get method for text and image ads.

April 14, 2016

The Dictionaries.get method now provides names of ad exchanges (SSPs).

March 30, 2016

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

March 29, 2016
  • Added the AdExtensions service for managing ad extensions. Only one type of extension, the callout, is available at this time. More information about callouts

    The Ads service now supports callouts for text and image ads and dynamic text ads. More about ads

  • Added support for images in the Ads service for ads with the “Ads for mobile apps” type.

  • Added the Dictionaries service for getting reference data: regions, time zones, exchange rates, metro stations, restrictions on parameter values, and other information.

March 14, 2016

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

February 25, 2016

Added the campaign setting ENABLE_AREA_OF_INTEREST_TARGETING to the methods for the Campaigns service (for all types of campaigns).

February 16, 2016

Added the OptimizeGoalId campaign parameter to methods of the Campaigns service (for campaigns with the “Text & Image Ads” type).

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.

January 13, 2016

Added the DomainUrlProcessingStatus parameter to the AdGroups.get method.

January 11, 2016

In the BidModifiers service, changed the acceptable coefficient values in bid adjustments for gender, age, and website users.

December 15, 2015

Added the DynamicTextAdTargets service for managing targeting conditions for dynamic text ads. More information

In the Campaigns service, added campaign support for dynamic text ads. More about campaigns

In the AdGroups service, added group support for dynamic text ads. More about groups

In the Ads service, added support for dynamic text ads. More about ads

Paged data selection is now available for the Bids.get method.

November 9, 2015

The Keywords.get method has the added ability to get the number of impressions and keys for a keyword over 28 days.

The Keywords.add method now allows setting the bid or priority for the keyword being created.

October 26, 2015
September 30, 2015

The Bids.setAuto method now allows calculating bids for search based on the minimum bid for second position in Premium Placement.

September 8, 2015

Added the BidModifiers service for managing bid adjustments. More information about bid adjustments

September 1, 2015

The Bids.get method now allows you to get bidding results of a new auction: the minimum bid and the actual CPC for each position. If the FieldsNames input parameter has the AuctionBids value, the method returns the AuctionBids array.

June 26, 2015
Launched.