---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.2
alternate:
  - https://yandex.com/dev/direct/doc/dg-v4/en/concepts/requirements.md
  - https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/requirements.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/direct/doc/dg-v4/en/llms.txt

# Requirements for an app

This section contains requirements and recommendations for apps that interact with the Yandex Direct API.


## General requirements. Error handling {#general}

1. 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.
1. The app must control and handle errors in accessing the API. The app must not send repeated invalid requests.
1. The app must control the number of simultaneous API requests from a single user (point [1](https://yandex.com/dev/direct/doc/dg-v4/en/concepts/Restrictions.md#simult) in [Technical limitations](https://yandex.com/dev/direct/doc/dg-v4/en/concepts/Restrictions.md#Technical)).
1. The app must control the total number of calls of each method from a single user per day (point [2](https://yandex.com/dev/direct/doc/dg-v4/en/concepts/Restrictions.md#calls-per-day) in [Technical limitations](https://yandex.com/dev/direct/doc/dg-v4/en/concepts/Restrictions.md#Technical)).
1. If errors occur in relation with the limit on the number of requests, the app must stop making requests.
1. Before calling methods that have point-based restrictions (see the section [Point limitations](https://yandex.com/dev/direct/doc/dg-v4/en/concepts/Restrictions.md#Units)), the app must check that points are available using the [GetClientsUnits](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetClientsUnits.md) method.


## Setting bids {#bids}

1. In general, the [SetAutoPrice](https://yandex.com/dev/direct/doc/dg-v4/en/reference/SetAutoPrice.md) method should be used for setting bids. Always use the [SetAutoPrice](https://yandex.com/dev/direct/doc/dg-v4/en/reference/SetAutoPrice.md) 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.
1. The number of [SetAutoPrice](https://yandex.com/dev/direct/doc/dg-v4/en/reference/SetAutoPrice.md) 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.
1. If the app implements its own logic for changing bids that cannot be implemented using the [SetAutoPrice](https://yandex.com/dev/direct/doc/dg-v4/en/reference/SetAutoPrice.md) method, bids may be set using the [UpdatePrices](https://yandex.com/dev/direct/doc/dg-v4/en/reference/UpdatePrices.md) method.
1. The number of [UpdatePrices](https://yandex.com/dev/direct/doc/dg-v4/en/reference/UpdatePrices.md) 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](https://yandex.com/dev/direct/doc/dg-v4/en/concepts/Restrictions.md#max-input) in [Technical limitations](https://yandex.com/dev/direct/doc/dg-v4/en/concepts/Restrictions.md#Technical)).
1. When calling the [UpdatePrices](https://yandex.com/dev/direct/doc/dg-v4/en/reference/UpdatePrices.md) method, use the keyword identifiers (`PhraseID`) that have been previously saved in the [cache](#cache), rather than getting keyword IDs before setting a bid each time.
1. We recommend varying the frequency of bid setting depending on the priority of campaigns and ads (groups). See [Prioritizing](#priority).
1. You should not continue changing bids for campaigns that are stopped or that have run out of funds.


## Updating the cache {#cache}

1. 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).
1. Before updating the data in the cache, use the [GetChanges](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetChanges.md) 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.
1. To get a list of campaigns, use the [GetCampaignsList](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetCampaignsList.md) method; to get campaign parameters, use the [GetCampaignsParams](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetCampaignsParams.md) method. The optimal number of calls is once per hour (or less).
1. To get parameters for ads, use the [GetBanners](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetBanners.md) 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](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetBanners.md) method with the `GetPhrases = "No"` parameter, then get keywords using the [GetBannerPhrasesFilter](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetBannerPhrasesFilter.md) method (see [5](#get-phrases)).
    If there are a large number of ads in a campaign (about 1000 or more), use the parameters `Limit`/`Offset` when getting ads.
    
1. To get keywords, use the [GetBannerPhrasesFilter](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetBannerPhrasesFilter.md) 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).
1. For high-priority campaigns or ads (ad groups), the cache may be updated more often (see [Prioritizing](#priority) ).


## Prioritizing {#priority}

1. 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.
    
1. High-priority objects are allowed to set bids and update the cache more frequently (provided that you follow point [3](#low-priority)).
1. 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 {#expenses}

1. Use the [GetSummaryStat](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetSummaryStat.md) 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.
1. To get statistics for ads and keywords, use the [GetBannersStat (Live)](https://yandex.com/dev/direct/doc/dg-v4/en/live/GetBannersStat.md) method. The optimal call frequency is once per hour for each campaign (or less).
1. The [CreateNewReport](https://yandex.com/dev/direct/doc/dg-v4/en/reference/CreateNewReport.md) 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.
1. If you need to get multiple reports using the [CreateNewReport](https://yandex.com/dev/direct/doc/dg-v4/en/reference/CreateNewReport.md) method, start generating the maximum number of reports at once (with consideration for the restrictions given in point [6](https://yandex.com/dev/direct/doc/dg-v4/en/concepts/Restrictions.md#reports) in [Technical limitations](https://yandex.com/dev/direct/doc/dg-v4/en/concepts/Restrictions.md#Technical)). This speeds up processing the request queue. As reports become available, you should download them, delete them from the server ([DeleteReport](https://yandex.com/dev/direct/doc/dg-v4/en/reference/DeleteReport.md) method) and start generating the next report.
1. Check report readiness ([GetReportList](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetReportList.md) 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.
1. If highly precise statistics are needed with consideration for corrections, use the [GetChanges](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetChanges.md) 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 {#forecast}

1. Reports generated using the [CreateNewForecast](https://yandex.com/dev/direct/doc/dg-v4/en/reference/CreateNewForecast.md) and [CreateNewWordstatReport](https://yandex.com/dev/direct/doc/dg-v4/en/reference/CreateNewWordstatReport.md) methods are intended for expanding and more precisely defining clients' advertising campaigns in Yandex Direct. Do not generate these reports for other purposes.
1. 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](https://yandex.com/dev/direct/doc/dg-v4/en/concepts/Restrictions.md#reports) in [Technical limitations](https://yandex.com/dev/direct/doc/dg-v4/en/concepts/Restrictions.md#Technical)). This speeds up processing the request queue. As reports become available, you should download them ([GetForecast](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetForecast.md) and [GetWordstatReport](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetWordstatReport.md) methods), delete them from the server ([DeleteForecastReport](https://yandex.com/dev/direct/doc/dg-v4/en/reference/DeleteForecastReport.md) and [DeleteWordstatReport](https://yandex.com/dev/direct/doc/dg-v4/en/reference/DeleteWordstatReport.md) methods) and start generating the next reports.
1. Check report readiness ([GetForecastList](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetForecastList.md) and [GetWordstatReportList](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetWordstatReportList.md) methods) in a single thread, no more than once every 10-30 seconds.
1. Before calling the [CreateNewWordstatReport](https://yandex.com/dev/direct/doc/dg-v4/en/reference/CreateNewWordstatReport.md) and [GetKeywordsSuggestion](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetKeywordsSuggestion.md) methods, the app must check that points are available using the [GetClientsUnits](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetClientsUnits.md) method (see the section [Балльные ограничения](https://yandex.com/dev/direct/doc/dg-v4/en/concepts/Restrictions.md#Units)).


## Dictionary data {#dictionary}

1. The list of regions ([GetRegions](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetRegions.md) method) and list of time zones ([GetTimeZones](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetTimeZones.md) method) should be requested from the server one time and saved in the cache.
1. Before updating the data in the cache, use the [GetChanges](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetChanges.md) method to check for changes. This check should be made no more than once per day.