Yandex.Direct API

Negative keywords library available in the Yandex.Direct API
11 July, 13:28

Sets of negative keywords are now supported in the API:

  • The new NegativeKeywordSharedSets service allows you to manage sets of negative keywords.
  • Methods of the AdGroups service now have the NegativeKeywordSharedSetIds parameter where you can specify up to three IDs of sets. The AdGroups.get method allows you to filter ad groups that use specific sets of negative keywords.

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

news,api5
Video display ads in the Yandex.Direct API
24 June, 16:27

Video ads are now supported in display campaigns:

  • The AdGroups service now supports ad groups with the CPM_VIDEO_AD_GROUP type.

    Restriction. The Gather audience by completion rate setting is currently not supported in the API.

  • The Ads service now supports ads with the CPM_VIDEO_AD type.
  • The Creatives service now supports creatives with the CPM_VIDEO_CREATIVE type.

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

news,api5
Changes to the RetargetingLists service
3 June, 17:30
  • Lifted restrictions on retargeting lists that consist exclusively of rules with the NONE operator. Now these retargeting lists can use both Yandex.Metrica goals and segments, as well as Yandex.Audience segments.
  • The MembershipLifeSpan parameter is now used only for Yandex.Metrica goals. For segments from Yandex.Metrica and Yandex.Audience, the add and update methods ignore the passed value.
  • The maximum number of days in the MembershipLifeSpan parameter increased to 540.
api5, news
Coming soon: 8 sitelinks
28 May, 17:38

We want to let you know that Yandex.Direct ads will soon include up to eight sitelinks. The new limit will take effect in June.

These changes will affect the Sitelinks service, so if you use it, you should prepare your applications now.

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

api5, news
Turbo pages available in the Yandex.Direct API
15 May, 11:05

The changes we wrote about earlier are now active:

  • New TurboPages service for getting Turbo pages that were created in the Turbo Page Builder.
  • Methods of the Ads service now have the TurboPageId parameter. The response to the Ads.get method also has the TurboPageModeration parameter.

    The Href parameter in the TextImageAd, TextAdBuilderAd, CpcVideoAdBuilderAd, and CpmBannerAdBuilderAd structures is now nillable in the Ads.update and Ads.get methods.

  • Methods of the Sitelinks service now have the TurboPageId parameter.

    The Href and Description parameters are now nillable in the Sitelinks.get method.

    The Sitelinks.get method has the new SitelinkFieldNames input parameter.
news,api5
Turbo pages in the Yandex.Direct API: prepare your applications for upcoming changes
18 April, 13:30

We recently launched Turbo pages for desktop. In many types of ads, the link to the site is now optional. The advertiser can choose to specify a Turbo page instead.

What is changing in the API

The Ads service will have a new field: TurboPageId. The TextAd structure will require only one of Href, VCardId, or TurboPageId.

The structures TextImageAd, TextAdBuilderAd, CpcVideoAdBuilderAd, and CpmBannerAdBuilderAd will require only one of Href or TurboPageId. This means that Href will be optional in the add method, and it will be nillable in the update and get methods. Please note: The get method may return nil (null) in the Href field (for example, if the advertiser deleted the main ad link). The application must correctly handle such a response.

The Sitelinks service will also have the TurboPageId field. The Sitelink structure will require only one of the Href or TurboPageId fields. In addition, the get method will have the new SitelinkFieldNames input parameter: use it to enumerate the field names of a sitelink that you want to get. In the response for the get method, the Href and Description fields will be nillable, so the application must also correctly process the nil (null) value in these fields.

There will be a new method for getting a list of the advertiser's published Turbo pages: TurboPages.get.

When to expect the changes

Support for Turbo pages will appear in the API in approximately two to three weeks. Please plan to update your applications. If you have any questions, please contact the Yandex.Direct API support team.

news,api5
Priority goals in statistics
9 April, 11:27

The Reports service supports priority goals:

  • Added the Profit field.
  • The values of RevenueProfit, and GoalsRoi for priority goals are based on the conversion values specified in the campaign settings.
news,api5
Price in ads
27 March, 18:56

Now you can configure the price of a product or service to show in a text and image ad.

  • To add or change the price, pass the price parameters in the PriceExtension structure of the Ads.add or Ads.update method.
  • To remove the price, pass the nil (null) value in the PriceExtension parameter for the Ads.update method.

To get the price parameters, call the Ads.get method with the TextAdPriceExtensionFieldNames and TextAdFieldNames parameters in the request.

api5, news
Disabled ad network settings for conversion strategies
11 March, 16:58

The Campaigns service has new settings for conversion strategies.

If one of the following strategies is selected for search:

  • AVERAGE_CPA, AVERAGE_ROI or WB_MAXIMUM_CONVERSION_RATE for a “Text & Image Ads” campaign
  • AVERAGE_CPI or WB_MAXIMUM_APP_INSTALLS for an “Ads for mobile apps” campaign

then there is no support for the NetworkDefault.BidPercent and NetworkDefault.LimitPercent parameters in ad networks, or for the MAINTAIN_NETWORK_CPC option in the Settings structure.

The add and update methods ignore the passed values and return a warning. To enable the strategy in NETWORK_DEFAULT networks, you need to pass an empty NetworkDefault structure.

The get method doesn't return the NetworkDefault structure or the MAINTAIN_NETWORK_CPC option.

news,api5
News for the Yandex.Direct API
4 February, 18:35

The Campaigns service now supports priority goals for campaigns with the “Text & Image Ads” type: the addupdate and get methods have the PriorityGoals structure.

You can configure bid adjustments based on device type for groups of display ads in the BidModifiers service.

For smart banners there are some changes in statistics provided by the Reports service:

  • For campaigns with the SMART_BANNER_CAMPAIGN type, if at least one of the CriterionCriterionIdCriteria, or CriteriaId  fields is specified, or data is filtered by the SmartBannerFilterId field, or the CRITERIA_PERFORMANCE_REPORT type is selected, a dash will be shown in the Impressions and Ctr fields.
  • The ImpressionShare field can be specified in conjunction with TargetingLocationId and TargetingLocationName.
news,api5
Changes in the reference list of regions
10 December 2018, 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.

news,api4,api4live,api5
Coming soon: changes in the reference list of regions
5 December 2018, 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.

news,api4,api4live,api5
Changes to the currency list
29 November 2018, 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.

news,api5
API News: Behavioral segments in audience targets and more
14 November 2018, 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.

news,api5
API version 4 and Live 4: support for units will be disabled
8 November 2018, 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.

news,api4,api4live
API News: Video ads and much more
15 October 2018, 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.

news,api5
Managing display campaigns in the Yandex.Direct API
10 October 2018, 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 2018, 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.

news,api5
Traffic volume and weighted CTR in statistics
8 August 2018, 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.
news,api5
New age groups in bid adjustments and statistics
7 August 2018, 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.

news,api5