Direct API

The API for the Yandex.Direct service provides programmatic access to data and enables you to create applications for managing advertising campaigns.

The API is used by applications such as Direct Commander and Direct for mobile.

Who should use the API

The Direct API is intended primarily for advertising agencies and direct advertisers — commercial firms, companies in the service industry, and others. Developing custom applications allows them to fully implement their own approaches to running advertising campaigns, get statistical reports promptly, and accurately forecast budgets.

Ways to use the API

Conducting advertising campaigns

The API allows you to effectively manage complex and large-scale advertising campaigns with many ads and keyword phrases. You can use the API to automate routine operations, such as regularly updating the CPC using a specific algorithm. The API also lets you create convenient tools for viewing and editing campaigns: to make changes, you do not have to wait for pages to load, like in the web interface.

Integration with business applications
You can use the Direct API to manage advertising based on information about goods and services from your database, for example:
  • Automatically generate large arrays of keyword phrases and add the names of specific brands or product models to them — for such refined phrases, the CPC is lower while click rates and conversion are higher than for “generic” phrases.
  • Stop and restart ad displays depending on whether products are in stock.
  • Update ad texts when the price of the product changes.
  • Automatically generate ads about upcoming promotions and sales; improve the display position of these ads.
A/B testing for ads

The API offers more features than the web interface. In particular, you can use the API to create and edit ad groups — multiple variations of ads with the same set of keywords and other display settings. Initially, the ads in the group are shown in rotation, but as statistics are accumulated, the system begins to show the ad with the highest CTR more frequently. In this way, the ad that is the most appealing to the audience is selected automatically from the ad group.

Monitoring and analyzing the effectiveness of advertising campaigns
The Direct API provides both aggregate and detailed statistics for impressions, clicks, conversions and expenditures that can be uploaded to a Decision Support System, accounting system, and so on.
Selecting keyword phrases and expanding advertising campaigns
The keyword selection tool takes your set of keywords and gives you statistics on search queries with these words, along with statistics on other queries made by users who are performing searches using these words. You can use the resulting data to supplement the list of keyword phrases. The budget forecasting tool helps estimate the cost and the potential number of clicks for these phrases in different display positions.

A full list of available operations is provided in the documentation.

Start developing your application

  1. Review the documentation and examples.
  2. Register your application on the Yandex OAuth server and submit a request for API access.
  3. Create a test user and test user data:
    1. 3.1. 
      Register the test user's account on Yandex.
    2. 3.2. 
      Create an advertising campaign on behalf of the test user in the Direct web interface (creating one ad with a single keyword phrase is enough). This is a requirement for accessing the Direct API.
    3. 3.3. 
      In the API section of the Direct interface, click the Get API access link and accept the user agreement.
    4. 3.4. 
      Enable the Sandbox — an application debugging environment, where you can manage test campaigns without actual impressions and spending.
    5. 3.5. 
      Get a debug token on behalf of the test user.
  4. Send HTTP POST requests to the Sandbox, using the debug token. Sample request:
POST /json-api/v4 HTTP/1.1
Content-Type: text/plain; charset=UTF-8

           "method": "GetCampaignsList",
           "locale": "en",
           "token": "1b652016a45d4b5db18132e071e36489"


March 3, 2015 Added a coefficient for setting bids on mobile devices and information about device types in the reports.

February 26, 2015 Added the Get operation to the Keyword (Live) method for getting keyword productivity values. AutoBroker is always on for all phrases.

February 11, 2015 Added the AdGroupID output parameter for the Get operation of the Retargeting (Live) method.

Subscribe to news