AdGroup Data Object
Defines an ad group.
<xs:complexType name="ArrayOfAdGroup">
<xs:sequence>
<xs:element minOccurs="0" maxOccurs="unbounded" name="AdGroup" nillable="true" type="tns:AdGroup" />
</xs:sequence>
</xs:complexType>
<xs:element name="ArrayOfAdGroup" nillable="true" type="tns:ArrayOfAdGroup" />
<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="CashBackInfo" nillable="true" type="tns:CashBackInfo" />
<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="LanguageAndRegion" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="Name" nillable="true" type="xs:string" />
<xs:element xmlns:q20="http://schemas.microsoft.com/2003/10/Serialization/Arrays" minOccurs="0" name="NegativeKeywords" nillable="true" type="q20:ArrayOfstring" />
<xs:element xmlns:q21="http://schemas.microsoft.com/2003/10/Serialization/Arrays" minOccurs="0" name="NegativeSiteUrls" nillable="true" type="q21:ArrayOfstring" />
<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="StartDate" nillable="true" type="tns:Date" />
<xs:element minOccurs="0" name="Status" nillable="true" type="tns:AdGroupStatus" />
</xs:sequence>
</xs:complexType>
<xs:element name="AdGroup" nillable="true" type="tns:AdGroup" />
| Element | Description | Data Type | Add | Update | Rules |
|---|---|---|---|---|---|
|
|
Determines whether the ad group contains content ads, search ads, or both.  Note
Content match is limited to the U.S. and Canadian markets and is available only to pilot program participants.
|
Required |
Optional |
||
|
|
Determines whether the ad group bids on keyword matches, site placement matches, or behavioral matches. If you specify the keyword bidding model, you can set Note
The site placement and behavioral bidding models are limited to the U.S. markets.
|
Required |
Read-only |
None |
|
|
|
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 all of the words in the keyword or phrase are present in the user's query; however, the order of the words can vary. 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 |
Optional |
Optional |
||
|
|
The |
Read-only |
Read-only |
None |
|
|
|
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 or phrase 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 must set a content match bid if the |
Optional |
Optional |
||
|
|
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 |
Optional |
Optional |
||
|
|
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 or phrase exactly match the user's query. The plural form of a keyword is also used in an exact match comparison, if the plural form is not in your keyword list. For example, if you specify an exact match bid for the keyword, car, the service will match on car and cars. To prevent the service from matching on the plural form of a keyword, add the plural form to the negative keyword list. 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 |
Optional |
Optional |
||
|
|
The system generated identifier of the ad group. |
|
Read-only |
Required
|
None |
|
|
The language used on the websites where you want the service to display the ads in the ad group. For example, if you want the service to display the ads on Bing.fr or on websites that use the French language, set |
|
Required |
Read-only |
None |
|
|
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. |
|
Required |
Optional |
None |
|
|
A list of negative keywords that prevent the service from serving an ad if the user’s query contains one of the negative keywords. You can specify up to 10,000 negative keywords. Each keyword is limited to 100 characters. You can specify negative keywords at the campaign level and ad group level. Negative keywords specified at the ad group level override negative keywords specified at the campaign level. To use an exact match comparison, enclose the negative keyword in square brackets (for example, [old dog]); otherwise, adCenter uses a phrase match comparison. You should specify the keywords in the locale of the If you do not specify negative keywords, set the For more information about negative keywords, see Negative Keywords. |
|
Optional |
Optional |
None |
|
|
A list of URLs that identify the websites on which you do not want your ads displayed. You can specify a maximum of 500 URLs. Each URL must specify the domain name and can specify one subdomain name and a maximum of two directories. You can exclude websites for search and content ads. For search ads, you can specify only syndicated search websites. For more information, see AdGroupNetwork. Negative site URLs specified at the ad group level override negative site URLs specified at the campaign level. |
|
Optional |
Optional |
None |
|
|
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 or phrase 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 an exact match bid if the |
Optional |
Optional |
||
|
|
You can specify a pricing model based on cost-per-click (CPC) or cost-per-thousand impressions (CPM). For CPC, the service charges your account a maximum of your bid value plus the incremental bid value if you specify targeting, each time the user clicks your ad. 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. Note
The CPM pricing model is available only to pilot program participants and the AdDistribution element must include Content distribution.
|
Required |
Read-only |
None |
|
|
|
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 |
Optional |
Optional |
None |
|
|
|
The status of the ad group. |
Optional |
Read-only |
Bid Values
For information on setting bid values, see Bid Values.
To specify a 0 (zero) bid value for a match type (for example, PhraseMatchBid) when adding a new ad group, set the match type element to null. Setting the Amount element of the Bid object to 0 results in an error.
To specify a 0 bid value for a match type when updating an existing ad group, set the Amount element of the Bid object to 0. If you were to set the match type element to null, the existing bid value is not changed.
If you specify a 0 bid value, the default bid value for the specified ad group language is used.
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 operations, respectively.
