Lesson 7. How to get data via the API

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.

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": {
              "LimitPercent": 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_ID]
    },
    "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": [GROUP_ID]
    },
    "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.

Useful links

Documentation: How the "get" method works

Questions

1. What is the purpose of the Yandex Direct Campaigns API service?

   It is used to manage ads.It is used to manage keywords.It is used to get ad group statistics.It is used to manage advertising campaigns.

   False.

   False.

   False.

   True.
2. Which method of the Campaigns service can you use to get data?

   updateCreateOrUpdateCampaigngetGetCampaignsParams

   False.

   False.

   True.

   False.
3. Why would you use paginated selection?

   It allows you to get objects in stages using multiple requests.Such selection allows you to send fewer requests to the API.Paginated selection is required for working with Sandbox.

   True.

   False.

   False.