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.
- If errors occur in relation with the limit on the number of requests, the app must stop making requests.
- 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.
- 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 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
- 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.