Documentation

What do you want to ask Support about?

Use cases and features of the Yandex.Direct API are described in detail in the documentation. If you didn't find the answer to your question, contact our experts — we are always ready to help.

Choose a question from the list below or to the left. After choosing the relevant topics, you will see either an answer to your question or a contact form.

Questions about using the Yandex.Direct API

What is the Yandex.Direct API and what can it be used for?

The API for the Yandex.Direct service provides programmatic access to data and enables you to create applications for managing advertising campaigns. External applications use the API to add and edit campaigns, ads, and keywords, and to set bids.

The Yandex.Direct API is intended primarily for advertising agencies and direct advertisers — commercial firms, companies in the service industry, and others. They develop their own applications in order to fully implement their own approaches to running advertising campaigns.

The features and options of the programming interface are described in detail in the documentation.

Is there a difference in managing an advertising campaign using the API and using the web interface?

All changes made via the API are reflected in your advertising campaigns.

Are there any programs available that use the Yandex.Direct API?

Since different companies have different approaches to managing advertising, various solutions have appeared on the market for managing advertising based on the Yandex.Direct API.

Many advertising agencies offer their clients tools for automated management of ads in Yandex.Direct, and also use these tools to optimize their own processes. All of these solutions are based on Yandex.Direct API methods.

Yandex also has solutions based on the Yandex.Direct API:

  • The Direct Commander program is intended for management of large-scale advertising campaigns in a convenient interface.
  • Mobile Direct for iPhone and Android gives advertisers the ability to manage their campaigns as efficiently as possible.
Which technologies are supported in the API?

Requests to the Yandex.Direct API are made over the HTTPS protocol using the POST method. Input and output data structures are passed in the body of the request and response.

The Yandex.Direct API supports two formats: JSON and SOAP.

Authentication uses the OAuth 2.0 protocol: requests must specify the access token.

How much does it cost to use the API?

Both connection to the Yandex.Direct API and usage are free of charge.

How do I connect to the API?

An application (program, script, or other) sends an API request on behalf of a Yandex.Direct user — an advertiser or advertising agency — and manages this user's data.

The app can access a user's data under the following conditions:

  1. The app developer completed the application registration process, and the request for access was approved.

  2. The Yandex.Direct user is a direct advertiser, advertising agency, or client of an advertising agency who was granted access to the data by the agency.

    Note. 
    • If the agency granted the client read-only access to the web interface, the client can only get data when using the API, as well.

    • If the agency granted the client permission to edit campaigns, the client can use either the web interface or the API for managing campaigns.

  3. At least one advertising campaign has been created for this user in the web interface (creating one draft of an ad with a single keyword is sufficient).
  4. The user has accepted the user agreement on the API page for the Yandex.Direct service.
  5. The user has allowed the app to make requests.

    The app must request permission from the user to access data, get an access token, and specify the token in requests.

    To get a token, the application must redirect the user to the access request page. The user authenticates in Yandex (using the username for Direct) and clicks the Confirm button. Next, the Yandex server generates a token and sends it to the app.

How do I get a token for a user?
Getting a token manually

At the app debugging stage, you can get a so-called debugging token in the name of a test user. See the section Debugging token in the Yandex.OAuth guide.

Getting a token automatically

When you are ready to begin working with real user data, you need to implement a user-friendly way to get tokens in the application. To get a token, the application should redirect the user to a special Yandex.OAuth page for requesting access. The user logs in on Yandex (with the username for Yandex.Direct) and clicks the Allow button to grant the application access to personal data. Yandex.OAuth generates a token and transmits it to the application automatically.

Yandex.OAuth supports multiple ways to transmit the token that are suitable for different types of applications: desktop programs, mobile apps, web services, and others. The flow for getting a token is covered in detail in the OAuth guide.

See also: PHP example, Python example.

Attention! Regardless of whether the token is obtained manually or automatically, it allows you to manage the user's real advertising materials.
Which method should I choose for getting a token?

In some cases, you can use tokens that you obtain manually after you switch to working with real user data. For example:

  • If the application only has a small number of users, who are representatives of a single advertiser.

  • If the application doesn't interact with the user. For example, this is a script for automatically updating bids.

Tokens should be obtained automatically if the application is accessed by multiple advertisers or a large number of users with different access rights.

Why did the token become invalid?

A token might become invalid if, for example, the user's password changed on Yandex. For a complete list of reasons, see the section Revoking tokens in the Yandex.OAuth guide. In this case, a new token must be obtained.

If you are using an application, we recommend that you register a special representative in Yandex.Direct and get a token for the representative. See the section Recommendations for registering representatives.

How can I increase the number of points available to me?

Your daily limit of points depends on the activity of advertising campaigns — the number of impressions and clicks, and resulting expenditures.

If the number of impressions and clicks isn't growing much or campaigns are short on funds, frequent and large API requests create an unreasonable load on the Yandex.Direct servers. The daily limit is calculated using a grid of budget thresholds based on statistics for different types of campaigns.

The daily limit is re-calculated once a day.

See also

How can I view the XML code of the request and the server response?

For detecting errors and debugging, sometimes you need to output the client's SOAP request and the server's SOAP response.

For Perl:

my $client = SOAP::Lite->service($client->on_debug(sub {print @_}));
How can I tell if there are active displays for a keyword?

Check whether the following conditions are met:

  • Make sure the keyword is active (the State parameter is set to ON) by using the Keywords.get method.
  • Make sure the group has at least one active ad (the State parameter is set to ON) by using the Ads.get method. Ads can be selected simultaneously by the group ID (the AdGroupIds input parameter) and the state (the States input parameter).
  • Make sure the campaign is active (the State parameter is set to ON) by using the Campaigns.get method.

If all these conditions are met, ad displays for the keyword are possible. However, this does not guarantee that displays are occurring at this time. Common reasons for lack of displays:

  • The campaign is currently being activated.
  • Displays are automatically suspended according to the daily budget settings or an automatic strategy.
  • Displays are automatically suspended according to time targeting settings.

For more information, see the section Display problems in the Help for Direct.

How can I find out about changes in the Yandex.Direct API?

To get information about changes to the Yandex.Direct API:

  • Use the button in the News section to subscribe to the API mailing list.
  • Watch for announcements in the official blog.

A list of changes by API version is provided in the following sections:

Where is the documentation for version 4 and Live 4?

The documentation for version 4 and Live 4 is at https://tech.yandex.com/direct/doc/dg-v4/.

How does version 5 differ from version 4 and Live 4?

For information about changes in version 5 compared to previous versions and a list of equivalents for methods and their parameters, see the Migration guide.