Creating and editing ad groups

Backward compatibility

Previously created ads are automatically reorganized in ad groups: each of these groups contains a single ad. Statistics stay with the ads.

For ad groups consisting of a single ad, all ad management methods continue working as before.

Creating ad groups

Call the CreateOrUpdateBanners (Live) method with the AdGroupID parameter set to 0 (or omitted) and the BannerID parameter set to 0. The Geo and Phrases parameters are mandatory when creating ad groups.

As a result, a new ad group containing a single ad will be created. If the AdGroupName parameter was omitted, the group is automatically assigned a name in the format “AdGroup #<group ID>”.

The CreateOrUpdateBanners (Live) method returns the ID of the created ad. To get the ID of the ad group, use the GetBanners (Live) method and pass the ad ID as an input parameter. However, we recommend setting the GetPhrases parameter to the value No in order to reduce the load on the API and increase performance.

Creating ads in an ad group

Call the CreateOrUpdateBanners (Live) method and specify the ID of the ad group in the AdGroupID parameter. The AdGroupName, Geo, Phrases, and MinusKeywords parameters are not necessary.

Getting ad group parameters

The GetBanners (Live) method returns parameters for both the ad and the ad group. In other words, keywords and other ad group parameters will be duplicated in each ad.

Attention. If the ad group has several ads, the GetBanners (Live) method returns the same set of keywords for each of the ads in the group. This could cause an application error if the application checks for overall PhraseID uniqueness.

The GetBannerPhrases (Live) and GetBannerPhrasesFilter (Live) methods get the ad ID as input and return the keywords for the ad group the ad belongs to.

Similarly, the GetBannersTags (Live) method gets the ad ID as input and returns the ad group's tags; the Get action for the Retargeting (Live) method returns the retargeting settings for the ad group.

Editing ad group parameters

Ad group parameters are changed by editing any one of the ads that is in the group.

To change the ad group parameters (AdGroupName, Geo, Phrases, or MinusKeywords), call the CreateOrUpdateBanners (Live) method and pass BannerID, all the ad parameters, and all the ad group parameters as input. New values of the AdGroupName, Geo, Phrases, and MinusKeywords parameters will be applied to the entire ad group.

If the input array for the CreateOrUpdateBanners (Live) method passes multiple ads from the same ad group, we recommend only setting the AdGroupName, Geo, Phrases, MinusKeywords, and AutoMinusWords parameters in one of them.

Attention.

If a CreateOrUpdateBanners (Live) method call passes one of an ad group's ads with one set of keywords, but the next call passes another ad from the same ad group with a different set of keywords, the first set of keywords will be replaced with the second one.

If a CreateOrUpdateBanners (Live) method call passes multiple ads that belong to the same ad group but with different sets of keywords, only one of these sets will be saved (not a combination of the sets).

To change bids, call the SetAutoPrice (Live) or UpdatePrices (Live) method. New bids will apply to all the ads in the ad group. When calling the SetAutoPrice (Live) method, we recommend passing only one of the ads from an ad group in the BannerIDS input array.

To change tags, call the UpdateBannersTags (Live) method and input the BannerID parameter (any one of the ads in the ad group) and the new array of tags. New tags will apply to all ads in the ad group.

To add retargeting settings, call the Retargeting (Live) method (the Add action) and set the ID of any one of the group's ads in the AdID parameter. Retargeting settings will apply to all the ads in the ad group.

Deleting ad groups

An ad group is deleted automatically when the last ad is deleted from it.

Operations with ads

When the ModerateBanners (Live) method is called for one of the ads in an ad group, all the ads in this ad group that have the “Draft” status are submitted for moderation.

The following methods:

are executed for each ad separately. In particular, if you use the StopBanners (Live) method to stop displaying an ad, the other ads in this ad group will continue being displayed.

Attention. If you need to delete all the ads from an ad group and add new ones, first add the new ones. Otherwise, when you delete all the ads, the ad group will be deleted automatically, and you will get an error when trying to add new ads to it.

Checking for changes

If ad group parameters were changed (AdGroupName, Geo, Phrases, MinusKeywords, or AutoMinusWords), the GetChanges method shows whether there were changes for each of the ads in the ad group.

Getting statistics

Attention. The GetBanners (Live), GetBannerPhrases (Live), and GetBannerPhrasesFilter (Live) methods get the ad ID as input and return statistics on impressions and clicks for each keyword that are cumulative for all the ads in the ad group.

The GetBannersStat (Live) method, as well as the report generated using the CreateNewReport (Live) method, return statistics on impressions, clicks, and CPC for each of the ads separately. When you get the ID of the ad group for each ad using the GetBanners (Live) method, you can compare statistics for ads in the same ad group, calculate cumulative statistics for an ad group, and so on.