get
Returns parameters of keywords or autotargetings that match the set criteria: the values of substitution variables, status and state, statistics for impressions and clicks, and bids and priorities.
You can get bids and priorities regardless of whether a manual or automatic strategy is selected in the campaign.
Bids and prices are passed via the Yandex Direct API as integer numbers. The value passed is a bid or price multiplied by 1,000,000.
All bids and prices are shown in the advertiser's currency.
Restrictions
The method returns a maximum of 10,000 objects.
You can't get keywords from archived campaigns.
Request
Request structure in JSON format:
{
"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)
}
}
}
Parameter | Type | Description | Required |
Params structure (for JSON) / GetRequest (for SOAP) | |||
---|---|---|---|
SelectionCriteria | KeywordsSelectionCriteria | Criteria for selecting keywords and autotargetings. | Yes |
FieldNames | array of KeywordFieldEnum | The names of parameters to get. Attention. We don't recommend specifying the StatisticsSearch and StatisticsNetwork parameters when requesting data for a large number of keywords: requests like this take much longer to process. | Yes |
AutotargetingSettingsCategoriesFieldNames | array of AutotargetingSettingsCategoriesFieldEnum | Targeting categories to get. | No |
AutotargetingSettingsBrandOptionsFieldNames | array of AutotargetingSettingsBrandOptionsFieldEnum | Brand mention settings to get. | No |
Page | LimitOffset | Structure that defines the page for paginated selection of data. | No |
KeywordsSelectionCriteria structure | |||
Ids | array of long | Selects keywords and autotargetings with the specified IDs. From 1 to 10,000 items in the array. | One of the parameters Ids, AdGroupIds, or CampaignIds (or all may be present) |
AdGroupIds | array of long | Selects keywords and autotargetings from the specified groups. From 1 to 1000 items in the array. | |
CampaignIds | array of long | Selects keywords and autotargetings from the specified campaigns. From 1 to 10 items in the array. | |
States | array of KeywordStatusSelectionEnum | Selects keywords and autotargetings with the specified states. See Status and state of a keywordwhen calling finance methods. | No |
Statuses | array of StatusEnum | Selects keywords and autotargetings with the specified statuses. See Status and state of a keywordwhen calling finance methods. | No |
ServingStatuses | array of ServingStatusEnum | Selects keywords and autotargetings with the specified ad group serving statuses. See Ad group serving statuswhen calling finance methods. | No |
ModifiedSince | string | Selects keywords and autotargetings that had changes starting from the specified date. Specified in | No |
Parameter | Type | Description | Required |
Params structure (for JSON) / GetRequest (for SOAP) | |||
---|---|---|---|
SelectionCriteria | KeywordsSelectionCriteria | Criteria for selecting keywords and autotargetings. | Yes |
FieldNames | array of KeywordFieldEnum | The names of parameters to get. Attention. We don't recommend specifying the StatisticsSearch and StatisticsNetwork parameters when requesting data for a large number of keywords: requests like this take much longer to process. | Yes |
AutotargetingSettingsCategoriesFieldNames | array of AutotargetingSettingsCategoriesFieldEnum | Targeting categories to get. | No |
AutotargetingSettingsBrandOptionsFieldNames | array of AutotargetingSettingsBrandOptionsFieldEnum | Brand mention settings to get. | No |
Page | LimitOffset | Structure that defines the page for paginated selection of data. | No |
KeywordsSelectionCriteria structure | |||
Ids | array of long | Selects keywords and autotargetings with the specified IDs. From 1 to 10,000 items in the array. | One of the parameters Ids, AdGroupIds, or CampaignIds (or all may be present) |
AdGroupIds | array of long | Selects keywords and autotargetings from the specified groups. From 1 to 1000 items in the array. | |
CampaignIds | array of long | Selects keywords and autotargetings from the specified campaigns. From 1 to 10 items in the array. | |
States | array of KeywordStatusSelectionEnum | Selects keywords and autotargetings with the specified states. See Status and state of a keywordwhen calling finance methods. | No |
Statuses | array of StatusEnum | Selects keywords and autotargetings with the specified statuses. See Status and state of a keywordwhen calling finance methods. | No |
ServingStatuses | array of ServingStatusEnum | Selects keywords and autotargetings with the specified ad group serving statuses. See Ad group serving statuswhen calling finance methods. | No |
ModifiedSince | string | Selects keywords and autotargetings that had changes starting from the specified date. Specified in | No |
Response
Response structure in JSON format:
{
"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)
}
}
}
Parameter | Type | Description | ||||||||||||||||||||
Result structure (for JSON) / GetResponse (for SOAP) | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Keywords | array of KeywordGetItem | Keywords and autotargetings. | ||||||||||||||||||||
LimitedBy | long | Sequential number of the last object returned. It is included if there was a limit on the number of objects in the response. See Paginated selection. | ||||||||||||||||||||
KeywordGetItem structure | ||||||||||||||||||||||
Id | long | ID of the keyword or autotargeting. | ||||||||||||||||||||
AdGroupId | long | ID of the ad group that the keyword or autotargeting is associated with. | ||||||||||||||||||||
CampaignId | long | ID of the campaign that the keyword or autotargeting is associated with. | ||||||||||||||||||||
Keyword | string | Keywords. May contain negative keywords. For autotargeting, the value | ||||||||||||||||||||
UserParam1 | string, nillable | The value of the {param1} substitution variable. Maximum of 255 characters. | ||||||||||||||||||||
UserParam2 | string, nillable | The value of the {param2} substitution variable. Maximum of 255 characters. | ||||||||||||||||||||
Bid | long | Bid in search results. | ||||||||||||||||||||
AutotargetingSearchBidIsAuto | YesNoEnum | A flag indicating whether automatic bid is enabled. | ||||||||||||||||||||
ContextBid | long | Bid in ad networks. | ||||||||||||||||||||
StrategyPriority | PriorityEnum, nillable | Priority of the keyword or autotargeting: LOW, NORMAL or HIGH. | ||||||||||||||||||||
Status | StatusEnum | Status of the keyword or autotargeting. For status descriptions, see Status and state of a keyword. | ||||||||||||||||||||
ServingStatus | ServingStatusEnum | Serving status for the ad group. For status descriptions, see Ad group serving status. | ||||||||||||||||||||
State | StateEnum | State of the keyword or autotargeting. For state descriptions, see Status and state of a keyword. | ||||||||||||||||||||
Productivity | Productivity, nillable | This parameter is obsolete. Always returns null (nil). | ||||||||||||||||||||
StatisticsSearch | Statistics | Statistics on impressions and clicks for all the group's ads for this keyword or autotargeting in search results. If the ad group has very few displays (the ServingStatus parameter has the value RARELY_SERVED), the parameter isn't returned. | ||||||||||||||||||||
StatisticsNetwork | Statistics | Statistics on impressions and clicks for all the group's ads for this keyword in ad networks. If the ad group has very few displays (the ServingStatus parameter has the value RARELY_SERVED), the parameter isn't returned. | ||||||||||||||||||||
AutotargetingCategories | AutotargetingCategories, nillable | Targeting categories. Attention. This field is deprecated and will soon cease to be supported. To get the targeting settings, use the | ||||||||||||||||||||
AutotargetingSettings | AutotargetingSettings, nillable | Targeting settings. | ||||||||||||||||||||
Statistics structure | ||||||||||||||||||||||
Clicks | long | Number of clicks on all the group's ads that were shown for this keyword or autotargeting. Calculated for the last 28 days. | ||||||||||||||||||||
Impressions | long | Number of impressions for this keyword or autotargeting for all ads in the ad group. Calculated for the last 28 days. | ||||||||||||||||||||
AutotargetingCategories structure | ||||||||||||||||||||||
Category | AutotargetingCategoriesEnum | Targeting category:
Attention. This field is deprecated and will soon cease to be supported. The settings specified in the web interface are converted for the API as follows:
| ||||||||||||||||||||
Value | YesNoEnum | The flag indicating that the specified targeting category is enabled. All targeting categories are enabled by default. | ||||||||||||||||||||
AutotargetingSettings structure | ||||||||||||||||||||||
Categories | AutotargetingSettingsCategoriesFieldNames | Targeting categories. Available options:
| ||||||||||||||||||||
BrandOptions | AutotargetingSettingsBrandOptionsFieldNames | Brand mention settings. Available options:
|
Parameter | Type | Description | ||||||||||||||||||||
Result structure (for JSON) / GetResponse (for SOAP) | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Keywords | array of KeywordGetItem | Keywords and autotargetings. | ||||||||||||||||||||
LimitedBy | long | Sequential number of the last object returned. It is included if there was a limit on the number of objects in the response. See Paginated selection. | ||||||||||||||||||||
KeywordGetItem structure | ||||||||||||||||||||||
Id | long | ID of the keyword or autotargeting. | ||||||||||||||||||||
AdGroupId | long | ID of the ad group that the keyword or autotargeting is associated with. | ||||||||||||||||||||
CampaignId | long | ID of the campaign that the keyword or autotargeting is associated with. | ||||||||||||||||||||
Keyword | string | Keywords. May contain negative keywords. For autotargeting, the value | ||||||||||||||||||||
UserParam1 | string, nillable | The value of the {param1} substitution variable. Maximum of 255 characters. | ||||||||||||||||||||
UserParam2 | string, nillable | The value of the {param2} substitution variable. Maximum of 255 characters. | ||||||||||||||||||||
Bid | long | Bid in search results. | ||||||||||||||||||||
AutotargetingSearchBidIsAuto | YesNoEnum | A flag indicating whether automatic bid is enabled. | ||||||||||||||||||||
ContextBid | long | Bid in ad networks. | ||||||||||||||||||||
StrategyPriority | PriorityEnum, nillable | Priority of the keyword or autotargeting: LOW, NORMAL or HIGH. | ||||||||||||||||||||
Status | StatusEnum | Status of the keyword or autotargeting. For status descriptions, see Status and state of a keyword. | ||||||||||||||||||||
ServingStatus | ServingStatusEnum | Serving status for the ad group. For status descriptions, see Ad group serving status. | ||||||||||||||||||||
State | StateEnum | State of the keyword or autotargeting. For state descriptions, see Status and state of a keyword. | ||||||||||||||||||||
Productivity | Productivity, nillable | This parameter is obsolete. Always returns null (nil). | ||||||||||||||||||||
StatisticsSearch | Statistics | Statistics on impressions and clicks for all the group's ads for this keyword or autotargeting in search results. If the ad group has very few displays (the ServingStatus parameter has the value RARELY_SERVED), the parameter isn't returned. | ||||||||||||||||||||
StatisticsNetwork | Statistics | Statistics on impressions and clicks for all the group's ads for this keyword in ad networks. If the ad group has very few displays (the ServingStatus parameter has the value RARELY_SERVED), the parameter isn't returned. | ||||||||||||||||||||
AutotargetingCategories | AutotargetingCategories, nillable | Targeting categories. Attention. This field is deprecated and will soon cease to be supported. To get the targeting settings, use the | ||||||||||||||||||||
AutotargetingSettings | AutotargetingSettings, nillable | Targeting settings. | ||||||||||||||||||||
Statistics structure | ||||||||||||||||||||||
Clicks | long | Number of clicks on all the group's ads that were shown for this keyword or autotargeting. Calculated for the last 28 days. | ||||||||||||||||||||
Impressions | long | Number of impressions for this keyword or autotargeting for all ads in the ad group. Calculated for the last 28 days. | ||||||||||||||||||||
AutotargetingCategories structure | ||||||||||||||||||||||
Category | AutotargetingCategoriesEnum | Targeting category:
Attention. This field is deprecated and will soon cease to be supported. The settings specified in the web interface are converted for the API as follows:
| ||||||||||||||||||||
Value | YesNoEnum | The flag indicating that the specified targeting category is enabled. All targeting categories are enabled by default. | ||||||||||||||||||||
AutotargetingSettings structure | ||||||||||||||||||||||
Categories | AutotargetingSettingsCategoriesFieldNames | Targeting categories. Available options:
| ||||||||||||||||||||
BrandOptions | AutotargetingSettingsBrandOptionsFieldNames | Brand mention settings. Available options:
|