--- metadata: - name: generator content: Diplodoc Platform v5.50.6 alternate: - https://yandex.ru/dev/direct/doc/en/keywords/get.md - https://yandex.ru/dev/direct/doc/ru/keywords/get.md sourcePath: ru/ref-v5/keywords/get.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/direct/doc/ru/llms.txt # get Возвращает параметры ключевых фраз или автотаргетингов, отвечающих заданным критериям: значения подстановочных переменных, статус и состояние, статистику показов и кликов и ставки. {% note alert %} Не рекомендуется запрашивать статистику показов и кликов для большого количества ключевых фраз: такие запросы могут обрабатываться значительно медленнее. {% endnote %} Ставки можно получить независимо от того, какая стратегия выбрана в кампании — ручная или автоматическая. ## Узнайте больше - [Как работает метод get](https://yandex.ru/dev/direct/doc/dg/best-practice/get.html) - [Автотаргетинг](https://yandex.ru/dev/direct/doc/dg/best-practice/auto-targeting.html) ## Ограничения {#restrictions} Метод возвращает не более 10 000 объектов. ## Запрос {#input} Структура запроса в формате JSON: ```javascript translate=no { "method": "get", "params": { /* params */ "SelectionCriteria": { /* KeywordsSelectionCriteria */ "Ids": [(long), ... ], "AdGroupIds": [(long), ... ], "CampaignIds": [(long), ... ], "States": [( "OFF" | "ON" | "SUSPENDED" ), ... ], "Statuses": [( "ACCEPTED" | "DRAFT" | "REJECTED"), ... ], "ServingStatuses": [( "ELIGIBLE" | "RARELY_SERVED" ), ... ], "ModifiedSince": (string) }, /* required */ "FieldNames": [( "Id" | "Keyword" | "State" | "Status" | "ServingStatus" | "AdGroupId" | "CampaignId" | "Bid" | "AutotargetingSearchBidIsAuto" | "ContextBid" | "StrategyPriority" | "UserParam1" | "UserParam2" | "Productivity" | "StatisticsSearch" | "StatisticsNetwork" | "AutotargetingCategories" ), ... ], /* required */ "AutotargetingSettingsCategoriesFieldNames" : [ ("Exact"|"Narrow"|"Alternative"|"Accessory"|"Broader") ], "AutotargetingSettingsBrandOptionsFieldNames" : [ ("WithoutBrands"|"WithAdvertiserBrand"|"WithCompetitorsBrand") ], "Page": { /* LimitOffset */ "Limit": (long), "Offset": (long) } } } ``` #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || **Структура params (для JSON) / GetRequest (для SOAP)** || || `SelectionCriteria` | KeywordsSelectionCriteria | Критерий отбора ключевых фраз и автотаргетингов. | Да || || `FieldNames` | array of KeywordFieldEnum | Имена параметров, которые требуется получить. {% note alert %} Не рекомендуется указывать параметры `StatisticsSearch` и `StatisticsNetwork`, если запрашиваются данные большого количества ключевых фраз: такие запросы могут обрабатываться значительно медленнее. {% endnote %} | Да || || `AutotargetingSettingsCategoriesFieldNames` | array of AutotargetingSettingsCategoriesFieldEnum | Категории таргетинга, которые требуется получить. | Нет || || `AutotargetingSettingsBrandOptionsFieldNames` | array of AutotargetingSettingsBrandOptionsFieldEnum | Настройки брендовости, которые требуется получить. | Нет || || `Page` | [LimitOffset](https://yandex.ru/dev/direct/doc/dg/best-practice/get.html#LimitOffset) | Структура, задающая страницу при [постраничной выборке](https://yandex.ru/dev/direct/doc/dg/best-practice/get.html) данных. | Нет || || **Структура KeywordsSelectionCriteria** || || `Ids` | array of long | Отбирать ключевые фразы и автотаргетинги с указанными идентификаторами. От 1 до 10 000 элементов в массиве. | Один из параметров `Ids`, `AdGroupIds` и `CampaignIds` (могут присутствовать все) || || `AdGroupIds` | array of long | Отбирать ключевые фразы и автотаргетинги указанных групп. От 1 до 1000 элементов в массиве. || || `CampaignIds` | array of long | Отбирать ключевые фразы и автотаргетинги указанных кампаний. От 1 до 10 элементов в массиве. || || `States` | array of KeywordStatusSelectionEnum | Отбирать ключевые фразы и автотаргетинги с указанными состояниями. См. [Статус и состояние фразы](https://yandex.ru/dev/direct/doc/dg/objects/keyword.html). | Нет || || `Statuses` | array of StatusEnum | Отбирать ключевые фразы и автотаргетинги с указанными статусами. См. [Статус и состояние фразы](https://yandex.ru/dev/direct/doc/dg/objects/keyword.html). | Нет || || `ServingStatuses` | array of ServingStatusEnum | Отбирать ключевые фразы и автотаргетинги с указанными статусами возможности показов группы объявлений. См. [Статус возможности показов группы](https://yandex.ru/dev/direct/doc/dg/objects/adgroup.html). | Нет || || `ModifiedSince` | string | Отбирать ключевые фразы и автотаргетинги, в которых были изменения начиная с указанной даты. Задается в формате `YYYY-MM-DDThh:mm:ssZ` (согласно ISO 8601), например `2015-05-24T23:59:59Z`. | Нет || |# ## Ответ {#output} {% note info %} В ответе присутствуют только параметры, которые были указаны во входном параметре `FieldNames`. {% endnote %} Структура ответа в формате JSON: ```javascript translate=no { "result": { /* result */ "Keywords": [{ /* KeywordGetItem */ "Id": (long), "Keyword": (string), "AdGroupId": (long), "CampaignId": (long), "UserParam1": (string), /* nillable */ "UserParam2": (string), /* nillable */ "Bid": (long), "AutotargetingSearchBidIsAuto" : ("YES"|"NO"), "ContextBid": (long), "StrategyPriority": "NORMAL", /* nillable */ "State": ( "OFF" | "ON" | "SUSPENDED" ), "Status": ( "ACCEPTED" | "DRAFT" | "REJECTED" | "UNKNOWN" ), "ServingStatus": ( "ELIGIBLE" | "RARELY_SERVED" ), "Productivity": null, "StatisticsSearch": { /* Statistics */ "Clicks": (long), /* required */ "Impressions": (long) /* required */ }, "StatisticsNetwork": { /* Statistics */ "Clicks": (long), /* required */ "Impressions": (long) /* required */ }, "AutotargetingCategories" : { /* nillable */ "Items" : [{ /* required */ "Category" : ("EXACT"|"ALTERNATIVE"|"COMPETITOR"|"BROADER"|"ACCESSORY") /* required */, "Value" : ("YES"|"NO") /* required */ }, ...], "AutotargetingSettings" : { /* nillable */ "Categories" : { "Exact" : ("YES"|"NO"), "Narrow" : ("YES"|"NO"), "Alternative" : ("YES"|"NO"), "Accessory" : ("YES"|"NO"), "Broader" : ("YES"|"NO") }, "BrandOptions" : { "WithoutBrands" : ("YES"|"NO"), "WithAdvertiserBrand" : ("YES"|"NO"), "WithCompetitorsBrand" : ("YES"|"NO") } } }, ... ], "LimitedBy": (long) } } } ``` #| || **Параметр** | **Тип** | **Описание** || || **Структура result (для JSON) / GetResponse (для SOAP)** || || `Keywords` | array of KeywordGetItem | Ключевые фразы и автотаргетинги. || || `LimitedBy` | long | Порядковый номер последнего возвращенного объекта. Передается в случае, если количество объектов в ответе было ограничено лимитом. См. раздел [Постраничная выборка](https://yandex.ru/dev/direct/doc/dg/best-practice/get.html). || || **Структура KeywordGetItem** || || `Id` | long | Идентификатор ключевой фразы или автотаргетинга. || || `AdGroupId` | long | Идентификатор группы объявлений, к которой относится ключевая фраза или автотаргетинг. || || `CampaignId` | long | Идентификатор кампании, к которой относится ключевая фраза или автотаргетинг. || || `Keyword` | string | Ключевая фраза. Может содержать минус-слова. Для автотаргетинга возвращается значение `---autotargeting`. || || `UserParam1` | string, nillable | Значение [подстановочной переменной](https://yandex.ru/dev/direct/doc/dg/objects/keyword.html)`{param1}`. Не более 255 символов. || || `UserParam2` | string, nillable | Значение [подстановочной переменной](https://yandex.ru/dev/direct/doc/dg/objects/keyword.html)`{param2}`. Не более 255 символов. || || `Bid` | long | Ставка на поиске. || || `AutotargetingSearchBidIsAuto` | YesNoEnum | Признак включения опции [автоматической ставки](https://yandex.ru/support/direct/impression-criteria/autotargeting.html#autotargeting__auto-bids). || || `ContextBid` | long | Ставка в сетях. || || `StrategyPriority` | PriorityEnum, nillable | Приоритет ключевой фразы или автотаргетинга: NORMAL. || || `Status` | StatusEnum | Статус ключевой фразы или автотаргетинга. Описание статусов см. в разделе [Статус и состояние фразы](https://yandex.ru/dev/direct/doc/dg/objects/keyword.html). || || `ServingStatus` | ServingStatusEnum | Статус возможности показов группы объявлений. Описание статусов см. в разделе [Статус возможности показов группы](https://yandex.ru/dev/direct/doc/dg/objects/adgroup.html). || || `State` | StateEnum | Состояние ключевой фразы или автотаргетинга. Описание состояний см. в разделе [Статус и состояние фразы](https://yandex.ru/dev/direct/doc/dg/objects/keyword.html). || || `Productivity` | Productivity, nillable | Параметр утратил актуальность, всегда возвращается значение null (nil). || || `StatisticsSearch` | Statistics | Статистика показов и кликов всех объявлений группы по данной ключевой фразе или автотаргетингу на поиске. Если в группе объявлений мало показов (значение RARELY_SERVED параметра `ServingStatus`), параметр не возвращается. || || `StatisticsNetwork` | Statistics | Статистика показов и кликов всех объявлений группы по данной фразе в сетях. Если в группе объявлений мало показов (значение RARELY_SERVED параметра `ServingStatus`), параметр не возвращается. || || `AutotargetingCategories` | AutotargetingCategories, nillable | Категории таргетинга. {% note alert %} Поле устарело и скоро перестанет поддерживаться. Для получения настроек таргетинга используйте структуру `AutotargetingSettings`. {% endnote %} || || `AutotargetingSettings` | AutotargetingSettings, nillable | Настройки таргетинга. || || **Структура Statistics** || || `Clicks` | long | Количество кликов по всем объявлениям группы, показанным по данной ключевой фразе или автотаргетингу. Рассчитывается за 28 дней от текущей даты. || || `Impressions` | long | Количество показов всех объявлений группы по данной фразе или автотаргетингу. Рассчитывается за 28 дней от текущей даты. || || **Структура AutotargetingCategories** || || `Category` | AutotargetingCategoriesEnum | Категория таргетинга: - EXACT — целевые запросы. Объявление точно отвечает на запросы пользователя; - ALTERNATIVE — альтернативные запросы. Пользователь ищет продукт, который можно заменить продвигаемым. При этом объявление также может удовлетворить запрос; - COMPETITOR — запросы с упоминанием конкурентов. Поиск продвигаемого продукта у конкурентов; - BROADER — широкие запросы. Запросы с интересом к продукту, примером которого является предложение; - ACCESSORY — сопутствующие запросы. Запросы по продуктам, которые могут быть интересны вместе с продвигаемым товаром или услугой. {% note alert %} Поле устарело и скоро перестанет поддерживаться. Настройки, заданные в веб-интерфейсе, сконвертируются в API по следующим правилам: #| || **Веб-интерфейс** | **API** || || Хотя бы одна включенная категория из набора «Целевые», «Узкие». | Включенная категория `EXACT`. || || Включенная опция упоминания брендов «Конкуренты» (если это единственная включенная опция упоминания брендов). | Включенная категория `COMPETITOR` + выключение остальных категорий. || || Включенная опция упоминания брендов «Конкуренты» (если это не единственная включенная опция упоминания брендов). | Включенная категория `COMPETITOR`. || || Выключенная опция упоминания брендов «Конкуренты». | Выключенная категория `COMPETITOR`. || |# {% endnote %} || || `Value` | YesNoEnum | Признак включения указанной категории таргетинга. По умолчанию включены все категории таргетинга. || || **Структура AutotargetingSettings** || || `Categories` | AutotargetingSettingsCategoriesFieldNames | Категории таргетинга. Доступные опции: - Exact – целевые запросы. Объявление точно отвечает на запросы пользователя. - Narrow – узкие запросы. Объявление шире, чем запросы пользователя. - Alternative – альтернативные запросы. Пользователь ищет продукт, который можно заменить продвигаемым. При этом объявление также может удовлетворить запрос. - Accessory – сопутствующие запросы. Запросы по продуктам, которые могут быть интересны вместе с продвигаемым товаром или услугой. - Broader – широкие запросы. Запросы с интересом к продукту, примером которого является предложение. || || `BrandOptions` | AutotargetingSettingsBrandOptionsFieldNames | Настройки брендовости. Доступные опции: - WithoutBrands – без упоминания брендов. - WithAdvertiserBrand – с упоминанием бренда пользователя. - WithCompetitorsBrand – с упоминанием брендов конкурентов. || |#