get
Возвращает параметры ключевых фраз или автотаргетингов, отвечающих заданным критериям: значения подстановочных переменных, статус и состояние, статистику показов и кликов, ставки и приоритеты.
Ставки или приоритеты можно получить независимо от того, какая стратегия выбрана в кампании — ручная или автоматическая.
Ставки и цены передаются через 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 | Отбирать ключевые фразы и автотаргетинги, в которых были изменения начиная с указанной даты. Задается в формате | Нет |
Параметр | Тип | Описание | Обяза-тельный |
Структура 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 | Отбирать ключевые фразы и автотаргетинги, в которых были изменения начиная с указанной даты. Задается в формате | Нет |
Ответ
Структура ответа в формате 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 | Ключевая фраза. Может содержать минус-слова. Для автотаргетинга возвращается значение | ||||||||||||||||||||
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, nillable | Настройки таргетинга. | ||||||||||||||||||||
Структура Statistics | ||||||||||||||||||||||
Clicks | long | Количество кликов по всем объявлениям группы, показанным по данной ключевой фразе или автотаргетингу. Рассчитывается за 28 дней от текущей даты. | ||||||||||||||||||||
Impressions | long | Количество показов всех объявлений группы по данной фразе или автотаргетингу. Рассчитывается за 28 дней от текущей даты. | ||||||||||||||||||||
Структура AutotargetingCategories | ||||||||||||||||||||||
Category | AutotargetingCategoriesEnum | Категория таргетинга:
Внимание. Поле устарело и скоро перестанет поддерживаться. Настройки, заданные в веб-интерфейсе, сконвертируются в API по следующим правилам:
| ||||||||||||||||||||
Value | YesNoEnum | Признак включения указанной категории таргетинга. По умолчанию включены все категории таргетинга. | ||||||||||||||||||||
Структура AutotargetingSettings | ||||||||||||||||||||||
Categories | AutotargetingSettingsCategoriesFieldNames | Категории таргетинга. Доступные опции:
| ||||||||||||||||||||
BrandOptions | AutotargetingSettingsBrandOptionsFieldNames | Настройки брендовости. Доступные опции:
|
Параметр | Тип | Описание | ||||||||||||||||||||
Структура result (для JSON) / GetResponse (для SOAP) | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Keywords | array of KeywordGetItem | Ключевые фразы и автотаргетинги. | ||||||||||||||||||||
LimitedBy | long | Порядковый номер последнего возвращенного объекта. Передается в случае, если количество объектов в ответе было ограничено лимитом. См. раздел Постраничная выборка. | ||||||||||||||||||||
Структура KeywordGetItem | ||||||||||||||||||||||
Id | long | Идентификатор ключевой фразы или автотаргетинга. | ||||||||||||||||||||
AdGroupId | long | Идентификатор группы объявлений, к которой относится ключевая фраза или автотаргетинг. | ||||||||||||||||||||
CampaignId | long | Идентификатор кампании, к которой относится ключевая фраза или автотаргетинг. | ||||||||||||||||||||
Keyword | string | Ключевая фраза. Может содержать минус-слова. Для автотаргетинга возвращается значение | ||||||||||||||||||||
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, nillable | Настройки таргетинга. | ||||||||||||||||||||
Структура Statistics | ||||||||||||||||||||||
Clicks | long | Количество кликов по всем объявлениям группы, показанным по данной ключевой фразе или автотаргетингу. Рассчитывается за 28 дней от текущей даты. | ||||||||||||||||||||
Impressions | long | Количество показов всех объявлений группы по данной фразе или автотаргетингу. Рассчитывается за 28 дней от текущей даты. | ||||||||||||||||||||
Структура AutotargetingCategories | ||||||||||||||||||||||
Category | AutotargetingCategoriesEnum | Категория таргетинга:
Внимание. Поле устарело и скоро перестанет поддерживаться. Настройки, заданные в веб-интерфейсе, сконвертируются в API по следующим правилам:
| ||||||||||||||||||||
Value | YesNoEnum | Признак включения указанной категории таргетинга. По умолчанию включены все категории таргетинга. | ||||||||||||||||||||
Структура AutotargetingSettings | ||||||||||||||||||||||
Categories | AutotargetingSettingsCategoriesFieldNames | Категории таргетинга. Доступные опции:
| ||||||||||||||||||||
BrandOptions | AutotargetingSettingsBrandOptionsFieldNames | Настройки брендовости. Доступные опции:
|