Documentation
Developer's guide
Methods
 Ctrl Prev

Questions and answers

What is the Yandex.Direct API, and what can I use it 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 for adding and editing campaigns, ads and keywords, setting bids, and getting impression statistics.

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.

More information about ways to use the API...

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

The API has more features than the web interface. In particular, you can use the API to create and edit ad groups — multiple variations of an ad with the same set of keywords and other display settings.

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

Which technologies are supported in the API?

Requests to the 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 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 Direct API and usage are free of charge.

How do I connect to the API?

Application access

The application developer must complete the application registration process.

An API request is made on behalf of a Direct user — an advertiser or advertising agency. The request must specify the access token, which is a special code allowing the application to perform operations with this user's data.

User access

To get a token, the application must redirect the user to the access request page. The user authenticates in Yandex (using his username for Direct) and clicks the Confirm button. All other actions are performed automatically by the application and the Yandex server.

Who should register the application?

The application developer registers the application on the Yandex OAuth server and creates a request for access to the Direct API. This only needs to be done once, regardless of the number of copies of the application.

If you purchased or use a ready-made program, you do not need to register the application or submit the access request.

How do I get a token for a user?

To get a token, the app must redirect the user to the access request page, which is a special page on the Yandex OAuth server. The user authenticates on Yandex (using his login name in Direct) and grants the app access to personal data. The Yandex OAuth server generates a token and passes it to the app.

The procedure for getting a token is described in detail in the OAuth authentication guide.

Note. At the app development stage, you can get a debugging token in the name of a test user. See the section Debugging token in the OAuth authentication guide.

Why did the token become invalid?

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

If it is a problem for the app to get a new token (for example, the app updates bids automatically and does not interact with the user), we recommend registering a separate account in Direct as the representative of a client or agency. If this account will only be used in the app and not in the browser, there is minimal risk of it being compromised, and the password can be changed less often than normally.

What restrictions are there on API usage?

There are several types of restrictions in the API.

Access restrictions

Direct API access is not available for users of the Light web interface. These users will need to switch to the Professional web interface.

Clients of advertising agencies can get API access:

  • If the agency gave the client read-only access to the web interface, in the API the client will only be able to get data.
  • If the agency granted the client permission to edit campaigns, the client can manage campaigns either in the web interface or using the API.

An agency sets up access permissions for its clients using the UpdateClientInfo
[no-highlight[

Changes Yandex.Direct accounts.

More UpdateClientInfo

]no-highlight]
method, and also in the web interface (the edit campaign option on the page for editing client settings).

API access may be restricted by IP address, for increased information security. The list of allowed IP addresses can be specified on the Direct API access management page on the Settings tab.

