--- metadata: - name: generator content: Diplodoc Platform v5.50.6 alternate: - https://yandex.ru/dev/direct/doc/en/get.md - https://yandex.ru/dev/direct/doc/ru/get.md sourcePath: en/start/get.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/direct/doc/en/llms.txt # 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): ![](_assets/intro_objects_scheme.png) The API provides a service for each object class: `Campaigns` for managing campaigns, `AdGroups` for managing ad groups, `Ads` for managing ads, and others. You can find the full list of services in 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: ![](_assets/get_methods.png) ## How to get objects {#get_get_obj} Let's look at how you can get 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. ![](_assets/get_params.png) 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 {#get_training} Let's remember a 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`. {% note alert %} Don't forget to change the token and IDs used in the examples to your own data. {% endnote %} **cURL**   ```text translate=no curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"get","params":{"SelectionCriteria":{},"FieldNames":["Id","Name"]}}' https://api-sandbox.direct.yandex.com/json/v5/campaigns ``` **cURL for Windows**   ```text translate=no curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{},\"FieldNames\":[\"Id\",\"Name\"]}}" https://api-sandbox.direct.yandex.com/json/v5/campaigns ``` **Request**   ```text translate=no { "method": "get", "params": { "SelectionCriteria": {}, "FieldNames": ["Id", "Name"] } } ``` **Response**   ```text translate=no { "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 following example, we only get campaigns with the "Text & Image Ads" type. To get display strategies for those campaigns, specify the relevant parameter name in the `TextCampaignFieldNames` input parameter . **cURL**   ```text translate=no curl -k -H "Authorization: Bearer ТОКЕН" -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**   ```text translate=no curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{ \"Types\": [\"TEXT_CAMPAIGN\"]},\"FieldNames\":[\"Id\",\"Name\"],\"TextCampaignFieldNames\":[\"BiddingStrategy\"]}}" https://api-sandbox.direct.yandex.com/json/v5/campaigns ``` **Request**   ```text translate=no { "method": "get", "params": { "SelectionCriteria": { "Types": ["TEXT_CAMPAIGN"] }, "FieldNames": ["Id", "Name"], "TextCampaignFieldNames": ["BiddingStrategy"] } } ``` **Response**   ```text translate=no { "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 you get this parameter, this indicates that not all objects were received.   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 {#get_task} We have prepared several examples for other services as well. Try to reproduce the relevant requests in the Sandbox. **AdGroups Service**   Get a list of ad groups from a campaign. {% cut "cURL" %} ```text translate=no curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"get","params":{"SelectionCriteria":{"CampaignIds":[ИДЕНТИФИКАТОР_КАМПАНИИ]},"FieldNames":["Id","Name","Status","Type"]}}' https://api-sandbox.direct.yandex.com/json/v5/adgroups ``` {% endcut %} {% cut "cURL for Windows" %} ```text translate=no curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{\"CampaignIds\":[ИДЕНТИФИКАТОР_КАМПАНИИ]},\"FieldNames\":[\"Id\",\"Name\",\"Status\",\"Type\"]}}" https://api-sandbox.direct.yandex.com/json/v5/adgroups ``` {% endcut %} {% cut "Request" %} ```text translate=no { "method": "get", "params": { "SelectionCriteria": { "CampaignIds": [ИДЕНТИФИКАТОР_КАМПАНИИ] }, "FieldNames": ["Id", "Name", "Status", "Type"] } } ``` {% endcut %} {% cut "Response" %} ```text translate=no { "result": { "AdGroups": [{ "Status": "ACCEPTED", "Name": "Группа №1296502", "Id": 1296502, "Type": "TEXT_AD_GROUP" }, { "Name": "Группа №1296517", "Status": "DRAFT", "Id": 1296517, "Type": "TEXT_AD_GROUP" }] } } ``` {% endcut %} **Service Ads**   Get the list of ads in an ad group. {% cut "cURL" %} ```text translate=no curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"get","params":{"SelectionCriteria":{"AdGroupIds":[ИДЕНТИФИКАТОР_ГРУППЫ]},"FieldNames":["Id","State","Status","Type"]}}' https://api-sandbox.direct.yandex.com/json/v5/ads ``` {% endcut %} {% cut "cURL for Windows" %} ```text translate=no curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{\"AdGroupIds\":[ИДЕНТИФИКАТОР_ГРУППЫ]},\"FieldNames\":[\"Id\",\"State\",\"Status\",\"Type\"]}}" https://api-sandbox.direct.yandex.com/json/v5/ads ``` {% endcut %} {% cut "Request" %} ```text translate=no { "method": "get", "params": { "SelectionCriteria": { "AdGroupIds": [ИДЕНТИФИКАТОР_ГРУППЫ] }, "FieldNames": ["Id", "State", "Status", "Type"] } } ``` {% endcut %} {% cut "Response" %} ```text translate=no { "result": { "Ads": [{ "State": "ON", "Id": 1381459, "Status": "ACCEPTED", "Type": "TEXT_AD" }, { "Type": "TEXT_AD", "Status": "DRAFT", "Id": 1381470, "State": "OFF" }] } } ``` {% endcut %} Get parameters of a single ad. {% cut "cURL" %} ```text translate=no curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"get","params":{"SelectionCriteria":{"Ids":[ИДЕНТИФИКАТОР_ОБЪЯВЛЕНИЯ]},"FieldNames":["Id"],"TextAdFieldNames":["Text","Title","Href","VCardId"]}}' https://api-sandbox.direct.yandex.com/json/v5/ads ``` {% endcut %} {% cut "cURL for Windows" %} ```text translate=no curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{\"Ids\":[ИДЕНТИФИКАТОР_ОБЪЯВЛЕНИЯ]},\"FieldNames\":[\"Id\"],\"TextAdFieldNames\":[\"Text\",\"Title\",\"Href\",\"VCardId\"]}}" https://api-sandbox.direct.yandex.com/json/v5/ads ``` {% endcut %} {% cut "Request" %} ```text translate=no { "method": "get", "params": { "SelectionCriteria": { "Ids": [1381459] }, "FieldNames": ["Id"], "TextAdFieldNames": ["Text", "Title", "Href", "VCardId"] } } ``` {% endcut %} {% cut "Response" %} ```text translate=no { "result": { "Ads": [{ "Id": 1381459, "TextAd": { "Title": "Test sandbox banner 5", "Href": "http://www.yandex.ru", "VCardId": 171518, "Text": "Test sandbox banner 5 text" } }] } } ``` {% endcut %} **Keywords service**   Get keywords for an ad group. {% cut "cURL" %} ```text translate=no curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"get","params":{"SelectionCriteria":{"AdGroupIds":[ИДЕНТИФИКАТОР_ГРУППЫ]},"FieldNames":["Id","Keyword","Bid","State","Status"]}}' https://api-sandbox.direct.yandex.com/json/v5/keywords ``` {% endcut %} {% cut "cURL for Windows" %} ```text translate=no curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{\"AdGroupIds\":[ИДЕНТИФИКАТОР_ГРУППЫ]},\"FieldNames\":[\"Id\",\"Keyword\",\"Bid\",\"State\",\"Status\"]}}" https://api-sandbox.direct.yandex.com/json/v5/keywords ``` {% endcut %} {% cut "Request" %} ```text translate=no { "method": "get", "params": { "SelectionCriteria": { "AdGroupIds": [1296506] }, "FieldNames": ["Id", "Keyword", "Bid", "State", "Status"] } } ``` {% endcut %} {% cut "Response" %} ```text translate=no { "result": { "Keywords": [{ "State": "ON", "Keyword": "test keyword 5.1", "Status": "ACCEPTED", "Bid": 7700000, "Id": 3458327 }, { "Keyword": "Новая фраза", "Id": 3458351, "Bid": 400000, "Status": "ACCEPTED", "State": "ON" }] } } ``` {% endcut %} ## What's next {#get_whats_now} So, you have learned how to use the `get` method. In the next lesson, you will learn about the methods that change the data.