AdGroup Data Object
Defines an ad group.
<xs:complexType name="AdGroup"> <xs:sequence> <xs:element minOccurs="0" name="AdDistribution" nillable="true" type="tns:AdDistribution" /> <xs:element minOccurs="0" name="BiddingModel" nillable="true" type="tns:BiddingModel" /> <xs:element minOccurs="0" name="BroadMatchBid" nillable="true" type="tns:Bid" /> <xs:element minOccurs="0" name="ContentMatchBid" nillable="true" type="tns:Bid" /> <xs:element minOccurs="0" name="EndDate" nillable="true" type="tns:Date" /> <xs:element minOccurs="0" name="ExactMatchBid" nillable="true" type="tns:Bid" /> <xs:element minOccurs="0" name="Id" nillable="true" type="xs:long" /> <xs:element minOccurs="0" name="Language" nillable="true" type="xs:string" /> <xs:element minOccurs="0" name="Name" nillable="true" type="xs:string" /> <xs:element minOccurs="0" name="Network" nillable="true" type="tns:Network" /> <xs:element minOccurs="0" name="PhraseMatchBid" nillable="true" type="tns:Bid" /> <xs:element minOccurs="0" name="PricingModel" nillable="true" type="tns:PricingModel" /> <xs:element minOccurs="0" name="PublisherCountries" nillable="true" type="tns:ArrayOfPublisherCountry" /> <xs:element minOccurs="0" name="StartDate" nillable="true" type="tns:Date" /> <xs:element minOccurs="0" name="Status" nillable="true" type="tns:AdGroupStatus" /> </xs:sequence> </xs:complexType>
Elements
Element | Description | Data Type | Add | Update | Rules | ||
|---|---|---|---|---|---|---|---|
AdDistribution | Determines whether the ad group contains content ads, search ads, or both. Although you can specify both distribution mediums for an ad group, you should specify one medium only.
| Required | Optional | ||||
BiddingModel | Determines whether the ad group bids on keyword matches or site placement matches. The default is Keyword. If you specify the keyword bidding model, you can set AdDistribution to both Content and Search. If you specify the site placement model, you must set AdDistribution only to Content.
| Optional | Read-only | None | |||
BroadMatchBid | The bid to use when the user’s query and the ad group’s keywords match by using a broad match comparison. A broad match results when words in the keyword are present in the user's query; however, the order of the words can vary. For more information, see Match Type and Bid Values. Specifying a broad match bid at the keyword level overrides the ad group’s broad match bid value. You can set a broad match bid if the AdDistribution element contains Search. | Optional | Optional | ||||
ContentMatchBid | The bid to use when the keywords that the service extracts from the content page and the ad group’s keywords match by using an exact match comparison. An exact match results when all of the words in the keyword exactly match the user's query. Specifying a content match bid at the keyword level overrides the ad group’s content match bid value. You can set a content match bid if the AdDistribution element contains Content. | Optional | Optional | ||||
EndDate | The date that the ads in the ad group will expire. If you do not specify an end date, the ads will not expire. The end date is inclusive. For example, if you set EndDate to 3/10/2010, the ads in the ad group will expire at 11:59 PM on 3/10/2010. The time is based on the time zone that you specify at the campaign level. | Optional | Optional | ||||
ExactMatchBid | The bid to use when the user’s query and the ad group’s keywords match by using an exact match comparison. An exact match results when all of the words in the keyword exactly match the user's query. Specifying an exact match bid at the keyword level overrides the ad group’s exact match bid value. You can set an exact match bid if the AdDistribution field contains Search. | Optional | Optional | ||||
Id | The system generated identifier of the ad group. | long | Read-only | Required | None | ||
Language | The language of the ads and keywords in the ad group. For possible values, see Language Values. | string | Required | Read-only | None | ||
Name | The name of the ad group. The name must be unique among all active ad groups within the campaign. The name can contain a maximum of 128 characters. | string | Required | Optional | None | ||
Network | The search networks where you want your ads to display. The default is OwnedAndOperatedAndSyndicatedSearch. If you select one of the syndicated search options, you can call the SetNegativeSitesToAdGroups operation to prevent the ads from displaying on specific syndicated search websites. You must set Network to null if AdDistribution is set to Content. | Optional | Optional | None | |||
PhraseMatchBid | The bid value to use when the user’s query and the ad group’s keywords match by using a phrase match. A phrase match results when all of the words in the keyword are present in the user's query, and are in the same order. Specifying a phrase-match bid at the keyword level overrides the ad group’s phrase-match bid value. You can set a phrase match bid if the AdDistribution element contains Search. | Optional | Optional | ||||
PricingModel | You can specify a pricing model based on cost-per-click (CPC) or cost-per-thousand impressions (CPM). For CPC, each time the user clicks your ad, the service charges your account a maximum of your bid value plus the incremental bid value if you specify targeting. The actual charge is based on the auction results and may be less than your bid value (the bid value for the match type that won the auction). If you specify CPC and enable conversion tracking for the campaign, you can calculate your costs per conversion. This helps you to determine the return on investment for your campaign. For CPM, your account is charged after the service displays your ad 1,000 times. The charge is based on the sum of your winning bids divided by 1,000.
| Required | Read-only | None | |||
PublisherCountries | Not supported. To target your ads by location, use location targeting (see Target Locations); otherwise, your ads are displayed to users worldwide. | Required | Read-only | None | |||
StartDate | The date that the ads in the ad group can begin serving; otherwise, the service can begin serving the ads in the ad group the day that the ad group becomes active. The start date is inclusive. For example, if you set StartDate to 3/5/2010, the ads in the ad group will start at 12:00 AM on 3/5/2010. The time is based on the time zone that you specify at the campaign level. | Optional | Optional | None | |||
Status | The status of the ad group. | Optional | Read-only |
Business Rules
Bid Values
For information about the default bid values of an ad group and setting keyword bid values, see Match Type and Bid Values.
A default bid value is used for a match type if you set the match type bid element (for example, PhraseMatchBid) to null or you set the Amount element of the Bid object to 0 (zero)). The default bid value is based on the customer’s currency and the bidding and pricing models that you specify.
Element Rules
AdDistribution Element
If you remove Content from the AdDistribution element of an existing ad group, the ContentMatchBid value is preserved for all keywords in the ad group. If you later add the Content distribution type back to the ad group, the previous ContentMatchBid value is applied to the keywords.
EndDate Element
To set no end date when updating an ad group, set the EndDate element to a date equal to or later than January 2, 2050.
To set no end date when adding an ad group, set the EndDate element to null.
Status Element
You can set the status to Active or Paused when you add the ad group. If you do not set the status, the system sets the status to Draft. To move the status from Draft to Active, call the SubmitAdGroupForApproval operation. Note that you can have a maximum of 500 ad groups awaiting editorial review in the Draft or Paused state.
After you add the ad group, you cannot change the status field directly. If you want to pause or resume the ad group, you must call the PauseAdGroups or ResumeAdGroups operation.
