Lesson 7. How to get data via the API

In this lesson, you will learn:

  1. How to get objects
  2. Sandbox practice
  3. Task
  4. What's next
  5. Useful links
  6. Questions

In this lesson, you will learn about the API structure and look at some examples of getting data.

Let's remember how objects are linked in the Yandex.Direct API (see Lesson 1):



The API provides a service for each object class: Campaigns, for campaign management; Groups, for ad group management; Ads, for ad management, etc. For the full list of services please refer to the documentation.

The logic of working with the API objects is unified, with all the service methods assigned standard names. A service typically includes the following methods:

  • add — Adding objects.
  • update — Changing object parameters.
  • delete — Deleting objects.
  • get — Getting objects.

A service can also have other methods. For example, the Campaigns service provides the following methods:



How to get objects

Let's look how you can get ad campaign parameters using the get method.

The get method is designed so that you can request only the data you need. For example, for campaigns you can get their IDs and names only, rather than all their parameters. List the names of the parameters you need in the FieldNames input parameter.



Use the SelectionCriteria input structure to set criteria for selecting objects. If there are several selection criteria, the server searches for objects fitting all the criteria at once. Some services allow you to specify an empty SelectionCriteria structure: in this case, all objects are returned.

Sandbox practice

Let's remember the query example from the previous lesson. In that example, we got an entire list of campaigns by specifying an empty SelectionCriteria structure, getting only an ID and name for each campaign by specifying relevant parameters in FieldNames.

Attention. Don't forget to replace the token and IDs used in the samples with your data.
cURL
curl -k -H "Authorization: Bearer TOKEN" -d '{"method":"get","params":{"SelectionCriteria":{},"FieldNames":["Id","Name"]}}' https://api-sandbox.direct.yandex.com/json/v5/campaigns
cURL for Windows
curl -k -H "Authorization: Bearer TOKEN" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{},\"FieldNames\":[\"Id\",\"Name\"]}}" https://api-sandbox.direct.yandex.com/json/v5/campaigns
Request
{
  "method": "get",
  "params": {
    "SelectionCriteria": {},
    "FieldNames": ["Id", "Name"]
  }
}
Response
{
  "result": {
    "Campaigns": [{
      "Name": "Test API Sandbox campaign 1",
      "Id": 1234567
    }, {
      "Name": "Test API Sandbox campaign 2",
      "Id": 1234578
    }, {
      "Name": "Test API Sandbox campaign 3",
      "Id": 1234589
    }]
  }
}

Some campaign parameters (such as name and ID) are shared across all campaign types, while some of them (such as display strategies) depend on the campaign type. In the next sample, we only get campaigns of the “Text & Image Ads” type. To get display strategies for those campaigns, specify the relevant parameter name in the TextCampaignFieldNames input parameter.

