Direct API

Questions and answers

In the beginning

API usage

Who can I ask

In the beginning

  • What is the Yandex.Direct API and what can I use it for?
    The API allows developers to create applications that interact with the Yandex contextual advertising service directly.
    By using such applications, advertisers and advertising agencies can flexibly and effectively control and maintain complex large-scale advertising campaigns, more precisely estimate their budgets, and promptly receive statistical reports for every active campaign.
    The most common applications of the API are:
    • Automatic generation of statistical reports for the selected advertising campaigns.
    • Using the data obtained from Yandex.Direct as input for various business applications, including integration of the data into existing statistics databases inside the company infrastructure.
    • Developing more complex applications to control sophisticated Internet advertising campaigns.
  • How do I connect to the API?
    To connect to the API, follow these steps:
    1. Open the "API" section and accept the License Agreement.
    2. Create the API certificate using one of the available methods, see How to get access to the API.
      Note
      You can create a certificate that is valid for a period from 1 to 3 months.
    In your application script you should explicitly specify paths to the certificate files, the private key and the file cacert.pem.
    Attention We recommend that you use the following third-party modules for interaction between servers over HTTPS:
  • How can I obtain a certificate?
    When you gain access to the API you can create a certificate for your account using one of the following methods:
    • Get a ready-made signed certificate from Yandex.Direct.
    • Generate the private key yourself and then confirm the certificate on the Yandex.Direct server.
    More detailed information can be found in the How to get access to the API section.

API usage

  • What is the maximum number of campaigns allowed for a single API certificate?
    The API certificate is signed for a particular login. This means that you can control all campaigns related to this login using a single API certificate.
  • What about the existing API usage limitations?
    There are two types of limitations defined within the API: technical and score-based.
    Technical limitations
    These limitations apply to the maximum number of method calls per day (24 hours). The number varies from method to method:
    If the allowed number of calls for any of the above methods is exceeded, the following limitation applies: the method cannot be called more than once every 10 minutes until the start of the new day.
    Limitations are also applied to the maximum number of phrases used in the following methods:
    The maximum number of requests processed simultaneously is limited. No more than five simultaneous requests can be sent per login.
    Score-based limitations
    The Yandex.Direct API is a free service, but the number and variety of operations available during the day depend on the current number of score points on your account. API points are calculated and your account credited every 24 hours.
    The number of available score points depends on a great number of factors, including:
    • The number of ads rejected on moderation.
    • The number of phrases disabled because of a low CTR.
    • The average CTR of the advertising campaign.
    • The average budget of the advertising campaign.
    When an operation is completed, read the server response to check the operation cost and the number of points left on the account.
    Costs of score-limited operations:
    • Adding an ad - 12 points.
    • Editing an ad - 4 points.
    • Adding a new phrase - 2 points.
    • Editing a phrase - 1 point.
  • How can I increase the number of available points?
    You can increase the number of available points by optimizing your advertising campaigns. You can do this by adding and refining keywords, improving the text of your ad to increase the CTR, and increasing your minimum bids. The points are calculated every 24 hours.
  • Is there any difference if I control my campaign using the API or using the web interface?
    The API offers the same functionality as the Yandex.Direct web interface. All changes made using the API are made to your advertising campaigns.
  • Please show me code examples of Perl, Python and PHP client applications which I can use to access my Yandex.Direct account
    Perl:
    use strict;
    use SOAP::Lite;
    use LWP::Simple;
    use Crypt::SSLeay;
    
    # The directory where the certificate files are stored
    $ENV{HTTPS_CA_DIR} = '/path_to_certs/';                     
    
    # The file containing the user certificate
    $ENV{HTTPS_CERT_FILE} = $ENV{HTTPS_CA_DIR} . 'cert.crt'; 
    
    # The file containing the private key
    $ENV{HTTPS_KEY_FILE} = $ENV{HTTPS_CA_DIR} . 'private.key';
    
    # The file containing the root certificate
    $ENV{HTTPS_CA_FILE} = $ENV{HTTPS_CA_DIR} . 'cacert.pem';
    
    # Creates an object to connect to the SOAP
    my $client = SOAP::Lite->service('http://soap.direct.yandex.ru/wsdl/v4/');
    $client->namespace('namesp1');
    
    # Calls the PingAPI method (change it for the method of your choice)
    my $result = $client->PingAPI();
    
    PHP:
    require_once('nusoap073/lib/nusoap.php');
    $proxyhost = '';
    $proxyport = '';
    $proxyusername = '';
    $proxypassword = '';
    $wsdlurl = "http://soap.direct.yandex.ru/wsdl/v4/";
    $client = new nusoap_client($wsdlurl, 'wsdl', $proxyhost, $proxyport, $proxyusername, $proxypassword); 
    $client->authtype = 'certificate';
    $client->decode_utf8 = 0;
    $client->soap_defencoding = 'UTF-8';
    $client->certRequest['sslcertfile'] = '/path_to_certs/cert.crt'; 
    $client->certRequest['sslkeyfile'] = '/path_to_certs/private.key'; 
    $client->certRequest['cainfofile'] = '/path_to_certs/cacert.pem';
    
    # Calls the PingAPI method (change it for the method of your choice)
    $result = $client->call('PingAPI', array());
    
  • How can I view the XML code of the request and the server response?
    For debugging, it is often useful to display the client SOAP request and the server SOAP response.
    Perl:
    my $client = SOAP::Lite->service($client->on_debug(sub {print @_}));
    Python:
    SOAPpy.Config.debug = 1
  • Which technologies are supported by the API?
    The Yandex.Direct API uses the SOAP protocol version 1.1 and the WSDL language to communicate between applications. The programming languages currently supported are: Perl, PHP, Python, and Java.
  • How frequently can I call GetReportList and GetForecastList methods?
    You cannot call GetReportList and GetForecastList methods more often than once every 10 seconds. This interval is set due to the overall frequency of data updates.
  • How frequently can I update bids?
    We recommend changing bids no more than once every 20-30 minutes.

Who can I ask

  • Who can I ask for help if some problems arise when using the API?
    If you cannot find a comprehensive answer for your question in the documentation, send an email to the Yandex.Direct support team: api@direct.yandex.ru.
    Please provide the following information in your message:
    • The login used to connect to the service.
    • The exact time of the request.
    • The name of the method and the code of the method call.
    • The server response and its code.
    • A brief explanation of the current problem.