get

Возвращает параметры ключевых фраз или автотаргетингов, отвечающих заданным критериям: значения подстановочных переменных, статус и состояние, статистику показов и кликов, ставки и приоритеты.

  1. Ограничения
  2. Запрос
  3. Ответ
Внимание. Не рекомендуется запрашивать статистику показов и кликов для большого количества ключевых фраз: такие запросы могут обрабатываться значительно медленнее.

Ставки или приоритеты можно получить независимо от того, какая стратегия выбрана в кампании — ручная или автоматическая.

Внимание.
  • Ставки и цены передаются через API Директа в виде целых чисел. Передаваемое значение представляет собой ставку или цену, умноженную на 1 000 000.

  • Все ставки и цены указываются в валюте рекламодателя.

Ограничения

Метод возвращает не более 10 000 объектов.

Получение фраз из архивных кампаний недоступно.

Запрос

Структура запроса в формате JSON:

{
  "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

Имена параметров, которые требуется получить.

Внимание. Не рекомендуется указывать параметры StatisticsSearch и StatisticsNetwork, если запрашиваются данные большого количества ключевых фраз: такие запросы могут обрабатываться значительно медленнее.
Да
AutotargetingSettingsCategoriesFieldNames array of AutotargetingSettingsCategoriesFieldEnum

Категории таргетинга, которые требуется получить.

Нет
AutotargetingSettingsBrandOptionsFieldNames array of AutotargetingSettingsBrandOptionsFieldEnum

Настройки брендовости, которые требуется получить.

Нет
Page LimitOffset

Структура, задающая страницу при постраничной выборке данных.

Нет
Структура 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 Отбирать ключевые фразы и автотаргетинги с указанными состояниями. См. Статус и состояние фразы. Нет
Statuses array of StatusEnum Отбирать ключевые фразы и автотаргетинги с указанными статусами. См. Статус и состояние фразы. Нет
ServingStatuses array of ServingStatusEnum Отбирать ключевые фразы и автотаргетинги с указанными статусами возможности показов группы объявлений. См. Статус возможности показов группы. Нет
ModifiedSince string

Отбирать ключевые фразы и автотаргетинги, в которых были изменения начиная с указанной даты.

Задается в формате YYYY-MM-DDThh:mm:ssZ (согласно ISO 8601), например 2015-05-24T23:59:59Z.

Нет
Параметр Тип Описание Обяза-тельный
Структура params (для JSON) / GetRequest (для SOAP)
SelectionCriteria KeywordsSelectionCriteria

Критерий отбора ключевых фраз и автотаргетингов.

Да
FieldNames array of KeywordFieldEnum

Имена параметров, которые требуется получить.

Внимание. Не рекомендуется указывать параметры StatisticsSearch и StatisticsNetwork, если запрашиваются данные большого количества ключевых фраз: такие запросы могут обрабатываться значительно медленнее.
Да
AutotargetingSettingsCategoriesFieldNames array of AutotargetingSettingsCategoriesFieldEnum

Категории таргетинга, которые требуется получить.

Нет
AutotargetingSettingsBrandOptionsFieldNames array of AutotargetingSettingsBrandOptionsFieldEnum

Настройки брендовости, которые требуется получить.

Нет
Page LimitOffset

Структура, задающая страницу при постраничной выборке данных.

Нет
Структура 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 Отбирать ключевые фразы и автотаргетинги с указанными состояниями. См. Статус и состояние фразы. Нет
Statuses array of StatusEnum Отбирать ключевые фразы и автотаргетинги с указанными статусами. См. Статус и состояние фразы. Нет
ServingStatuses array of ServingStatusEnum Отбирать ключевые фразы и автотаргетинги с указанными статусами возможности показов группы объявлений. См. Статус возможности показов группы. Нет
ModifiedSince string

Отбирать ключевые фразы и автотаргетинги, в которых были изменения начиная с указанной даты.

Задается в формате YYYY-MM-DDThh:mm:ssZ (согласно ISO 8601), например 2015-05-24T23:59:59Z.

Нет

Ответ

Примечание. В ответе присутствуют только параметры, которые были указаны во входном параметре FieldNames.

Структура ответа в формате JSON:

{
  "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": ( "LOW" | "NORMAL" | "HIGH" ), /* 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 Порядковый номер последнего возвращенного объекта. Передается в случае, если количество объектов в ответе было ограничено лимитом. См. раздел Постраничная выборка.
Структура KeywordGetItem
Id long Идентификатор ключевой фразы или автотаргетинга.
AdGroupId long Идентификатор группы объявлений, к которой относится ключевая фраза или автотаргетинг.
CampaignId long Идентификатор кампании, к которой относится ключевая фраза или автотаргетинг.
Keyword string

Ключевая фраза. Может содержать минус-слова.

Для автотаргетинга возвращается значение ---autotargeting.

UserParam1 string, nillable Значение подстановочной переменной {param1}. Не более 255 символов.
UserParam2 string, nillable Значение подстановочной переменной {param2}. Не более 255 символов.
Bid long Ставка на поиске.
AutotargetingSearchBidIsAuto YesNoEnum Признак включения опции автоматической ставки.
ContextBid long

Ставка в сетях.

StrategyPriority PriorityEnum, nillable

Приоритет ключевой фразы или автотаргетинга: LOW, NORMAL или HIGH.

Status StatusEnum Статус ключевой фразы или автотаргетинга. Описание статусов см. в разделе Статус и состояние фразы.
ServingStatus ServingStatusEnum Статус возможности показов группы объявлений. Описание статусов см. в разделе Статус возможности показов группы.
State StateEnum Состояние ключевой фразы или автотаргетинга. Описание состояний см. в разделе Статус и состояние фразы.
Productivity Productivity, nillable Параметр утратил актуальность, всегда возвращается значение null (nil).
StatisticsSearch Statistics

Статистика показов и кликов всех объявлений группы по данной ключевой фразе или автотаргетингу на поиске.

Если в группе объявлений мало показов (значение RARELY_SERVED параметра ServingStatus), параметр не возвращается.

StatisticsNetwork Statistics

Статистика показов и кликов всех объявлений группы по данной фразе в сетях.

Если в группе объявлений мало показов (значение RARELY_SERVED параметра ServingStatus), параметр не возвращается.

AutotargetingCategories AutotargetingCategories, nillable

Категории таргетинга.

Внимание.

Поле устарело и скоро перестанет поддерживаться. Для получения настроек таргетинга используйте структуру AutotargetingSettings.

AutotargetingSettings AutotargetingSettings, nillable

Настройки таргетинга.

Структура Statistics
Clicks long Количество кликов по всем объявлениям группы, показанным по данной ключевой фразе или автотаргетингу. Рассчитывается за 28 дней от текущей даты.
Impressions long Количество показов всех объявлений группы по данной фразе или автотаргетингу. Рассчитывается за 28 дней от текущей даты.
Структура AutotargetingCategories
Category AutotargetingCategoriesEnum

Категория таргетинга:

  • EXACT — целевые запросы. Рекламное объявление точно отвечает на запросы пользователя;
  • ALTERNATIVE — альтернативные запросы. Пользователь ищет продукт, который можно заменить рекламируемым. При этом объявление также может удовлетворить запрос;
  • COMPETITOR — запросы с упоминанием конкурентов. Поиск рекламируемого продукта у конкурентов;
  • BROADER — широкие запросы. Запросы с интересом к продукту, примером которого является рекламное предложение;
  • ACCESSORY — сопутствующие запросы. Запросы по продуктам, которые могут быть интересны вместе с рекламируемым товаром или услугой.
Внимание.

Поле устарело и скоро перестанет поддерживаться.

Настройки, заданные в веб-интерфейсе, сконвертируются в API по следующим правилам:

Веб-интерфейс API

Хотя бы одна включенная категория из набора «Целевые», «Узкие».

Включенная категория EXACT.

Включенная опция упоминания брендов «Конкуренты» (если это единственная включенная опция упоминания брендов).

Включенная категория COMPETITOR + выключение остальных категорий.

Включенная опция упоминания брендов «Конкуренты» (если это не единственная включенная опция упоминания брендов).

Включенная категория COMPETITOR.

Выключенная опция упоминания брендов «Конкуренты».

Выключенная категория COMPETITOR.

Веб-интерфейс API

Хотя бы одна включенная категория из набора «Целевые», «Узкие».

Включенная категория EXACT.

Включенная опция упоминания брендов «Конкуренты» (если это единственная включенная опция упоминания брендов).

Включенная категория COMPETITOR + выключение остальных категорий.

Включенная опция упоминания брендов «Конкуренты» (если это не единственная включенная опция упоминания брендов).

Включенная категория COMPETITOR.

Выключенная опция упоминания брендов «Конкуренты».

Выключенная категория COMPETITOR.

Value YesNoEnum Признак включения указанной категории таргетинга. По умолчанию включены все категории таргетинга.
Структура AutotargetingSettings
Categories AutotargetingSettingsCategoriesFieldNames

Категории таргетинга. Доступные опции:

  • Exact – целевые запросы. Рекламное объявление точно отвечает на запросы пользователя.
  • Narrow – узкие запросы. Рекламное объявление шире, чем запросы пользователя.
  • Alternative – альтернативные запросы. Пользователь ищет продукт, который можно заменить рекламируемым. При этом объявление также может удовлетворить запрос.
  • Accessory – сопутствующие запросы. Запросы по продуктам, которые могут быть интересны вместе с рекламируемым товаром или услугой.
  • Broader – широкие запросы. Запросы с интересом к продукту, примером которого является рекламное предложение.
BrandOptions AutotargetingSettingsBrandOptionsFieldNames

Настройки брендовости. Доступные опции:

  • WithoutBrands – без упоминания брендов.
  • WithAdvertiserBrand – с упоминанием бренда рекламодателя.
  • WithCompetitorsBrand – с упоминанием брендов конкурентов.
Параметр Тип Описание
Структура result (для JSON) / GetResponse (для SOAP)
Keywords array of KeywordGetItem Ключевые фразы и автотаргетинги.
LimitedBy long Порядковый номер последнего возвращенного объекта. Передается в случае, если количество объектов в ответе было ограничено лимитом. См. раздел Постраничная выборка.
Структура KeywordGetItem
Id long Идентификатор ключевой фразы или автотаргетинга.
AdGroupId long Идентификатор группы объявлений, к которой относится ключевая фраза или автотаргетинг.
CampaignId long Идентификатор кампании, к которой относится ключевая фраза или автотаргетинг.
Keyword string

Ключевая фраза. Может содержать минус-слова.

Для автотаргетинга возвращается значение ---autotargeting.

UserParam1 string, nillable Значение подстановочной переменной {param1}. Не более 255 символов.
UserParam2 string, nillable Значение подстановочной переменной {param2}. Не более 255 символов.
Bid long Ставка на поиске.
AutotargetingSearchBidIsAuto YesNoEnum Признак включения опции автоматической ставки.
ContextBid long

Ставка в сетях.

StrategyPriority PriorityEnum, nillable

Приоритет ключевой фразы или автотаргетинга: LOW, NORMAL или HIGH.

Status StatusEnum Статус ключевой фразы или автотаргетинга. Описание статусов см. в разделе Статус и состояние фразы.
ServingStatus ServingStatusEnum Статус возможности показов группы объявлений. Описание статусов см. в разделе Статус возможности показов группы.
State StateEnum Состояние ключевой фразы или автотаргетинга. Описание состояний см. в разделе Статус и состояние фразы.
Productivity Productivity, nillable Параметр утратил актуальность, всегда возвращается значение null (nil).
StatisticsSearch Statistics

Статистика показов и кликов всех объявлений группы по данной ключевой фразе или автотаргетингу на поиске.

Если в группе объявлений мало показов (значение RARELY_SERVED параметра ServingStatus), параметр не возвращается.

StatisticsNetwork Statistics

Статистика показов и кликов всех объявлений группы по данной фразе в сетях.

Если в группе объявлений мало показов (значение RARELY_SERVED параметра ServingStatus), параметр не возвращается.

AutotargetingCategories AutotargetingCategories, nillable

Категории таргетинга.

Внимание.

Поле устарело и скоро перестанет поддерживаться. Для получения настроек таргетинга используйте структуру AutotargetingSettings.

AutotargetingSettings AutotargetingSettings, nillable

Настройки таргетинга.

Структура Statistics
Clicks long Количество кликов по всем объявлениям группы, показанным по данной ключевой фразе или автотаргетингу. Рассчитывается за 28 дней от текущей даты.
Impressions long Количество показов всех объявлений группы по данной фразе или автотаргетингу. Рассчитывается за 28 дней от текущей даты.
Структура AutotargetingCategories
Category AutotargetingCategoriesEnum

Категория таргетинга:

  • EXACT — целевые запросы. Рекламное объявление точно отвечает на запросы пользователя;
  • ALTERNATIVE — альтернативные запросы. Пользователь ищет продукт, который можно заменить рекламируемым. При этом объявление также может удовлетворить запрос;
  • COMPETITOR — запросы с упоминанием конкурентов. Поиск рекламируемого продукта у конкурентов;
  • BROADER — широкие запросы. Запросы с интересом к продукту, примером которого является рекламное предложение;
  • ACCESSORY — сопутствующие запросы. Запросы по продуктам, которые могут быть интересны вместе с рекламируемым товаром или услугой.
Внимание.

Поле устарело и скоро перестанет поддерживаться.

Настройки, заданные в веб-интерфейсе, сконвертируются в API по следующим правилам:

Веб-интерфейс API

Хотя бы одна включенная категория из набора «Целевые», «Узкие».

Включенная категория EXACT.

Включенная опция упоминания брендов «Конкуренты» (если это единственная включенная опция упоминания брендов).

Включенная категория COMPETITOR + выключение остальных категорий.

Включенная опция упоминания брендов «Конкуренты» (если это не единственная включенная опция упоминания брендов).

Включенная категория COMPETITOR.

Выключенная опция упоминания брендов «Конкуренты».

Выключенная категория COMPETITOR.

Веб-интерфейс API

Хотя бы одна включенная категория из набора «Целевые», «Узкие».

Включенная категория EXACT.

Включенная опция упоминания брендов «Конкуренты» (если это единственная включенная опция упоминания брендов).

Включенная категория COMPETITOR + выключение остальных категорий.

Включенная опция упоминания брендов «Конкуренты» (если это не единственная включенная опция упоминания брендов).

Включенная категория COMPETITOR.

Выключенная опция упоминания брендов «Конкуренты».

Выключенная категория COMPETITOR.

Value YesNoEnum Признак включения указанной категории таргетинга. По умолчанию включены все категории таргетинга.
Структура AutotargetingSettings
Categories AutotargetingSettingsCategoriesFieldNames

Категории таргетинга. Доступные опции:

  • Exact – целевые запросы. Рекламное объявление точно отвечает на запросы пользователя.
  • Narrow – узкие запросы. Рекламное объявление шире, чем запросы пользователя.
  • Alternative – альтернативные запросы. Пользователь ищет продукт, который можно заменить рекламируемым. При этом объявление также может удовлетворить запрос.
  • Accessory – сопутствующие запросы. Запросы по продуктам, которые могут быть интересны вместе с рекламируемым товаром или услугой.
  • Broader – широкие запросы. Запросы с интересом к продукту, примером которого является рекламное предложение.
BrandOptions AutotargetingSettingsBrandOptionsFieldNames

Настройки брендовости. Доступные опции:

  • WithoutBrands – без упоминания брендов.
  • WithAdvertiserBrand – с упоминанием бренда рекламодателя.
  • WithCompetitorsBrand – с упоминанием брендов конкурентов.