get
Returns bids and priorities for keywords and autotargetings that match the specified criteria, along with auction data: bids and actual CPC for various traffic volumes in search results, and bids for various percents of audience coverage in ad networks.
You can get bids and priorities regardless of whether a manual or automatic strategy is selected in the campaign.
Restrictions
The method returns a maximum of 10,000 objects.
Request
Request structure in JSON format:
{
"method": "get",
"params": { /* params */
"SelectionCriteria": { /* KeywordBidsSelectionCriteria */
"CampaignIds": [(long), ... ],
"AdGroupIds": [(long), ... ],
"KeywordIds": [(long), ... ],
"ServingStatuses": [( "ELIGIBLE" | "RARELY_SERVED" ), ... ]
}, /* required */
"FieldNames": [( "KeywordId" | "AdGroupId" | "CampaignId" | "ServingStatus" | "StrategyPriority" ), ... ], /* required */
"SearchFieldNames": [( "Bid" | "AutotargetingSearchBidIsAuto" | "AuctionBids" ), ... ],
"NetworkFieldNames": [( "Bid" | "Coverage" ), ... ],
"Page": { /* LimitOffset */
"Limit": (long),
"Offset": (long)
}
}
}
Parameter | Type | Description | Required |
Params structure (for JSON) / GetRequest (for SOAP) | |||
---|---|---|---|
SelectionCriteria | KeywordBidsSelectionCriteria | Criteria for selecting keywords and autotargetings. | Yes |
FieldNames | array of KeywordBidFieldEnum | Names of top-level parameters to get. | Yes |
SearchFieldNames | array of KeywordBidSearchFieldEnum | Names of search bidding parameters to get. Don't request the AuctionBids parameter if displays in search results are disabled for the campaign (the SERVING_OFF strategy in search). | No |
NetworkFieldNames | array of KeywordBidNetworkFieldEnum | Names of ad network bidding parameters to get. Don't request the Coverage parameter if the campaign has displays in ad networks disabled (the SERVING_OFF strategy in ad networks). | No |
Page | LimitOffset | Structure that defines the page for paginated selection of data. | No |
KeywordBidsSelectionCriteria structure | |||
CampaignIds | array of long | Get bids or priorities for keywords and autotargetings in the specified campaigns. From 1 to 10 items in the array. | One of the parameters KeywordIds, AdGroupIds, or CampaignIds (or all may be present) |
AdGroupIds | array of long | Get bids or priorities for keywords and autotargetings in the specified ad groups. From 1 to 1000 items in the array. | |
KeywordIds | array of long | Get bids or priorities for the specified keywords and autotargetings. A maximum of 10,000 items in the array. | |
ServingStatuses | array of ServingStatusEnum | Get bids or priorities for keywords and autotargetings with the specified ad group serving statuses. For status descriptions, see Ad group serving status. | No |
Parameter | Type | Description | Required |
Params structure (for JSON) / GetRequest (for SOAP) | |||
---|---|---|---|
SelectionCriteria | KeywordBidsSelectionCriteria | Criteria for selecting keywords and autotargetings. | Yes |
FieldNames | array of KeywordBidFieldEnum | Names of top-level parameters to get. | Yes |
SearchFieldNames | array of KeywordBidSearchFieldEnum | Names of search bidding parameters to get. Don't request the AuctionBids parameter if displays in search results are disabled for the campaign (the SERVING_OFF strategy in search). | No |
NetworkFieldNames | array of KeywordBidNetworkFieldEnum | Names of ad network bidding parameters to get. Don't request the Coverage parameter if the campaign has displays in ad networks disabled (the SERVING_OFF strategy in ad networks). | No |
Page | LimitOffset | Structure that defines the page for paginated selection of data. | No |
KeywordBidsSelectionCriteria structure | |||
CampaignIds | array of long | Get bids or priorities for keywords and autotargetings in the specified campaigns. From 1 to 10 items in the array. | One of the parameters KeywordIds, AdGroupIds, or CampaignIds (or all may be present) |
AdGroupIds | array of long | Get bids or priorities for keywords and autotargetings in the specified ad groups. From 1 to 1000 items in the array. | |
KeywordIds | array of long | Get bids or priorities for the specified keywords and autotargetings. A maximum of 10,000 items in the array. | |
ServingStatuses | array of ServingStatusEnum | Get bids or priorities for keywords and autotargetings with the specified ad group serving statuses. For status descriptions, see Ad group serving status. | No |
Response
Response structure in JSON format:
{
"result": { /* result */
"KeywordBids": [{ /* KeywordBidGetItem */
"CampaignId": (long),
"AdGroupId": (long),
"KeywordId": (long),
"ServingStatus": ( "ELIGIBLE" | "RARELY_SERVED" ),
"StrategyPriority": ( "LOW" | "NORMAL" | "HIGH" ), /* nillable */
"Search": { /* Search */
"Bid": (long),
"AutotargetingSearchBidIsAuto",: ( "YES" | "NO" ),
"AuctionBids": { /* AuctionBids */
"AuctionBidItems": [{ /* AuctionBidItem */
"TrafficVolume": (int), /* required */
"Bid": (long), /* required */
"Price": (long) /* required */
}, ... ]
} /* nillable */
},
"Network": { /* Network */
"Bid": (long),
"Coverage": { /* Coverage */
"CoverageItems": [{ /* NetworkCoverageItem */
"Probability": (decimal), /* required */
"Bid": (long) /* required */
}, ... ]
} /* nillable */
}
}, ... ],
"LimitedBy": (long)
}
}
Parameter | Type | Description |
Result structure (for JSON) / GetResponse (for SOAP) | ||
---|---|---|
KeywordBids | array of KeywordBidGetItem | Bids and/or priorities. |
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. |
KeywordBidGetItem structure | ||
CampaignId | long | ID of the campaign that the keyword or autotargeting is associated with. |
AdGroupId | long | ID of the ad group that the keyword or autotargeting is associated with. |
KeywordId | long | ID of the keyword or autotargeting. |
ServingStatus | ServingStatusEnum | Serving status for the ad group. For status descriptions, see Ad group serving status. |
StrategyPriority | PriorityEnum, nillable | Priority of the keyword or autotargeting: LOW, NORMAL or HIGH. |
Search | Search | Bid and auction data in search. |
Network | Network | Bid and auction data in ad networks. |
Search structure | ||
Bid | long | The bid for displays in search results that was set by the advertiser. |
AutotargetingSearchBidIsAuto | YesNoEnum | A flag indicating whether automatic bid is enabled. |
AuctionBids | AuctionBids, nillable | Bids and actual CPCs in search results for various traffic volumes for this keyword. If the group only has image ads, it returns null (nil). If the ad group has very few displays (the ServingStatus parameter has the value RARELY_SERVED), it returns null (nil). For autotargeting, it returns null (nil). |
AuctionBids structure | ||
AuctionBidItems | array of AuctionBidItem | Array of bids and actual CPCs in search results for various traffic volumes. |
AuctionBidItem structure | ||
TrafficVolume | int | Traffic volume. |
Bid | long | Bid in search for the specified traffic volume. |
Price | long | The actual CPC for the specified traffic volume. |
Network structure | ||
Bid | long | The bid for displays in ad networks that was set by the advertiser. |
Coverage | Coverage, nillable | The bids in ad networks that correspond to various percentages of audience coverage for this keyword. If the ad group has very few displays (the ServingStatus parameter has the value RARELY_SERVED), it returns null (nil). If the campaign uses the SERVING_OFF or NETWORK_DEFAULT strategy in ad networks, it returns null (nil). Restriction. The NETWORK_DEFAULT parameter is not supported for the HIGHEST_POSITION manual strategy. For autotargeting, it returns null (nil). |
Coverage structure | ||
CoverageItems | NetworkCoverageItem | Array of bids that correspond to various percentages of audience coverage. |
NetworkCoverageItem structure | ||
Probability | decimal | The frequency of impressions (the audience coverage) in ad networks. Indicated as a percentage from 0 to 100. |
Bid | long | Bid in ad networks for the specified frequency. |
Parameter | Type | Description |
Result structure (for JSON) / GetResponse (for SOAP) | ||
---|---|---|
KeywordBids | array of KeywordBidGetItem | Bids and/or priorities. |
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. |
KeywordBidGetItem structure | ||
CampaignId | long | ID of the campaign that the keyword or autotargeting is associated with. |
AdGroupId | long | ID of the ad group that the keyword or autotargeting is associated with. |
KeywordId | long | ID of the keyword or autotargeting. |
ServingStatus | ServingStatusEnum | Serving status for the ad group. For status descriptions, see Ad group serving status. |
StrategyPriority | PriorityEnum, nillable | Priority of the keyword or autotargeting: LOW, NORMAL or HIGH. |
Search | Search | Bid and auction data in search. |
Network | Network | Bid and auction data in ad networks. |
Search structure | ||
Bid | long | The bid for displays in search results that was set by the advertiser. |
AutotargetingSearchBidIsAuto | YesNoEnum | A flag indicating whether automatic bid is enabled. |
AuctionBids | AuctionBids, nillable | Bids and actual CPCs in search results for various traffic volumes for this keyword. If the group only has image ads, it returns null (nil). If the ad group has very few displays (the ServingStatus parameter has the value RARELY_SERVED), it returns null (nil). For autotargeting, it returns null (nil). |
AuctionBids structure | ||
AuctionBidItems | array of AuctionBidItem | Array of bids and actual CPCs in search results for various traffic volumes. |
AuctionBidItem structure | ||
TrafficVolume | int | Traffic volume. |
Bid | long | Bid in search for the specified traffic volume. |
Price | long | The actual CPC for the specified traffic volume. |
Network structure | ||
Bid | long | The bid for displays in ad networks that was set by the advertiser. |
Coverage | Coverage, nillable | The bids in ad networks that correspond to various percentages of audience coverage for this keyword. If the ad group has very few displays (the ServingStatus parameter has the value RARELY_SERVED), it returns null (nil). If the campaign uses the SERVING_OFF or NETWORK_DEFAULT strategy in ad networks, it returns null (nil). Restriction. The NETWORK_DEFAULT parameter is not supported for the HIGHEST_POSITION manual strategy. For autotargeting, it returns null (nil). |
Coverage structure | ||
CoverageItems | NetworkCoverageItem | Array of bids that correspond to various percentages of audience coverage. |
NetworkCoverageItem structure | ||
Probability | decimal | The frequency of impressions (the audience coverage) in ad networks. Indicated as a percentage from 0 to 100. |
Bid | long | Bid in ad networks for the specified frequency. |