cURL
curl -k -H "Authorization: Bearer TOKEN" -d '{"method":"get","params":{"SelectionCriteria":{ "Types": ["TEXT_CAMPAIGN"]},"FieldNames":["Id","Name"],"TextCampaignFieldNames":["BiddingStrategy"]}}' https://api-sandbox.direct.yandex.com/json/v5/campaigns
cURL for Windows
curl -k -H "Authorization: Bearer TOKEN" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{ \"Types\": [\"TEXT_CAMPAIGN\"]},\"FieldNames\":[\"Id\",\"Name\"],\"TextCampaignFieldNames\":[\"BiddingStrategy\"]}}" https://api-sandbox.direct.yandex.com/json/v5/campaigns
Request
{
  "method": "get",
  "params": {
    "SelectionCriteria": {
      "Types": ["TEXT_CAMPAIGN"]
    },
    "FieldNames": ["Id", "Name"],
    "TextCampaignFieldNames": ["BiddingStrategy"]
  }
}
Response
{
  "result": {
    "Campaigns": [{
      "Id": 1234567,
      "Name": "Test API Sandbox campaign 1",
      "TextCampaign": {
        "BiddingStrategy": {
          "Search": {
            "BiddingStrategyType": "HIGHEST_POSITION"
          }, 
          "Network": {
            "BiddingStrategyType":"NETWORK_DEFAULT",
            "NetworkDefault": {
              "BidPercent": 100
            }
          } 
        }
      }
    }]
  }
}
Paginated selection
If you are working with large data arrays, all the objects might not fit in a single request response, since the get method returns a maximum of 10,000 objects. In this case, the get method returns the LimitedBy parameter with a sequential number of the last object returned. If the response contains this parameter, it indicates that you haven't got all the objects yet.
To set up paginated selection parameters, use the Page input structure. Specify the number of objects to select (for example, 10) and the number of objects to be skipped before the selection (for example, 20); as a result, you will get a range of data, i.e., 10 objects from 21st to 30th.

Task

We have prepared some samples for other services as well. Try to reproduce these requests in Sandbox.

AdGroups service

Get a list of ad groups for a campaign.

cURL
curl -k -H "Authorization: Bearer TOKEN" -d '{"method":"get","params":{"SelectionCriteria":{"CampaignIds":[CAMPAIGN_IDENTIFIER]},"FieldNames":["Id","Name","Status","Type"]}}' https://api-sandbox.direct.yandex.com/json/v5/adgroups
cURL for Windows
curl-k-H "Authorization: Bearer token" - d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{\"CampaignIds\":[CAMPAIGN_IDENTIFIER]},\"FieldNames\":[\"Id\",\"Name\",\"Status\",\"Type\"]}}" https://api-sandbox.direct.yandex.com/json/v5/adgroups
Request
{
  "method": "get",
  "params": {
    "SelectionCriteria": {
      "CampaignIds": [CAMPAIGN_IDENTIFIER]
    },
    "FieldNames": ["Id", "Name", "Status", "Type"]
  }
}
Response
{
  "result": {
    "AdGroups": [{
      "Status": "ACCEPTED",
      "Name": "Group # 1296502",
      "Id": 1296502,
      "Type": "TEXT_AD_GROUP"
    }, {
      "Name": "Group # 1296517",
      "Status": "DRAFT",
      "Id": 1296517,
      "Type": "TEXT_AD_GROUP"
    }]
  }
}
Ads service

Get the list of ads in an ad group.

cURL
curl -k -H "Authorization: Bearer TOKEN" -d '{"method":"get","params":{"SelectionCriteria":{"AdGroupIds":[AD_GROUP_IDENTIFIER]},"FieldNames":["Id","State","Status","Type"]}}'  https://api-sandbox.direct.yandex.com/json/v5/ads
cURL for Windows
curl -k -H "Authorization: Bearer TOKEN" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{\"AdGroupIds\":[AD_GROUP_IDENTIFIER]},\"FieldNames\":[\"Id\",\"State\",\"Status\",\"Type\"]}}" https://api-sandbox.direct.yandex.com/json/v5/ads
Request
{
  "method": "get",
  "params": {
    "SelectionCriteria": {
      "AdGroupIds": [AD_GROUP_IDENTIFIER]
    },
    "FieldNames": ["Id", "State", "Status", "Type"]
  }
}
Response
{
  "result": {
    "Ads": [{
      "State": "ON",
      "Id": 1381459,
      "Status": "ACCEPTED",
      "Type": "TEXT_AD"
    }, {
      "Type": "TEXT_AD",
      "Status": "DRAFT",
      "Id": 1381470,
      "State": "OFF"
    }]
  }
}

Get parameters of a single ad.

cURL
curl -k -H "Authorization: Bearer TOKEN" -d '{"method":"get","params":{"SelectionCriteria":{"Ids":[AD_IDENTIFIER]},"FieldNames":["Id"],"TextAdFieldNames":["Text","Title","Href","VCardId"]}}' https://api-sandbox.direct.yandex.com/json/v5/ads
cURL for Windows
curl -k -H "Authorization: Bearer TOKEN" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{\"Ids\":[AD_IDENTIFIER]},\"FieldNames\":[\"Id\"],\"TextAdFieldNames\":[\"Text\",\"Title\",\"Href\",\"VCardId\"]}}" https://api-sandbox.direct.yandex.com/json/v5/ads
Request
{
  "method": "get",
  "params": {
    "SelectionCriteria": {
      "Ids": [1381459]
    },
    "FieldNames": ["Id"],
    "TextAdFieldNames": ["Text", "Title", "Href", "VCardId"]
  }
}
Response
{
  "result": {
    "Ads": [{
      "Id": 1381459,
      "TextAd": {
        "Title": "Test sandbox banner 5",
        "Href": "http://www.yandex.ru",
        "VCardId": 171518,
        "Text": "Test sandbox banner 5 text"
      }
    }]
  }
}
Keywords service

Get keywords for an ad group.

cURL
curl -k -H "Authorization: Bearer TOKEN" -d '{"method":"get","params":{"SelectionCriteria":{"AdGroupIds":[AD_GROUP_IDENTIFIER]},"FieldNames":["Id","Keyword","Bid","State","Status"]}}' https://api-sandbox.direct.yandex.com/json/v5/keywords
cURL for Windows
curl -k -H "Authorization: Bearer TOKEN" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{\"AdGroupIds\":[AD_GROUP_IDENTIFIER]},\"FieldNames\":[\"Id\",\"Keyword\",\"Bid\",\"State\",\"Status\"]}}" https://api-sandbox.direct.yandex.com/json/v5/keywords
Request
{
  "method": "get",
  "params": {
    "SelectionCriteria": {
      "AdGroupIds": [1296506]
    },
    "FieldNames": ["Id", "Keyword", "Bid", "State", "Status"]
  }
}
Response
{
  "result": {
    "Keywords": [{
      "State": "ON",
      "Keyword": "test keyword 5.1",
      "Status": "ACCEPTED",
      "Bid": 7700000,
      "Id": 3458327
    }, {
      "Keyword": "New keyword",
      "Id": 3458351,
      "Bid": 400000,
      "Status": "ACCEPTED",
      "State": "ON"
    }]
  }
}

What's next

So, you have learned how to use the get method. In the next lesson, you will learn about the methods that change the data.

Questions

  1. What is the purpose of the Yandex.Direct Campaigns API service?
    False.
    False.
    False.
    True.
  2. Which method of the Campaigns service can you use to get data?
    False.
    False.
    True.
    False.
  3. Why would you use paginated selection?
    True.
    False.
    False.