Ad

An ad consists of advertising materials. The set of parameters for an ad depends on its type.

Learn more

• Running an advertising campaign.

Service

Use the Ads service for managing ads.

Methods

add | update | delete | suspend | resume | archive | unarchive | moderate |get

To manage product ads, use this URL: https://api.direct.yandex.com/v501/.

Restrictions

The ad type must match the group type. See the table in Ad type.

Operations with ads are not possible in archived campaigns.

To get the limit on the number of ads per group for an advertiser, use the method Clients.get or AgencyClients.get (see the ADS_TOTAL_PER_ADGROUP element in the Restrictions array).

For restrictions on ad parameters, see Quantitative restrictions in Yandex Direct Help.

Ad type

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

The following types of ads are currently available:

• TEXT_AD: A Text & Image (regular) ad.

  The ad contains a title and ad text, as well as a link to the advertised website. You can also include a Turbo page, display link, image, video extension, price, sitelinks, ad callouts, and the ID of your business profile in Yandex Maps. If the Turbo page, vCard, or business profile ID is included, the website link is optional. The ad can be automatically assigned an age label. In this case, you can change the label.

  To create or edit a Text & Image ad, use the add or update method with the ad parameters defined in the TextAd structure.

  To get the ad parameters (other than price parameters), list the parameter names in the TextAdFieldNames input parameter for the get method. To get the price parameters, list their names in the TextAdPriceExtensionFieldNames input parameter.

• SMART_AD: A smart banner.

  The ad contains a creative that was created in Ad Builder.

  To create or edit an ad, use the add or update method with the ad parameters defined in the SmartAdBuilderAd structure.

  To get the ad parameters, list the parameter names in the SmartAdBuilderAdFieldNames input parameter of the get method.

• MOBILE_APP_AD: An ad for advertising mobile apps.

  The ad contains a title, text, and age restriction, as well as a label for the button to download or install. You can also add an image, specify a tracking link to track installs, and include a set of add-ons that need to be downloaded from the app store (icon, rating, and so on). For more information about ads for mobile apps, see Ads for Mobile Apps in Yandex Direct Help.

  To create or edit an ad for mobile app advertising, use the add or update method with the ad parameters defined in the MobileAppAd structure.

  To get the parameters of a mobile ad, list the parameter names in the MobileAppAdFieldNames input parameter of the get method.

• DYNAMIC_TEXT_AD: A dynamic ad.

  The ad contains text. You can also include an image, a set of sitelinks, and callouts in an ad. For more information about dynamic ads, see Dynamic ads in Yandex Direct Help.

  To create or edit a dynamic ad, use the add or update method with the ad parameters defined in the DynamicTextAd structure.

  To get the ad parameters, list the parameter names in the DynamicTextAdFieldNames input parameter for the get method.

• IMAGE_AD: An image ad.

  There are four subtypes of image ads:

  • TEXT_IMAGE_AD

    The ad contains an image and a link to the advertised website and/or Turbo page.

    To create or edit an ad, use the add or update method with the ad parameters defined in the TextImageAd structure.

    To get the ad parameters, list the parameter names in the TextImageAdFieldNames input parameter for the get method.

  • MOBILE_APP_IMAGE_AD

    The ad contains an image. You can also add a tracking link to the ad to track app installs.

    To create or edit an ad, use the add or update method with the ad parameters defined in the MobileAppImageAd structure.

    To get the ad parameters, list the parameter names in the MobileAppImageAdFieldNames input parameter for the get method.

  • TEXT_AD_BUILDER_AD

    The ad contains a creative that was designed in Ad Builder, as well as a link to the advertised website and/or Turbo page.

    To create or edit an ad, use the add or update method with the ad parameters defined in the TextImageAd structure.

    To get the ad parameters, list the parameter names in the TextAdBuilderAdFieldNames input parameter for the get method.

  • MOBILE_APP_AD_BUILDER_AD

    The ad contains a creative that was created in Ad Builder. You can also add a tracking link to the ad to track app installs.

    To create or edit an ad, use the add or update method with the ad parameters defined in the MobileAppImageAd structure.

    To get the ad parameters, list the parameter names in the MobileAppAdBuilderAdFieldNames input parameter for the get method.

  Alert

  Image ads are only displayed in ad networks (the Yandex Advertising Network and external networks); they are not displayed in search results.

  Displays of image ads are possible only if the bid on a keyword or audience target meets the minimum CPC for an ad containing an image, which you can find on the Minimum and maximum CPC page.

  For more information about image ads, see Image ads in Yandex Direct Help.

