AdGroupService - Services - Yahoo! Search Marketing Enterprise Web Services

Operations

addAdGroup

Create an ad group.

Capability required: CampaignWrite
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroup	AdGroup	The ad group to create.

Response

AdGroupResponse - The response, which indicates if the operation succeeded or failed, and the ad group.

Sample Code

addAdGroups

Create a list of ad groups.

Capability required: CampaignWrite
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroups	AdGroup[]	The list of ad groups to create.

Response

AdGroupResponse[] - A list of responses, which indicate if the operations succeeded or failed, and the list of ad groups.

deleteAdGroup

Delete an ad group.

Capability required: CampaignWrite
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupID	long	The ID of the ad group to delete.

Response

BasicResponse - The response, which indicates if the operation succeeded or failed.

deleteAdGroups

Delete a list of ad groups.

Capability required: CampaignWrite
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupIDs	long[]	The IDs of the ad groups to delete.

Response

BasicResponse[] - A list of responses, which indicate if the operations succeeded or failed.

getAdGroup

Return an ad group.

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupID	long	The ad group ID.

Response

AdGroup - The ad group.

getAdGroupAdCount

Return the number of ads in an ad group.

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupID	long	The ad group ID.
includeDeleted	boolean	If true, include the deleted ads in the count.

Response

long - The number of ads in the ad group.

getAdGroupContentMatchMaxBid

Return the maximum bid for Content Match® for an ad group.

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupID	long	The ad group ID.

Response

double - The maximum bid for Content Match in the specified ad group.

getAdGroupExcludedWordsCount

Return the number of excluded words for an ad group.

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupID	long	The ad group ID.
includeDeleted	boolean	If true, include excluded words that are in deleted ad groups in the count.

Response

long - The number of excluded words for the ad group.

getAdGroupKeywordCount

Return the number of keywords for an ad group.

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupID	long	The ad group ID.
includeDeleted	boolean	If true, include the deleted keywords in the count.

Response

long - The number of keywords for the ad group.

getAdGroups

Return one or more ad groups (specified by adGroupIDs).

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupIDs	long[]	A list of ad group IDs.

Response

AdGroup[] - The list of ad groups.

getAdGroupsByCampaignID

Return the ad groups for a campaign (specified by campaignID).

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
campaignID	long	The campaign ID.
includeDeleted	boolean	If true, include deleted ad groups.
startElement	int	The first element to be returned (0-based; if a value < 0 is entered, will default to 0).
numElements	int	The number of elements to be returned (1000 maximum; if a value <=0 is entered, will default to 1000).

Response

AdGroup[] - The list of ad groups for the specified campaign.

getAdGroupsByCampaignIDByStatus

Return the ad groups with the indicated status for the campaign (specified by campaignID).

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
campaignID	long	The campaign ID.
adGroupStatus	AdGroupStatus	The ad group status.

Response

AdGroup[] - The list of ad groups with the indicated status for the specified campaign.

getAdGroupSponsoredSearchMaxBid

Return the maximum bid for Sponsored Search for the ad group (specified by adGroupID).

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupID	long	The ad group ID.

Response

double - The maximum bid for Sponsored Search.

getContentMatchMinBidForAdGroupOptimizationGuidelines

Return the Content Match® minimum bid for the optimization guidelines of the ad group (specified by adGroupID).

Capability required: CampaignRead
License command group: CampaignOptimization
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupID	long	The ad group ID.

Response

double - The minimum bid for Content Match.

getOptimizationGuidelinesForAdGroup

Return the optimization guidelines for the ad group (specified by adGroupID).

Capability required: CampaignRead
License command group: CampaignOptimization
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupID	long	The ad group ID.

Response

AdGroupOptimizationGuidelines - The optimization guidelines for the ad group.

getSponsoredSearchMinBidForAdGroup

Return the minimum bid for Sponsored Search for the ad group (specified by adGroupID).

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupID	long	The ad group ID.

Response

double - The minimum bid for Sponsored Search.

getSponsoredSearchMinBidForAdGroupOptimizationGuidelines

Return the Sponsored Search minimum bid for the optimization guidelines of the ad group (specified by adGroupID).

Capability required: CampaignRead
License command group: CampaignOptimization
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupID	long	The ad group ID.

Response

double - The minimum bid for Sponsored Search.

getSponsoredSearchMinBidForAdGroups

