Yandex.Direct API

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.
No comments
news,api5
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.

No comments
news,api5
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.

No comments
news,api5
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.

No comments
news,api5,api4live,api4
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.

No comments
news,api5
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).
No comments
news,api5
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.

No comments
news,api5
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.

No comments
news,api5
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.

No comments
news,api5
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.

No comments
news,api5
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.

No comments
news,api5
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.

No comments
news,api5
Changes to point calculations for Keywords.get and Bids.get
23 November 2017, 03:22

Next week, we will change the number of points deducted and calculation logic for the get method in the Keywords and Bids services.

Previously, to retrieve data for keywords (Keywords.get), you would spend 1 point for every keyword and 15 points for every method call. We decided to decrease the cost of these operations and balance points when working with the Keywords and Bids services.

New values:

Keywords.get – 1 point per 2000 keywords, if none of the Productivity, StatisticsSearch, StatisticsNetwork parameters are requested, and 3 points for 2000 keywords with a request for any statistical data.

Bids.get – 3 points per 2000 keywords.

If fewer than 2000 keywords are retrieved, points are deducted only for the method call. The cost in points for get method calls in these services remains unchanged.

As a result, the cost in points will decrease in general, especially if you previously spent a lot of points to synchronize data for keywords. Additionally, you will be able to flexibly select which keywords you want to retrieve data for and how much you will spend.

In other news:

No comments
news,api5
API: Information from Yandex.Business Directory when serving ads on Yandex.Maps
19 September 2017, 17:19

You can use new setting to display information about an organization from Yandex.Business Directory when serving ads on Yandex.Maps: we added the campaign setting ENABLE_COMPANY_INFO to methods for the Campaigns service (for campaigns with the “Text & Image Ads” and “Dynamic ads” types).

No comments
news,api5
News and upcoming changes to the Direct API
15 September 2017, 17:19

A long-awaited feature has come to the Reports service in the fifth version of the API: support for requests in JSON format.

We also added new methods to the AgencyClients and Clients services for editing parameters of agency clients and advertisers, editing settings of users representing advertisers (Clients.update, AgencyClients.add, AgencyClients.update). And the Campaigns service has disabled support for the ENABLE_BEHAVIORAL_TARGETING setting in the Settings structure (the “Do not consider user preferences” option).

We are continuing to gradually close the methods in the 4 and Live 4 versions of the API:

  1. In December of 2017 we plan to disable the following methods:
    UpdateClientInfo and UpdateClientInfo (Live), GetSubClients, GetClientsList and GetClientsList (Live), GetClientInfo and GetClientInfo (Live), CreateNewSubclient and CreateNewSubclient (Live), GetClientsUnits, RetargetingCondition (Live), Retargeting (Live).
  2. Statistics methods in versions 4 and Live 4 will be disabled in February of 2018:
    CreateNewReport and CreateNewReport (Live), GetReportList, DeleteReport, GetBalance and GetBalance (Live), GetSummaryStat (Live), GetBannersStat (Live).

If you use any of the methods that we are planning to disable, you should quickly transfer them to API 5. Otherwise, these applications can lose access to the API.

The documentation in the Migration Guide provides all the information about method and parameter equivalents in the API Live 4 and API 5 versions needed to correctly transfer your applications to the fifth version of the API.

We will inform you at each stop of the closing of these methods.

No comments
news,api4,api4live,api5
Added support for second ad title
16 August 2017, 11:27

Now you can choose a second ad title (35 characters in length). And your ad texts can be up to 81 characters long.

  • 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. We recommend getting the updated list of restrictions by calling the Dictionaries.get method with the Constants reference list specified in the request.
No comments
news,api5
More data in Reports: query statistics from search sites
8 August 2017, 19:28

A report with the SEARCH_QUERY_PERFORMANCE_REPORT type now contains statistics for queries from search sites in the Yandex Advertising Network. The report includes information from both Yandex and its search partners.

In this type of report you can see the name of the site in the Placement field. To view statistics for different sites separately, you can filter the Placement field by site name.

Additional news: Autofocus is become built-in campaign feature
The Campaigns service has disabled support for the ENABLE_AUTOFOCUS setting in the Settings structure.

No comments
news,api5
Related keywords get even simpler
23 June 2017, 05:59

Managing your Related keywords and Additional relevant phrases is now even simpler — as of today, they have combined into one easy-to-use tool:

1. 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.

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

No comments
news,api5
Data for new Premium Placement positions
20 June 2017, 16:04

Support for new Premium Placement positions has been added to the Bids service. The AuctionBids array, returned via the Bids.get method, now features the element 'P14' (fourth position in Premium Placement) with the minimum bids and click prices for the extra ad. The SearchPrices array for Position="PREMIUMBLOCK" also gives the value 'P14' — the entry price for Premium Placement. Also the 'P14' has been added as the query parameter Position of the Bids.setAuto method.

No comments
news,api5
Regional bid adjustment
3 May 2017, 16:27

The BidModifiers service now supports regional bid adjustments. You can use the BidModifiers.add method (see the RegionalAdjustments array) to add a set of regions and bid coefficients that are applied when displaying ads in these regions on the campaign level.

No comments
news,api5