Yandex.Direct API

Changes in the reference list of regions
10 December, 16:28

The reference list of regions has been changed. We recommend calling the Dictionaries.get method or the GetRegions method to get an updated list of regions.

Coming soon: changes in the reference list of regions
5 December, 21:30

The Zabaikalsky administrative district and the Republic of Buryatia, which previously belonged to the Siberia federal district, are now part of the Dalnevostochny (Far East) district. In the near future, these administrative changes will be reflected in the reference list of regions returned by the methods Dictionaries.get (in API version 5) and GetRegions (in API version 4 and Live 4).

If your application does not support automatic updating of the reference list of regions, you will need to make changes manually. We will inform you when the updated reference list is available.

Changes to the currency list
29 November, 19:54

Units are no longer used in Yandex.Direct, and all clients are now running their advertising campaigns in currencies.

In approximately one week, the Dictionaries.get method will stop returning data about units in the Currencies reference list:

  • The YND_FIXED currency will be removed from the reference list.
  • For the other currencies, the Rate and RateWithVAT parameters will not be returned.

Make sure that your applications are not using this data.

If you have any questions, please contact the Yandex.Direct API support team.

API News: Behavioral segments in audience targets and more
14 November, 15:23

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.

The Dictionaries.get method also returns the minimum and maximum CPM bids for display ads  in the Currencies reference list.

Added restriction: in an “Ads for mobile apps” campaign, all ad groups must have the same app link.

API version 4 and Live 4: support for units will be disabled
8 November, 11:22

The process that began in 2013 of switching accounts over to actual currencies is now reaching completion. The majority of advertisers and agencies already run their ad campaigns in their payment currency, and soon the option to operate an account in units will be disabled.

During the transition period, several API methods have allowed applications to operate using units as monetary values, even in cases where the campaign and account operate using an actual currency. Beginning December 3rd, however, we will begin placing restrictions on these methods. Please make sure your applications are prepared for these changes.

Methods that will be completely disabled:

  • Version 4 methods: GetBalance, GetSummaryStat, CreateNewReport, CreateNewForecast, GetForecast, CreateInvoice, PayCampaigns, TransferMoney.
  • Version Live 4 methods: GetBalance (Live), GetClientInfo (Live), GetClientsList (Live).

Methods that will only work in the actual currency of the campaign or account:

  • Retargeting (Live), the Add, Update, Get operations
  • CreateInvoice (Live)
  • PayCampaigns (Live)
  • TransferMoney (Live)
  • AccountManagement (Live), the Deposit, Invoice and TransferMoney operations
  • CreateNewForecast (Live)
  • GetEventsLog (Live)

The Currency input parameter will be required for these methods. The parameter value should match the campaign or account currency for all methods except CreateNewForecast (Live) and GetEventsLog (Live).

Methods that will only generate statistics in the campaign currency:

  • GetBannersStat (Live)
  • GetSummaryStat (Live)
  • CreateNewReport (Live)

The Currency input parameter will be required for these methods if the campaign is run in an actual currency. You don’t have to indicate the Currency parameter (or you can pass NULL) for campaigns run in units that have been sent to the special archive.

These changes will not affect API version 5 methods because all these methods already accept and return monetary values in the advertiser’s currency.

Please note: to get statistics, or manage retargeting or clients, we recommend using the API version 5 methods. Read the Migration guide for more information about what methods you can use from version 5 and parameter equivalents in different versions.

If you have any questions, feel free to ask the experts on the Yandex.Direct API support team.

API News: Video ads and much more
15 October, 17:49

Video ads

Video ads can now be launched in Yandex.Direct not only as video extensions to text and image ads, but also as separate video ads. The Ads service has a new ad type for this purpose — CPC_VIDEO_AD.

Video ads can be placed in groups of text and image ads. To create or edit a video ad, pass the ad parameters in the CpcVideoAdBuilderAd structure of the add and update methods.

To learn more about working with video ads in the API, see the documentation.

Getting creatives

Creatives can only be created in the web interface. To get creatives designed in the Ad Builder, use the new Creatives.get method.

Differentiating overlapping keywords and eliminating duplicate keywords

The new KeywordsResearch.deduplicate method allows you to optimize a set of keywords:

  • Fix overlapping keywords that match the same search query. If two keywords differ by one word, a negative keyword is added to one of them. For example, the keywords fur coat and mink fur coat will be converted to fur coat -mink and mink fur coat.
  • Combine several keywords that differ only by negative keywords. The unified keyword contains the negative keywords from all the original keywords.
  • Discard keywords that cannot be saved due to errors.

You can use the method to input both keywords that already have an ID in Yandex.Direct or an external database, as well as new keywords without an ID. The method returns recommendations on which keywords to add, change, or delete. The response format is as close as possible to the request format for the add, update, and delete methods of the Keywords service.