• CPC_VIDEO_AD: A video ad (in a "Text & Image Ads" or "Ads for mobile apps" campaign).

  The ad contains a creative that was designed in Ad Builder, as well as a link to the advertised website and/or Turbo page.

  To create or edit an ad, use the add or update method with the ad parameters defined in the CpcVideoAdBuilderAd structure.

  To get the ad parameters, list the parameter names in the CpcVideoAdBuilderAdFieldNames input parameter of the get method.

  The "Ads for mobile apps" campaigns use a separate subtype for video ads — MOBILE_APP_CPC_VIDEO_AD_BUILDER_AD.

  • MOBILE_APP_CPC_VIDEO_AD_BUILDER_AD

    Such an ad contains a creative that was created in Ad Builder. You can also add a tracking link to the ad to track app installs.

    To create or edit an ad, use the add or update method with the ad parameters defined in the MobileAppCpcVideoAdBuilderAd structure.

    To get the ad parameters, list the parameter names in the MobileAppCpcVideoAdBuilderAdFieldNames input parameter of the get method.

• CPM_BANNER_AD: A display banner.

  The ad contains a creative that was uploaded in the web interface or designed in the Ad Builder, as well as a link to the advertised website and/or Turbo page. You can also add a Yandex Audience pixel and an ADFOX impression tag to your ads.

  To create or edit an ad, use the add or update method with the ad parameters defined in the CpmBannerAdBuilderAd structure.

  To get the ad parameters, list the parameter names in the CpmBannerAdBuilderAdFieldNames input parameter of the get method.

• CPM_VIDEO_AD: A display video ad in a display campaign.

  The ad contains a creative that was designed in Ad Builder, as well as a link to the advertised website and/or Turbo page. You can also add an ADFOX impression tag to an ad.

  To create or edit an ad, pass the parameters in the CpmBannerAdBuilderAd structure for the add or update method.

  To get the ad parameters, list the parameter names in the CpmBannerAdBuilderAdFieldNames input parameter of the get method.

• SHOPPING_AD: A product ad in a "unified performance campaign".

  To create or edit an ad, use the add or update method with the ad parameters defined in the ShoppingAd structure.

  To get the ad parameters, list the parameter names in the ShoppingAdFieldNames input parameter of the get method.

• LISTING_AD: An ad for catalog pages in a "unified performance campaign".

  To create or edit an ad, use the add or update method with the ad parameters defined in the ListingAd structure.

  To retrieve ad parameters, list the parameter names in the ListingAdFieldNames input parameter of the get method.

The Type, Subtype, Status, State, StatusClarification, AdCategories, and AgeLabel parameters are common to all types of ads. To get these parameters, list the desired parameter names in the FieldNames input parameter for the get method.

The table below shows how ad types correspond to group types.

Ad status and state

The State parameter reflects the current state of the ad.

The Status parameter reflects the result of reviewing the ad.

Special category

During the review, an ad can be assigned a label stating that the advertised product or service belongs to a special category. In this case, the ad is given the AdCategories parameter, which cannot be changed.

For certain categories, ad displays are forbidden. For others, ads are served with a special warning in accordance with the legislation of the Russian Federation.

To get the reference list of special categories, use the Dictionaries.get method.

These categories cannot be changed, assigned, or removed via the API. If you disagree with the category assigned, contact the Support service.

Age label

The AgeLabel parameter contains the age-appropriate category of the advertised product if this category is required to be specified by the federal law of the Russian Federation "About advertising". Assigning the age category depends on the ad type.

Ad extensions

You can use the add and update methods to link a vCard, image, video extension, set of sitelinks, or callouts with an ad (depending on the ad type). For detailed instructions, see Ad extensions.

Video extensions are only displayed in ad networks (the Yandex Advertising Network and external networks); they are not displayed in search results.

Bids for images and video extensions

An image or video extension can be displayed only if the bid for the keyword or audience target meets the minimum CPC for an ad containing an image, which you can find on the Minimum and maximum CPC page. Otherwise, the ad is shown without the image or video extension.

Result of reviewing add-ons

The vCard, image, video extension, and sitelinks are not reviewed in isolation, but together with the ad. They are sent for moderation automatically if the ad is under moderation or already passed moderation.

The get method returns the result of reviewing the vCard (VCardModeration structure), image (AdImageModeration structure), sitelinks (SitelinksModeration structure), or video extension (Status parameter in the VideoExtension structure).

Rules for selecting product ads.

The selection rule consists of three parameters:

• Operand — The feed field.
• Operator — The comparison operator.
• Arguments — An array of values to compare the field value in the feed with.

For a description of the fields for each type of feed, see Configuring filters in Yandex Direct Help.

The compatibility of feed fields and operators depends on the feed:

Examples

The value contains one of the specified rows:

    {
      "Operand": "mark_id",
      "Operator": "CONTAINS_ANY",
      "Arguments": ["Audi","Opel"]
    }

Range: price from 111 to 222 or 3000 to 10000:

    {
      "Operand": "price",
      "Operator": "IN_RANGE",
      "Arguments": ["111-222", "3000-10000"]
    }

Value from the list:

    {
      "Operand": "wheel",
      "Operator": "EQUALS_ANY",
      "Arguments": ["левый"]
    }

Ad labeling

The ErirAdDescription parameter contains a description of an ad object.

The AutogeneratedErirAdDescription contains an automatically generated description of an ad object.

For more information about ad labeling, see here.