get

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

Внимание

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

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

Узнайте больше

Ограничения

Метод возвращает не более page-size объектов.

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

Запрос

Структура запроса в формате 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 до ids-select элементов в массиве.

Один из параметров Ids, AdGroupIds и CampaignIds (могут присутствовать все)

AdGroupIds

array of long

Отбирать ключевые фразы и автотаргетинги указанных групп. От 1 до adgroup-ids-select элементов в массиве.

CampaignIds

array of long

Отбирать ключевые фразы и автотаргетинги указанных кампаний. От 1 до campaign-ids-select элементов в массиве.

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

Порядковый номер последнего возвращенного объекта. Передается в случае, если количество объектов в ответе было ограничено лимитом. См. раздел Постраничная выборка.

Структура 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

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

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.

Value

YesNoEnum

Признак включения указанной категории таргетинга. По умолчанию включены все категории таргетинга.

Структура AutotargetingSettings

Categories

AutotargetingSettingsCategoriesFieldNames

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

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

BrandOptions

AutotargetingSettingsBrandOptionsFieldNames

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

  • WithoutBrands – без упоминания брендов.
  • WithAdvertiserBrand – с упоминанием бренда рекламодателя.
  • WithCompetitorsBrand – с упоминанием брендов конкурентов.
Предыдущая
delete
Следующая
resume