Technical limitations
  1. A maximum of five simultaneous API requests are allowed from a single user.

  2. For the following methods, a limit is imposed on the number of calls per day (24-hour period).

    • CreateOrUpdateCampaign
      [no-highlight[

      Creates a campaign with the specified parameters, or changes the parameters of an existing campaign.

      More CreateOrUpdateCampaign

      ]no-highlight]
      ― 100 calls for editing each campaign and 100 calls for creating campaigns.
    • CreateOrUpdateBanners
      [no-highlight[

      Creates an ad and keywords, or changes an existing ad and keywords.

      More CreateOrUpdateBanners

      ]no-highlight]
      ― 1000 calls per campaign.
    • SetAutoPrice
      [no-highlight[

      Sets bids for keywords, or calculates them based on an algorithm.

      More SetAutoPrice

      ]no-highlight]
      ― 100 calls per campaign.
    • UpdatePrices
      [no-highlight[

      Sets bids and/or priorities for the specified keywords.

      More UpdatePrices

      ]no-highlight]
      ― 3000 calls per campaign. You can set prices for a maximum of 1000 keywords in a single request.
    • CreateNewReport
      [no-highlight[

      Generates a campaign statistics report on the server.

      More CreateNewReport

      ]no-highlight]
      and GetBannersStat
      [no-highlight[

      Returns statistics for the specified campaign for a period no longer than seven days.

      More GetBannersStat (Live)

      ]no-highlight]
      ― 300 calls per campaign.
    • GetSummaryStat
      [no-highlight[

      Returns statistics for the specified campaigns for each day of the specified period.

      More GetSummaryStat

      ]no-highlight]
      ― 100 calls per campaign.
    • GetKeywordsSuggestion
      [no-highlight[

      Returns suggestions for keywords.

      More GetKeywordsSuggestion

      ]no-highlight]
      ― 3000 calls from a single user.
    • CreateInvoice
      [no-highlight[

      Generates an invoice for one or more campaigns in HTML format.

      More CreateInvoice

      ]no-highlight]
      , GetCreditLimits
      [no-highlight[

      Returns information about credit provided to an advertising agency for campaign payments.

      More GetCreditLimits

      ]no-highlight]
      , PayCampaigns
      [no-highlight[

      Paying for campaigns using an advertising agency‘s credit limit.

      More PayCampaigns

      ]no-highlight]
      , TransferMoney
      [no-highlight[

      Transfers funds between campaigns.

      More TransferMoney

      ]no-highlight]
      ― 3000 calls from a single user.
    • All other methods ― 50,000 calls on behalf of a single user.
    Attention! If you have reached the maximum, the method will be available only once every 10 minutes until the start of the next day.
  3. For the following methods, a limit is imposed on the amount of input data:

    • CreateOrUpdateBanners
      [no-highlight[

      Creates an ad and keywords, or changes an existing ad and keywords.

      More CreateOrUpdateBanners

      ]no-highlight]
      ― up to 1000 ads.
    • UpdatePrices
      [no-highlight[

      Sets bids and/or priorities for the specified keywords.

      More UpdatePrices

      ]no-highlight]
      ― up to 1000 keywords.
    • GetSummaryStat
      [no-highlight[

      Returns statistics for the specified campaigns for each day of the specified period.

      More GetSummaryStat

      ]no-highlight]
      ― the number of requested campaigns multiplied by the number of days in the selected period must not exceed 1000.
    • CreateNewForecast
      [no-highlight[

      Generates a forecast on the server for impressions, clicks and expenses.

      More CreateNewForecast

      ]no-highlight]
      ― up to 100 keywords.
    • CreateNewWordstatReport
      [no-highlight[

      Generates a search query statistics report on the server.

      More CreateNewWordstatReport

      ]no-highlight]
      ― up to 10 keywords per request, and up to 1000 keywords per day.
    • GetBanners
      [no-highlight[

      Returns parameters of ads and keywords.

      More GetBanners

      ]no-highlight]
      ― up to 2000 ads or up to 10 campaigns in a single request.
    • GetBannerPhrases
      [no-highlight[

      Returns information about keywords.

      More GetBannerPhrases

      ]no-highlight]
      , GetBannerPhrasesFilter
      [no-highlight[

      Returns information about keywords and lets you limit what is included in returned data.

      More GetBannerPhrasesFilter

      ]no-highlight]
      ― up to 1000 ads per request.
    • GetClientInfo
      [no-highlight[

      Returns Yandex.Direct accounts.

      More GetClientInfo

      ]no-highlight]
      — up to 1000 user logins.
    • StopBanners
      [no-highlight[

      Stops displaying ads.

      More StopBanners

      ]no-highlight]
      , ResumeBanners
      [no-highlight[

      Allows ad displays.

      More ResumeBanners

      ]no-highlight]
      , ArchiveBanners
      [no-highlight[

      Archives the ad.

      More ArchiveBanners

      ]no-highlight]
      , UnArchiveBanners
      [no-highlight[

      Removes an ad from the archive.

      More UnArchiveBanners

      ]no-highlight]
      , DeleteBanners
      [no-highlight[

      Deletes ads.

      More DeleteBanners

      ]no-highlight]
      — up to 2000 ad IDs.
  4. Using the CreateNewSubclient
    [no-highlight[

    Registers a client of an advertising agency in Yandex and creates an account in Yandex.Direct.

    More CreateNewSubclient

    ]no-highlight]
    method, an advertising agency can register no more than 100 clients per day.
  5. Financial transactions have the following restrictions:

    • Up to 30 financial transactions per day per campaign, including calls of the CreateInvoice
      [no-highlight[

      Generates an invoice for one or more campaigns in HTML format.

      More CreateInvoice

      ]no-highlight]
      and PayCampaigns
      [no-highlight[

      Paying for campaigns using an advertising agency‘s credit limit.

      More PayCampaigns

      ]no-highlight]
      methods and transferring funds using the TransferMoney
      [no-highlight[

      Transfers funds between campaigns.

      More TransferMoney

      ]no-highlight]
      method (deducting funds using the TransferMoney
      [no-highlight[

      Transfers funds between campaigns.

      More TransferMoney

      ]no-highlight]
      method does not count).
    • Up to 30 financial transactions per day per shared account, as the total of the Deposit
      [no-highlight[

      Adds funds to shared accounts using an advertising agency‘s credit limit, or the advertiser‘s overdraft.

      More Deposit

      ]no-highlight]
      and Invoice
      [no-highlight[

      Generates an invoice in HTML format.

      More Invoice

      ]no-highlight]
      operations for the AccountManagement (Live)
      [no-highlight[

      Manages the shared account.

      More AccountManagement (Live)

      ]no-highlight]
      method.
    • Up to 3 TransferMoney
      [no-highlight[

      Transfers funds between clients‘ shared accounts.

      More TransferMoney

      ]no-highlight]
      operations for the AccountManagement (Live)
      [no-highlight[

      Manages the shared account.

      More AccountManagement (Live)

      ]no-highlight]
      method per day per shared account (both credits and deposits are counted).
  6. For the following methods, a restriction is applied to the number of reports that can be stored on the server simultaneously:
    • CreateNewReport
      [no-highlight[

      Generates a campaign statistics report on the server.

      More CreateNewReport

      ]no-highlight]
      — maximum 5 reports for a single user.
    • CreateNewForecast
      [no-highlight[

      Generates a forecast on the server for impressions, clicks and expenses.

      More CreateNewForecast

      ]no-highlight]
      — maximum 5 reports for a single user.
    • CreateNewWordstatReport
      [no-highlight[

      Generates a search query statistics report on the server.

      More CreateNewWordstatReport

      ]no-highlight]
      — maximum 5 reports for a single user.
