Ad group

An ad group consists of a set of ads and shared criteria for displaying these ads. You can use groups to test different variations of ads and automatically determine which of them is the most attractive for the audience. For more information, see Experimenting with ads in Yandex Direct Help.

Service

Use the AdGroups service for managing groups.

Methods

add | update | delete | get

To manage an ad group in a unified performance campaign, use the URL: https://api.direct.yandex.com/v501/.

Restrictions

The group type must match the campaign type.

Operations with groups are not possible in archived campaigns.

To get the limit on the number of ad groups in a campaign for an advertiser, use the method Clients.get or AgencyClients.get (see the ADGROUPS_TOTAL_PER_CAMPAIGN element in the Restrictions array).

Ad group type

The group type is set when creating an ad group and can't be changed.

The set of group parameters depends on its type.

The parameters common to all types of groups are the name, display region, shared negative keywords for a group, as well as tags. When creating or editing a group, pass these parameters within the AdGroups structure of the add and update methods. To get these parameters, list the parameter names in the FieldNames input parameter for the get method.

The parameters that depend on the group type are passed in the child structure with the corresponding name.

The Yandex Direct API currently supports the following types of groups:

TEXT_AD_GROUP — A group of Text & Image ads.

For this type of group, you can additionally specify the feed ID and product category IDs for generating Text & Image ads.

A group can have child objects — ads, keywords, autotargetings, and audience targets. Bid adjustments can be set for a group.
SMART_AD_GROUP — A group of smart banners.

For this type of group, you must specify the feed ID to use for generating smart banners. Optionally, you can specify the names of feed elements to take the ad title and text from. For more information about smart banners, see Smart banners in Yandex Direct Help.

To create or edit a group, use the add or update method with the group-specific parameters defined in the SmartAdGroup structure.

When getting group parameters, list the names of parameters that are shared across all group types in the FieldNames input parameter, and list the names of parameters that are specific to this group type in the SmartAdGroupFieldNames input parameter of the get method.

A group can have child objects — ads and filters. Bid adjustments can be set for a group.
MOBILE_APP_AD_GROUP — A group for advertising mobile apps.

For this type of group, you must additionally specify a link to the app in App Store or Google Play, along with the types of devices, types of internet connection, and earliest OS version that the ad can be displayed on. For more information about ads for mobile apps, see Ads for Mobile Apps in Yandex Direct Help.

Alert

All ad groups in the same campaign must have the same app link.

To create or edit a group, use the add or update method with the group-specific parameters defined in the MobileAppAdGroup structure.

When getting group parameters, list the names of parameters that are shared across all group types in the FieldNames input parameter, and list the names of parameters that are specific to this group type in the MobileAppAdGroupFieldNames input parameter of the get method.

A group can have child objects — ads, keywords, autotargetings, and audience targets. Bid adjustments can be set for a group.
DYNAMIC_TEXT_AD_GROUP — A group of dynamic ads. For more information about dynamic ads, see Dynamic ads in Yandex Direct Help.

There are two subtypes of dynamic ad groups:
- WEBPAGE — The data source for generating ads is website pages.
  
  For this subtype, you must additionally specify the advertised domain.
  
  To create or edit a group, use the add or update method with the group-specific parameters defined in the DynamicTextAdGroup structure.
  
  When getting group parameters, list the names of parameters that are shared across all group types in the FieldNames input parameter, and list the names of parameters that are specific to this group type in the DynamicTextAdGroupFieldNames input parameter of the get method.
  
  The group can have child objects: ads and dynamic ad targets. Bid adjustments can be set for a group.
- FEED — The data source for generating ads is a feed (a file with product offers).
  
  When getting group parameters, list the names of parameters that are shared across all group types in the FieldNames input parameter, and list the names of parameters that are specific to this group type in the DynamicTextFeedAdGroupFieldNames input parameter of the get method.
  
  The group can have child objects: ads and filters for selecting product offers from the feed. You must use the web interface for managing filters. Bid adjustments can be set for a group.
CPM_BANNER_AD_GROUP — A group of display banners.

It only has the parameters that are common to all types of groups.

There are two subtypes for display banner groups:
- KEYWORDS — The group can have child objects: ads and keywords. Bid adjustments can be set for a group.
  To create this type of group, pass an empty CpmBannerKeywordsAdGroup structure in the add method.
- USER_PROFILE — The group can have child objects: ads and audience targets by user profile. Negative keywords are not allowed in this type of group.
  To create this type of group, pass an empty CpmBannerUserProfileAdGroup structure in the add method.
CPM_VIDEO_AD_GROUP: A group of display video ads in a display campaign.

It only has the parameters that are common to all types of groups. Negative keywords are not allowed in these groups.

Alert

The Gather audience by completion rate setting is currently not supported in the API.

The group can have child objects: ads and audience targets by user profile.
UNIFIED_AD_GROUP — A unified performance group.

This group can include ads with the following types: TextAd, TextImageAd, TextAdBuilderAd, and ShoppingAd. Note that in a unified performance group, you can't specify the following fields for the TextAd type:
- TurboPageId;
- VCardId;
- Mobile="YES";
- PreferVCardOverBusiness="YES".
Similarly, you can't specify TurboPageId for TextImageAd and TextAdBuilderAd types in a unified performance group.

The group is created with autotargeting disabled in YAN.

Ad group status

The Status parameter reflects the overall result of reviewing keywords. Keywords are submitted for review automatically when one of the group's ads is submitted for moderation.

Status	Description
DRAFT	The group has been created but has not yet been submitted for review.
MODERATION	The group is under review.
PREACCEPTED	The group has been automatically accepted for displays, but will be further reviewed by a moderator.
ACCEPTED	At least one of the group's keywords was approved after review (some of them may have been rejected).
REJECTED	All keywords were rejected.

Ad group serving status

The ServingStatus parameter reflects whether the targeting criteria in the group are eligible for ad serving.

Serving status	Description
ELIGIBLE	Eligible for ad serving.
RARELY_SERVED	"Rarely served" — With the current settings, ads are rarely served. For example, users don't search for the specified keywords.

Was the article helpful?

Campaign parameters