Requirements for an app
This section contains requirements and recommendations for apps that interact with the Yandex.Direct API.
General requirements. Error handling
- The app must record all requests sent to the Yandex.Direct API and store logs of API requests and responses for at least the previous 3 days.
- The app must control and handle errors in accessing the API. The app must not send repeated invalid requests.
- The app must control the number of simultaneous API requests from a single user (point 1 in Technical limitations).
- The app must control the total number of calls of each method from a single user per day (point 2 in Technical limitations).
- If errors occur in relation with the limit on the number of requests, the app must stop making requests.
- Before calling methods that have point-based restrictions (see the section Point limitations), the app must check that points are available using the GetClientsUnits method.
- In general, the SetAutoPrice method should be used for setting bids. Always use the SetAutoPrice method for setting unified bids for an array of keywords or banners, and for setting bids that are equal to the price for displaying in a particular position with a certain markup.
- The number of SetAutoPrice calls should be minimized. The optimal number of calls is no more than once per hour and no more than 10 times per day for each campaign.
- If the app implements its own logic for changing bids that cannot be implemented using the SetAutoPrice method, bids may be set using the UpdatePrices method.
- The number of UpdatePrices calls should be minimized. To achieve this, put the maximum number of keywords in each method call, including those that belong to different ads or ad groups in the same campaign (but following the restrictions listed in point 3 in Technical limitations).
- When calling the UpdatePrices method, use the keyword identifiers (PhraseID) that have been previously saved in the cache, rather than getting keyword IDs before setting a bid each time.
- We recommend varying the frequency of bid setting depending on the priority of campaigns and ads (groups). See Prioritizing.
- You should not continue changing bids for campaigns that are stopped or that have run out of funds.
Updating the cache
- Parameters of campaigns, ads (groups), and keywords that are obtained from the server should be saved in a cache (in a local database, in memory, in files on a disk, and so on).
- Before updating the data in the cache, use the GetChanges method to check for changes. You should only get data from the Yandex.Direct API server again for campaigns and ads (ad groups) that have been changed since the last cache update.
- To get a list of campaigns, use the GetCampaignsList method; to get campaign parameters, use the GetCampaignsParams method. The optimal number of calls is once per hour (or less).
- To get parameters for ads, use the GetBanners method with the parameter GetPhrases = "Yes" (getting a reduced set of parameters, without auction results). If there are a large number of keywords, call the GetBanners method with the GetPhrases = "No" parameter, then get keywords using the GetBannerPhrasesFilter method (see 5).
If there are a large number of ads in a campaign (about 1000 or more), use the parameters Limit/Offset when getting ads.
- To get keywords, use the GetBannerPhrasesFilter method and list the set of parameters to get in the FieldsNames parameter (for example, FieldsNames = ["PhraseID","BannerID","Phrase","Price","ContextPrice","AutoBudgetPriority"], and set the ad IDs in the BannerIDS parameter (the optimal number is from 100 to 300).
- For high-priority campaigns or ads (ad groups), the cache may be updated more often (see Prioritizing ).
We recommend dividing campaigns, groups, ads and/or keywords into high-priority and low-priority groups. For example, high priority can be assigned to more active and important campaigns with a large number of clicks or a high CPC.
Priorities can be set manually by the user or assigned automatically using a specific algorithm, such as based on statistics for clicks and impressions.
- High-priority objects are allowed to set bids and update the cache more frequently (provided that you follow point 3).
- For low-priority objects, reduce the frequency of setting bids and updating the cache to one or two times per day.
Control for expenditure statistics
- Use the GetSummaryStat method to get summary statistics for a campaign by days or for a period. The optimal call frequency is a maximum of 5 times per hour for each campaign.
- To get statistics for ads and keywords, use the GetBannersStat (Live) method. The optimal call frequency is once per hour for each campaign (or less).
- The CreateNewReport method should be used only for getting statistics filtered by display regions, platforms, display position, or reaching Yandex.Metrica goals. In addition, the report period should be limited to the minimal value possible (for example, one or two days). The optimal call frequency is a maximum of 5 times per day for each campaign.
- If you need to get multiple reports using the CreateNewReport method, start generating the maximum number of reports at once (with consideration for the restrictions given in point 6 in Technical limitations). This speeds up processing the request queue. As reports become available, you should download them, delete them from the server (DeleteReport method) and start generating the next report.
- Check report readiness (GetReportList method) 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.
- If highly precise statistics are needed with consideration for corrections, use the GetChanges method for checking for corrections to statistics. You should only get the statistics again for those campaigns and periods that had corrected statistics.
Budget forecasting and keyword selection
- Reports generated using the CreateNewForecast and CreateNewWordstatReport methods are intended for expanding and more precisely defining clients' advertising campaigns in Yandex.Direct. Do not generate these reports for other purposes.
- If you need to get multiple reports, start generating the maximum number of reports at once (with consideration for the restrictions given in point 6 in Technical limitations). This speeds up processing the request queue. As reports become available, you should download them (GetForecast and GetWordstatReport methods), delete them from the server (DeleteForecastReport and DeleteWordstatReport methods) and start generating the next reports.
- Check report readiness (GetForecastList and GetWordstatReportList methods) in a single thread, no more than once every 10-30 seconds.
- Before calling the CreateNewWordstatReport and GetKeywordsSuggestion methods, the app must check that points are available using the GetClientsUnits method (see the section Балльные ограничения).