For more information about the KeywordsResearch.deduplicate method, read the documentation.

Managing display campaigns in the Yandex.Direct API
10 October, 20:56

Display campaigns are ideal for strengthening brand loyalty. They attract your target audience into the sales funnel, where you can then continue communicating with them via contextual ads and retargeting.

To make the entire ad purchasing process even easier, you can now manage your display campaigns in the Yandex.Direct API:

  • The Campaigns service supports a new campaign type — CPM_BANNER_CAMPAIGN.
  • The AdGroups service supports a new group type — CPM_BANNER_AD_GROUP.
  • The Ads service supports a new ad type — CPM_BANNER_AD. You can make or upload creatives in the web interface and then use them to create ads in the API.
  • You can now add keywords to a group of display ads using the Keywords service or by targeting user profiles via the AudienceTargets service.
  • You can set up a user profile using the RetargetingLists service: the profile is created as an impression criteria and an AUDIENCE type retargeting list.
  • You can get demographic or user interest-based segments via the Dictionaries service and use them in the profile.

Keep in mind that in order to get statistics for display campaigns, you must use the report type REACH_AND_FREQUENCY_PERFORMANCE_REPORT in the Reports service.

You can find more detailed information about managing display campaigns in the API in the documentation.

api5, news
Age groups 45–54 and 55+ are available in the API
22 August, 10:33

The changes we wrote about earlier are now active: two new age groups are available in bid adjustments and Yandex.Direct statistics.

We recommend creating separate bid adjustments for AGE_45_54 and AGE_55 in the BidModifiers service. The old AGE_45 segment will remain available for several months.

Reports from the Reports service will show the new segments in statistics for dates starting from August 21, 2018.

Traffic volume and weighted CTR in statistics
8 August, 17:45

The Reports service now has fields that were previously only available in the Reports Wizard:

  • AvgTrafficVolume — Average volume of purchased traffic.
  • WeightedCtr — The adjusted click-through rate based on the volume of traffic for positions where ads are shown.
  • WeightedImpressions — Each impression is assigned a weight in proportion to the volume of traffic from the ad position.
New age groups in bid adjustments and statistics
7 August, 11:02

We want to make sure that you know about some upcoming changes in Yandex.Direct so that you can get your apps ready.

Yandex.Direct currently divides users into five age groups: 0–17, 18–24, 25–34, 35–44, and 45+. The 45+ group combines too many different types of people, so we are splitting it into two: 45–54 and 55+. The transition to six age groups is planned for the second half of August.

Why are we doing this?

The new age groups will give you better flexibility for targeting ad impressions by managing bids in the BidModifiers service.You will be able to configure separate bid adjustments for the AGE_45_54 and AGE_55 audience segments.

The old AGE_45 segment will remain available for several months. We recommend that your apps support the new audience segments, since users can select them when creating bid adjustments in the web interface.

What about the stats?

In reports provided by the Reports service, the same users might be assigned to different age groups depending on the date of impression or click:

  • before switching to the new categories, the Age field shows AGE_45.
  • after the switch, it shows either AGE_45_54 or AGE_55.

If the transition date falls within the report period, all three values might appear in the report. Please note: the age group that the user is assigned to in the report depends on the date when statistics were collected, not on the date when the report was requested.

If you filter data by the Age, field in reports and you need statistics for all users over 45, the best practice is to specify all three values in the filter (AGE_45, AGE_45_54 and AGE_55):

