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.
Alert
We don't recommend requesting statistics on impressions and clicks for a large number of keywords: requests like this might take much longer to process.
You can get bids and priorities regardless of whether a manual or automatic strategy is selected in the campaign.
Learn more
Restrictions
The method returns a maximum of page-size 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 |
Mandatory |
|
params structure (for JSON) / GetRequest (for SOAP) |
|||
|
|
KeywordsSelectionCriteria |
Criteria for selecting keywords and autotargetings. |
Yes |
|
|
array of KeywordFieldEnum |
The names of parameters to get. Alert We don't recommend specifying the |
Yes |
|
|
array of AutotargetingSettingsCategoriesFieldEnum |
Targeting categories to get. |
No |
|
|
array of AutotargetingSettingsBrandOptionsFieldEnum |
Brand mention settings to get. |
No |
|
|
Structure that defines the page for paginated selection of data. |
No |
|
|
KeywordsSelectionCriteria structure |
|||
|
|
array of long |
Selects keywords and autotargetings with the specified IDs. From 1 to |
One of the parameters |
|
|
array of long |
Selects keywords and autotargetings from the specified groups. From 1 to |
|
|
|
array of long |
Selects keywords and autotargetings from the specified campaigns. From 1 to |
|
|
|
array of KeywordStatusSelectionEnum |
Selects keywords and autotargetings with the specified states. See Status and state of a keyword. |
No |
|
|
array of StatusEnum |
Selects keywords and autotargetings with the specified statuses. See Status and state of a keyword. |
No |
|
|
array of ServingStatusEnum |
Selects keywords and autotargetings with the specified ad group serving statuses. See Serving status for the ad group. |
No |
|
|
string |
Selects keywords and autotargetings that had changes starting from the specified date. Specified in |
No |
Response
Note
The response contains only those parameters that were indicated in the FieldName input parameter.
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) |
||||||||||||
|
|
array of KeywordGetItem |
Keywords and autotargetings. |
||||||||||
|
|
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 the section Paginated data selection. |
||||||||||
|
KeywordGetItem structure |
||||||||||||
|
|
long |
ID of the keyword or autotargeting. |
||||||||||
|
|
long |
ID of the ad group that the keyword or autotargeting is associated with. |
||||||||||
|
|
long |
ID of the campaign that the keyword or autotargeting is associated with. |
||||||||||
|
|
string |
Keywords. May contain negative keywords. For autotargeting, the value |
||||||||||
|
|
string, nillable |
Value of the |
||||||||||
|
|
string, nillable |
Value of the |
||||||||||
|
|
long |
Bid in search results. |
||||||||||
|
|
YesNoEnum |
A flag indicating whether automatic bid is enabled. |
||||||||||
|
|
long |
Bid in ad networks. |
||||||||||
|
|
PriorityEnum, nillable |
Priority of the keyword or autotargeting: LOW, NORMAL or HIGH. |
||||||||||
|
|
StatusEnum |
Status of the keyword or autotargeting. For a description of the statuses, see the section Status and state of a keyword. |
||||||||||
|
|
ServingStatusEnum |
Serving status for the ad group. For a description of the statuses, see the section Serving status for the ad group. |
||||||||||
|
|
StateEnum |
State of the keyword or autotargeting. For a description of the states, see the section Status and state of a keyword. |
||||||||||
|
|
Productivity, nillable |
This parameter is obsolete. Always returns null (nil). |
||||||||||
|
|
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 |
||||||||||
|
|
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 |
||||||||||
|
|
AutotargetingCategories, nillable |
Targeting categories. Alert This field is deprecated and will soon cease to be supported. You can retrieve the targeting settings using the |
||||||||||
|
|
AutotargetingSettings, nillable |
Targeting settings. |
||||||||||
|
Statistics structure |
||||||||||||
|
|
long |
Number of clicks on all the group's ads that were shown for this keyword or autotargeting. Calculated for the last 28 days. |
||||||||||
|
|
long |
Number of impressions for this keyword or autotargeting for all ads in the ad group. Calculated for the last 28 days. |
||||||||||
|
AutotargetingCategories structure |
||||||||||||
|
|
AutotargetingCategoriesEnum |
Targeting category:
Alert 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:
|
||||||||||
|
|
YesNoEnum |
The flag indicating that the specified targeting category is enabled. All targeting categories are enabled by default. |
||||||||||
|
AutotargetingSettings structure |
||||||||||||
|
|
AutotargetingSettingsCategoriesFieldNames |
Targeting categories. Available options:
|
||||||||||
|
|
AutotargetingSettingsBrandOptionsFieldNames |
Brand mention settings. Available options:
|