Lesson 10. How to efficiently use the API: restrictions and recommendations

In this lesson, you will learn:

  1. How to find points spent and point balance
  2. How to optimize your points spending
  3. How to track changes using the Changes service
  4. Task
  5. Useful links
  6. Questions

In this lesson, you will learn what restrictions apply to the Yandex.Direct API and how you can run your app efficiently in view of those restrictions.

Various types of restrictions are applied to balance the load on the API server. A maximum of 5 concurrent requests can be run on behalf of a single advertiser. Each method limits the number of objects per request. Also, the API applies a point-based system.

Each advertiser (or an agency) is granted an individual limit of points per day. Points are granted in regular intervals throughout the day. Points are deducted per calling a method, per changing or getting an object, or per error in a request. If you do not have enough points, you cannot make API requests.



How to find points spent and point balance

In response to each request, the API server sends the HTTP Units header that indicates the number of points:

Units: spent on request/available points/daily limit.

Response example
HTTP/1.1 200 OK
Connection:close
Content-Type:application/json
Date:Fri, 28 Jun 2018 17:07:02 GMT
RequestId: 1111111111111111112
Units: 10/20828/64000
Server:nginx
Transfer-Encoding:chunked

{
  "result": {
    ...
  }
}
  • RequestId — request identifier.
  • Units — number of points.
Note. If a request to the API is made on behalf of the agency, the advertiser's points are spent by default. However, the agency can choose to spend their points instead of the advertiser's points.

How to optimize your points spending

We recommend that you store all the data used by the app in the cache, for example, in the local database. Having got the parameters of campaigns, groups, ads, keywords, as well as reference lists of regions and time zones, from the server, you can use the methods of the Changes service to track whether they are up-to-date. Before updating the cached data, please check for changes. You need not get objects from the server again, unless they have actually changed. This way you can reduce the amount of data transmitted, speed up your app, and reduce the point spending.

How to track changes using the Changes service

1. At the first launch of your app, call the checkDictionaries method of the Changes service, without any parameters. In the response, you will get the Timestamp parameter with the current UTC time set on the server.

cURL
curl -k -H "Authorization: Bearer TOKEN" -d '{"method":"checkDictionaries","params":{}}' https://api.direct.yandex.com/json/v5/changes
cURL for Windows
curl -k -H "Authorization: Bearer TOKEN" -d "{\"method\":\"checkDictionaries\",\"params\":{}}" https://api.direct.yandex.com/json/v5/changes
Request
{
  "method": "checkDictionaries",
  "params": { }
}
Response
{
  "result": {
    "Timestamp": "2018-06-03T12:48:27Z"
  } 
}

2. To get a list of campaigns changed, call method checkCampaigns. In each next call, specify Timestamp retrieved by the previous call: this ensures absense of gaps between the change check intervals.

cURL
curl -k -H "Authorization: Bearer TOKEN" -d '{"method":"checkCampaigns","params":{"Timestamp":"2018-06-03T12:48:27Z"}}' https://api.direct.yandex.com/json/v5/changes
cURL for Windows
curl -k -H "Authorization: Bearer TOKEN" -d "{\"method\":\"checkCampaigns\",\"params\":{\"Timestamp\":\"2018-06-03T12:48:27Z\"}}" https://api.direct.yandex.com/json/v5/changes
Request
{
  "method": "checkCampaigns",
  "params": {
    "Timestamp": "2018-06-03T12:48:27Z"
  }
}
Response
{
  "result": {
    "Timestamp": "2018-07-01T13:11:27Z",
    "Campaigns": [{
      "CampaignId": 136200,
      "ChangesIn": [ "SELF", "CHILDREN" ]
    }, {
      "CampaignId": 136201,
      "ChangesIn": [ "STAT" ]
    }]
  }
}

The method returns the IDs of the campaigns that were changed. The ChangesIn parameter specifies where the changes were made:

  • SELF — In campaign parameters.
  • CHILDREN — In child objects: ad groups, ads, or keywords.
  • STAT — Campaign statistics corrected (usually due to filtering out false clicks).

3. If the checkCampaigns method shows that the child objects have changed, get more details of the changes using the check method.

cURL
curl -k -H "Authorization: Bearer TOKEN" -d '{"method":"check","params": {"Timestamp":"2018-06-03T12:48:27Z","CampaignIds": [136200],"FieldNames": ["AdGroupIds","AdIds"]}}'  https://api.direct.yandex.com/json/v5/changes
cURL for Windows
curl -k -H "Authorization: Bearer TOKEN" -d "{\"method\":\"check\",\"params\": {\"Timestamp\":\"2018-06-03T12:48:27Z\",\"CampaignIds\": [136200],\"FieldNames\": [\"AdGroupIds\",\"AdIds\"]}}" https://api.direct.yandex.com/json/v5/changes
Request
{
  "method": "check",
  "params": {
    "CampaignIds": [136200],
    "FieldNames": ["AdGroupIds","AdIds"],
    "Timestamp": "2018-06-03T12:48:27Z"
  }
}
Response
{
  "result": {
    "Timestamp": "2018-07-01T13:12:22Z",
    "Modified": {
      "AdGroupIds": [22222222],
      "AdIds": [33333333,33333334]      
    }
  }
}
Attention. If the check method shows that an ad group has changed (the ad group ID is specified in the AdGroupIds array), this could mean a change either in the ad group parameters or in the keywords.

Use the get methods of the applicable services (Campaigns, AdGroups, Ads or Keywords) to get the changed objects from the server.

Task

  1. Create a new campaign, ad group, and ad in Sandbox.
  2. Use the moderate method of the Ads service to submit the ad for moderation.
  3. Get data of all the campaigns.
  4. Get data on changes in all the campaigns.
  5. Use the check method to find out which ads have changed (the status of the ad sent for moderation should have changed).
  6. Get the titles and texts of the ads accepted at ad moderation.
  7. See how many points you have spent on those requests.

Every aspect of working with Yandex.Direct API is detailed in the documentation.

Good luck!

Questions

  1. How many concurrent requests can an app make on behalf of a single advertiser?
    False.
    True.
    False.
    False.
  2. Does an app need to take into account how many points are available to the user?
    False.
    True.
    False.
  3. Which methods can you use to optimize point spending by the app?
    False.
    True.
    False.