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 the Help for Yandex Direct.

Service

Use the AdGroups service for managing groups.

Methods

add | update | delete | get

To manage unified performance groups, 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. When creating or editing a group, pass these parameters in the AdGroups structure of the add or update method. To get these parameters, list the parameter names in the FieldNames input parameter of 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 the Help for Yandex Direct.

    To create or edit a group, provide the parameters specific to this group type in the SmartAdGroup structure of the add or update method.

    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 advertising mobile apps, see Ads for Mobile Apps in the Help for Yandex Direct.

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

    To create or edit a group, provide the parameters specific to this group type in the MobileAppAdGroup structure of the add or update method.

    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 the Help for Yandex Direct.

    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, the parameters specific to this type of group must be passed in the DynamicTextAdGroup structure for the add or update method.

      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.

    Restriction. 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.
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.
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.