"Filter": [{
   "Field": "Age",
   "Operator": "IN",
   "Values": ["AGE_45", "AGE_45_54", "AGE_55"]

If the filter specifies AGE_45 but omits the new segments AGE_45_54 and AGE_55 and the report period begins after the transition date, you will get an error message, because such a request doesn't allow you to obtain correct data.

If the filter does not specify all the segments, statistics for a period that includes the transition date may be incomplete. For example, if you only specify the new segments, the report will not include users who were assigned to the old 45+ category.

When requesting a report for a period after the transition date, you only need to specify the new audience segments in the filter. It's also fine if you specify all three values: AGE_45, AGE_45_54 and AGE_55. You can already add the new AGE_45_54 and AGE_55 segments to the Age field filter right now.

The actual switch to six age groups in bid adjustments and statistics will be announced separately — check the site and the documentation.

If you have any questions, feel free to ask the experts on the Yandex.Direct API support team.

Attribution models and goals in Reports
9 July, 16:04

In June we've added two new parameters to Reports: Goals (the Yandex.Metrica goal IDs to get stats for) and AttributionModels (the attribution models to use for calculating the goal data). The acceptable attribution model values are LSC (last significant click), FC (first click), and LC (last click).

We also changed how we calculate the ConversionRate value: now the number of converted sessions is divided by the number of clicks, instead of by the total number of sessions.

Our example shows you how to retrieve Yandex.Metrica data on selected goals with a specific attribution model.

Now the Reports service allows you to get stats for a goal. This service provides all the features of statistical reports that were available in previous versions of the API, so the statistical methods in API 4 and Live 4 will be deprecated in the near future.

Additional change: the setAuto method of the KeywordBids service has a new BidCeiling parameter for limiting the bid amount.

Sandbox getting refreshed on July 17
3 July, 16:59

On July 17, we are planning to refresh our data in the Sandbox test environment for debugging apps. The Sandbox will be disabled on that day and test data will be deleted. After it refreshes, you’ll be able to activate it and work with it again as usual.

As you know, when the Sandbox is active, test data in an account is saved for a while starting from the last day a request is made to it through the API. Now, we are replacing that rule with a mechanism that periodically clears test data (this is necessary in order for the Sandbox to be functionally more stable).

After the refresh, you can enable the Sandbox in the Yandex.Direct web interface on the API Settings page under Sandbox. You can create test campaigns just as you have always done: in the web interface when you initialize the Sandbox, or add them later via the API.

In the near future, we will start regularly clearing test data from the Sandbox, but we will be sure to warn you ahead of time about this.

Added the KeywordBids.setAuto method
8 June, 19:00

We added the KeywordBids.setAuto method, which allows you to assign bids for keywords in search depending on the desired traffic volume.

More data in Reports: statistics for display campaigns
3 May, 18:52

The Reports service now returns statistics for:

  • Added the value CPM_BANNER_CAMPAIGN for the CampaignType field.
  • Added the new report type REACH_AND_FREQUENCY_PERFORMANCE_REPORT, which shows the new fields AvgCpm (average price per thousand impressions), AvgImpressionFrequency (average impression frequency per user) and ImpressionReach (impression reach: the number of unique users who were shown a banner).
A new approach to setting bids: KeywordBids available for testing
12 April, 14:03

Not long ago we published the documentation for the KeywordBids service in the open beta version of the Direct API. Now the service is available in the full version of the Direct API. You can begin testing your applications and get ready for the launch of the new bid setting interface in Yandex.Direct.

As you remember, prices in Yandex.Direct will soon be calculated not for positions, but for the traffic amounts that correspond to specific formats and places in which your ads can appear. This is a significant change, but not a reason to worry — it should make understanding prices in auctions easier. In any case, here are some answers to popular questions about the launch:

  • The auction and ranking on search will remain unchanged. Improving your ads’ CTR and relevance will still mean that you can get impressions in more noticeable positons and better CPC. The launch of the new interface will not push click prices higher or lower — pricing will remain unchanged. Click prices will be calculated according to the rules of the VCG auction, as they are now.
  • The new KeywordBids service offers more data including the full array of bids and CPC on search, as well as for impressions in expanded format. The more new formats and ad blocks appear on search results pages, the better KeywordBids will perform in comparison to other more outdated methods of calculating prices for positions.
  • The launch will neither disable the Bids service nor break your applications. The Bids service will be available during the transition period, giving you time to begin using the new service and change the logic used to set bids in applications. This means that for some time after the launch you will continue to see bids for positions in the new interface, allowing you to compare positions and traffic volumes in your own campaigns.

When to expect these changes

We are planning to update the bid setting interface in the last two weeks of April. Once we have a definite date, we will be in touch.

Disabled support for the IMPRESSIONS_BELOW_SEARCH strategy
30 March, 14:54

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.

Bid adjustments for video
26 February, 19:07

The BidModifiers service now supports video bid adjustments (VideoAdjustment parameter) — a bid coefficient that is applied when showing ads with video extensions.

Direct API News
31 January, 19:08

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

And we added the CriterionType field in the Reports service.

Image ads that use creatives
15 December 2017, 13:47

The Ads service now supports image ads that use creatives created in the Ad Builder. We added new subtypes of IMAGE_AD type.

See more information about ad types in the documentation.

Support for image ads that use creatives created in the AdBuilder
8 December 2017, 23:29

Next week the Ads service will support image ads that use creatives created in the AdBuilder.

We will add new subtypes of type IMAGE_AD: TEXT_AD_BUILDER_AD (a text and image ad) and MOBILE_APP_AD_BUILDER_AD (a mobile app ad).

How to work with new subtypes:

  • To create or edit an ad, pass its parameters in the TextAdBuilderAd or MobileAppAdBuilderAd structure for the add or update method.
  • To get the ad parameters, list the parameter names in the TextAdBuilderAdFieldNames or the MobileAppAdBuilderAdFieldNames input parameter for the get method.

You can create creatives in the Yandex.Direct web interface only. You can download the list of creatives with their IDs from the AdBuilder.

Please see more information about image ads that use creatives in the documentation.