Point-based limitations
Once per day, points are awarded to each API user. They do not accumulate, and are awarded starting from zero each day. Points are used as a method of paying for certain API operations (see below). If you do not have enough points, you cannot perform these operations. The GetClientsUnits
[no-highlight[

Returns the number of points the user has.

More GetClientsUnits

]no-highlight]
method returns the number of points available to the user.

Points are used when calling the following methods:

  1. CreateOrUpdateBanners
    [no-highlight[

    Creates an ad and keywords, or changes an existing ad and keywords.

    More CreateOrUpdateBanners

    ]no-highlight]
    :
    • Creating an ad ― 12 points.
    • Editing an ad ― 4 points.
    • Adding a keyword ― 2 points.
    • Editing a keyword ― 1 point.
  2. GetKeywordsSuggestion
    [no-highlight[

    Returns suggestions for keywords.

    More GetKeywordsSuggestion

    ]no-highlight]
    — 3 points per keyword.
  3. CreateNewWordstatReport
    [no-highlight[

    Generates a search query statistics report on the server.

    More CreateNewWordstatReport

    ]no-highlight]
    — 10 points per keyword.
  4. AdImage (Live)
    [no-highlight[

    Manages images: uploads and deletes images, returns a list of images, and so on.

    More AdImage (Live)

    ]no-highlight]
    — 2 points per image loaded.
  5. AdImageAssociation (Live)
    [no-highlight[

    Adds, removes, or returns associations of images with ads.

    More AdImageAssociation (Live)

    ]no-highlight]
    :
    • Adding an association between an image and an ad — 2 points.

    • Removing an association — 1 point.

    Note. When adding/removing an association between an image and an ad that has the “Draft” status, points are not deducted.

The more efficiently you use Yandex.Direct, the more points you will be awarded. Inefficient use is generally associated with creating ads that are rejected during moderation or adding keywords that have a low CTR. These sorts of practices waste the resources of Yandex.Direct and are not encouraged.

Efficient use of Yandex.Direct is associated with searching for successful keywords and ad texts that raise the CTR. The number of points also depends on the campaign size and advertising expenditures. This means that more points are awarded to users who have a higher campaign balance and higher bids.

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

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. Points are recalculated and awarded every 24 hours.

Show me code examples for Yandex.Direct API clients

Application samples in various programming languages are provided in the documentation:

Perl
PHP
Python
C#
Authentication
Reports

How do I download the report file?

You can use the GetReportList method to get information about available reports. You can refer to the sample provided in the documentation to create a script for downloading a prepared report.

How frequently can I call the GetReportList and GetForecastList methods?

Check report readiness in a single thread, no more than once every 10-30 seconds. We recommend increasing the interval before each consecutive check, for example: 10, 20, 40, ... seconds. For details, see the section Requirements for an app.

How frequently can I update bids?

Recommendations on the frequency of updating bids are provided in the section Requirements for an app.

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 @_}));

Where can I get help if I encounter problems using the API?

If you could not find a comprehensive answer to your question in the documentation, contact the Yandex.Direct API support team.