Return the minimum bids for Sponsored Search for the list of ad groups (specified by adGroupIDs).

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupIDs	long[]	The list of ad group IDs.

Response

double[] - The minimum bids for Sponsored Search.

getStatusForAdGroup

Return the status of the ad group (specified by adGroupID).

Capability required: CampaignRead
License command group: AdvancedTools
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupID	long	The ad group ID.

Response

AdGroupStatus - The ad group status.

moveAdGroup

Move the ad group (specified by adGroupdID) to the campaign (specified by destinationCampaignID).

Capability required: CampaignWrite
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupID	long	The ID of the ad group to move.
destinationCampaignID	long	The ID of the campaign to move the ad group to.
newAdGroupName	string	The new name for the ad group. (For this parameter, you may pass in the null string. If you pass in the null string, the old ad group name is used).

Response

BasicResponse - The response, which indicates if the operation succeeded or failed.

setAdGroupContentMatchMaxBid

Set the maximum bid for Content Match® for the ad group (specified by AdGroupID).

Capability required: CampaignWrite
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupID	long	The ad group ID.
maxBid	double	The maximum bid for Content Match.

Response

AdGroupResponse - The response, which indicates if the operation succeeded or failed.

setAdGroupSponsoredSearchMaxBid

Set the maximum bid for Sponsored Search for the ad group (specified by AdGroupID).

Capability required: CampaignWrite
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupID	long	The ad group ID.
maxBid	double	The maximum bid for Sponsored Search.

Response

AdGroupResponse - The response, which indicates if the operation succeeded or failed.

setOptimizationGuidelinesForAdGroup

Set the optimization guidelines for the ad group.

Capability required: CampaignWrite
License command group: CampaignOptimization
Supported accounts: Web

Parameters

Parameter	Data Type	Description
optimizationGuidelines	AdGroupOptimizationGuidelines	The optimization guidelines for the ad group.

Response

AdGroupOptimizationGuidelinesResponse - The response, which indicates if the operation succeeded or failed.

splitAdGroupBasedOnTactic

Split the ad group into multiple ad groups — one for each tactic (CM and SS).

The split is performed ONLY if:

The ad group (identified by adGroupID) is a multi-tactic ad group; otherwise, this operation returns an error.
The cap limit of the campaign is not exceeded.

After the split, the original ad group's status is paused.

Capability required: CampaignWrite
License command group: AdvancedTools
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupID	long	The ad group ID.

Response

AdGroup[] - The new ad groups after the split. There will be 3 ad groups — the original ad group, a replica of the original ad group for Sponsored Search, and another replica of the original ad group for Content Match. After the split, the new ad groups' names will include the tactic type (SS and CM) appended to the original name.

updateAdGroup

Update an ad group.

Capability required: CampaignWrite
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroup	AdGroup	The ad group.
updateAll	boolean	If true, the system performs a full update. All elements are updated. If you pass in the null value or omit an element, the current value is cleared. If false, the system performs a partial update. Only those elements you specify are updated. If you pass in the null value or omit an optional element, the current value is not changed.

Response

AdGroupResponse - The response, which indicates if the operation succeeded or failed.

updateAdGroups

Update one or more ad groups.

Capability required: CampaignWrite
License command group: Marketing
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroups	AdGroup[]	A list of ad groups.
updateAll	boolean	If true, the system performs a full update. All elements are updated. If you pass in the null value or omit an element, the current value is cleared. If false, the system performs a partial update. Only those elements you specify are updated. If you pass in the null value or omit an optional element, the current value is not changed.

Response

AdGroupResponse[] - A list of responses, which indicate if the operations succeeded or failed.

updateStatusForAdGroup

Update the status of the ad group (specified by adGroupID).

Capability required: CampaignWrite
License command group: AdvancedTools
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupID	long	The ad group ID.
status	AdGroupStatus	The new ad group status. You can set the status to On or Off, but not Deleted. (To delete an ad group, use the deleteAdGroup operation.)

Response

AdGroupResponse - The response, which indicates if the operation succeeded or failed.

updateStatusForAdGroups

Update the status of one or more ad groups (specified by the list of adGroupIDs).

Capability required: CampaignWrite
License command group: AdvancedTools
Supported accounts: Web

Parameters

Parameter	Data Type	Description
adGroupIDs	long[]	A list of ad group IDs.
status	AdGroupStatus	The new ad group status. You can set the status to On or Off, but not Deleted. (To delete one or more ad groups, use the deleteAdGroups operation.)