Ad
An ad consists of advertising materials. The set of parameters for an ad depends on its type.
Service
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 the Help for Yandex Direct.
- An ad in Belarusian can only be added to a group that has the display region restricted to Belarus.
- An ad in Kazakh can only be added to a group that has the display region restricted to Kazakhstan.
- An ad in Turkish can only be added to a group that has the display region restricted to Turkey.
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, set of sitelinks, vCard, ad callouts, and the Yandex Maps business profile ID. 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, pass its parameters in the TextAd structure of the add or update method.
To get the ad parameters (other than price parameters), list the parameter names in the TextAdFieldNames input parameter of 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, pass its parameters in the SmartAdBuilderAd structure of the add or update method.
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 advertising mobile apps, see Ads for Mobile Apps in the Help for Yandex Direct.
To create or edit an ad for mobile app advertising, pass its parameters in the MobileAppAd structure of the add or update method.
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, a vCard, and callouts with an ad. For more information about dynamic ads, see Dynamic ads in the Help for Yandex Direct.
To create or edit a dynamic ad, pass its parameters in the DynamicTextAd structure of the add or update method.
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, pass its parameters in the TextImageAd structure of the add or update method.
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, pass its parameters in the MobileAppImageAd structure of the add or update method.
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, pass its parameters in the TextAdBuilderAd structure of the add or update method.
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, pass its parameters in the MobileAppAdBuilderAd structure of the add or update method.
To get the ad parameters, list the parameter names in the MobileAppAdBuilderAdFieldNames input parameter for the get method.
Attention.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 the Help for Yandex Direct.
CPC_VIDEO_AD: A video ad in “Text & Image Ads” or “Ads for mobile apps” campaigns.
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, pass its parameters in the CpcVideoAdBuilderAd structure of the add or update method.
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, pass its parameters in the MobileAppCpcVideoAdBuilderAd structure of the add or update method.
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, pass its parameters in the CpmBannerAdBuilderAd structure of the add or update method.
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 its parameters in the CpmVideoAdBuilderAd structure of the add or update method.
To get the ad parameters, list the parameter names in the CpmVideoAdBuilderAdFieldNames 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 of the get method.
The table below shows how ad types correspond to group types.
Ad group type | Possible types of ads |
---|---|
TEXT_AD_GROUP | TEXT_AD IMAGE_AD with subtypes TEXT_IMAGE_AD and TEXT_AD_BUILDER_AD CPC_VIDEO_AD |
SMART_AD_GROUP | SMART_AD |
MOBILE_APP_AD_GROUP | MOBILE_APP_AD IMAGE_AD with subtypes MOBILE_APP_IMAGE_AD and MOBILE_APP_AD_BUILDER_AD CPC_VIDEO_AD, the subtype MOBILE_APP_CPC_VIDEO_AD_BUILDER_AD |
DYNAMIC_TEXT_AD_GROUP | DYNAMIC_TEXT_AD |
CPM_BANNER_AD_GROUP | CPM_BANNER_AD |
CPM_VIDEO_AD_GROUP | CPM_VIDEO_AD |
UNIFIED_AD_GROUP | TEXT_AD IMAGE_AD with subtypes TEXT_IMAGE_AD and TEXT_AD_BUILDER_AD SHOPPING_AD, LISTING_AD |
Ad group type | Possible types of ads |
---|---|
TEXT_AD_GROUP | TEXT_AD IMAGE_AD with subtypes TEXT_IMAGE_AD and TEXT_AD_BUILDER_AD CPC_VIDEO_AD |
SMART_AD_GROUP | SMART_AD |
MOBILE_APP_AD_GROUP | MOBILE_APP_AD IMAGE_AD with subtypes MOBILE_APP_IMAGE_AD and MOBILE_APP_AD_BUILDER_AD CPC_VIDEO_AD, the subtype MOBILE_APP_CPC_VIDEO_AD_BUILDER_AD |
DYNAMIC_TEXT_AD_GROUP | DYNAMIC_TEXT_AD |
CPM_BANNER_AD_GROUP | CPM_BANNER_AD |
CPM_VIDEO_AD_GROUP | CPM_VIDEO_AD |
UNIFIED_AD_GROUP | TEXT_AD IMAGE_AD with subtypes TEXT_IMAGE_AD and TEXT_AD_BUILDER_AD SHOPPING_AD, LISTING_AD |
Ad status and state
The State parameter reflects the current state of the ad.
State | Description |
---|---|
SUSPENDED | Ad displays were stopped by the owner using the suspend method or in the web interface. |
OFF_BY_MONITORING | Ad displays are automatically stopped by site availability monitoring. |
ON | The ad is active, belongs to an active campaign, and can be served (if the campaign has funds, time targeting settings allow impressions, and so on). |
OFF | The ad is inactive (a draft, pending review, or rejected), or belongs to an inactive or suspended campaign. |
ARCHIVED | The ad has been archived (using the archive method, or in the web interface), or belongs to an archived campaign. |
State | Description |
---|---|
SUSPENDED | Ad displays were stopped by the owner using the suspend method or in the web interface. |
OFF_BY_MONITORING | Ad displays are automatically stopped by site availability monitoring. |
ON | The ad is active, belongs to an active campaign, and can be served (if the campaign has funds, time targeting settings allow impressions, and so on). |
OFF | The ad is inactive (a draft, pending review, or rejected), or belongs to an inactive or suspended campaign. |
ARCHIVED | The ad has been archived (using the archive method, or in the web interface), or belongs to an archived campaign. |
The Status parameter reflects the result of reviewing the ad.
Status | Description |
---|---|
DRAFT | The ad has been created but has not yet been submitted for review. |
MODERATION | The ad is under review. |
PREACCEPTED | The ad has been automatically accepted for displays, but will be further reviewed by a moderator. |
ACCEPTED | The ad was accepted after review. |
REJECTED | The ad was rejected after review. |
Status | Description |
---|---|
DRAFT | The ad has been created but has not yet been submitted for review. |
MODERATION | The ad is under review. |
PREACCEPTED | The ad has been automatically accepted for displays, but will be further reviewed by a moderator. |
ACCEPTED | The ad was accepted after review. |
REJECTED | The ad was rejected after review. |
If the ad was edited, and the new version is pending review (the MODERATION status) or was immediately rejected after review (the REJECTED status), the previous version of the ad continues being displayed if it was not suspended. In this case, the ad has the ON status.
If the new version of the ad was automatically accepted for display after editing (PREACCEPTED), and then it was rejected (REJECTED), displays of the previous version will not be resumed.
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 assigned an unchangeable AdCategories parameter.
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 support.
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 “On Advertising”. Assigning the age category depends on the ad type.
The value of the age label depends on whether the ad belongs to the special category BABY_FOOD:
For ads that belong to the BABY_FOOD category, it is the age of the infant in months: "MONTHS_0", "MONTHS_1", "MONTHS_2", ..., "MONTHS_12".
For all other ads, it is the age that the informational product is appropriate for. Possible values: "AGE_0", "AGE_6", "AGE_12", "AGE_16", "AGE_18".
If an ad does not have an age label, this parameter can't be set (the update method ignores the parameter value).
The API can only be used to change the value of the age category if the ad has one. To add or remove the age category, contact support.
An age label is assigned to all ads. Possible values: "AGE_0", "AGE_6", "AGE_12", "AGE_16", "AGE_18".
The label can be specified when creating the ad. Default value: "AGE_18". You can change the value of the label when editing the ad, but you can't remove the label.
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). To learn how to do this, 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. This happens automatically when the ad is sent for review or has already passed it.
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).
Review status | Description |
---|---|
DRAFT | The ad extension has not been submitted for review. |
MODERATION | The ad extension is under review. |
ACCEPTED | The ad extension was accepted after review. The ad will contain the add-on when it is shown. |
REJECTED | The ad extension was rejected after review. |
UNKNOWN | The status is unknown. This value is used for backward compatibility and for displaying statuses that are not supported in this version of the API. |
Review status | Description |
---|---|
DRAFT | The ad extension has not been submitted for review. |
MODERATION | The ad extension is under review. |
ACCEPTED | The ad extension was accepted after review. The ad will contain the add-on when it is shown. |
REJECTED | The ad extension was rejected after review. |
UNKNOWN | The status is unknown. This value is used for backward compatibility and for displaying statuses that are not supported in this version of the API. |
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 the Help for Yandex Direct.
The compatibility of feed fields and operators depends on the feed:
- 0
- 1
- 0
- 1
- 1
- 2
- 3
- 4
- 5
- 1
- 2
- 3
- 4
- 5
- left
- right
- yes
- none
- in stock
- on order
- left
- right
- yes
- none
- in stock
- on order
Feed field | Operators | Restrictions on values |
---|---|---|
categoryId | GREATER_THAN, LESS_THAN | One number |
EQUALS_ANY | Max 20,000 numbers | |
RANGE | Max 10 ranges. See example. | |
id | GREATER_THAN, LESS_THAN | One number |
EQUALS_ANY | Max 50 numbers | |
RANGE | Max 10 ranges. See example. | |
market_category typePrefix vendor | CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
EXISTS | Pass the value 1 | |
description model name | CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
url | EQUALS,CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
oldprice price | GREATER_THAN, LESS_THAN | Single number, up to 2 decimal places |
EQUALS_ANY | Max 50 numbers, up to 2 decimal places | |
RANGE | Max 10 ranges, up to 2 decimal places. See the example. | |
EXISTS | Pass the value 1 | |
adult manufacturer_warranty pickup store | EQUALS_ANY | Acceptable values: |
EXISTS | Pass the value 1 | |
age | EQUALS_ANY | Acceptable values: integer from 0 to 12, 16, or 18. |
EXISTS | Pass the value 1 |
Feed field | Operators | Restrictions on values |
---|---|---|
categoryId | GREATER_THAN, LESS_THAN | One number |
EQUALS_ANY | Max 20,000 numbers | |
RANGE | Max 10 ranges. See example. | |
id | GREATER_THAN, LESS_THAN | One number |
EQUALS_ANY | Max 50 numbers | |
RANGE | Max 10 ranges. See example. | |
market_category typePrefix vendor | CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
EXISTS | Pass the value 1 | |
description model name | CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
url | EQUALS,CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
oldprice price | GREATER_THAN, LESS_THAN | Single number, up to 2 decimal places |
EQUALS_ANY | Max 50 numbers, up to 2 decimal places | |
RANGE | Max 10 ranges, up to 2 decimal places. See the example. | |
EXISTS | Pass the value 1 | |
adult manufacturer_warranty pickup store | EQUALS_ANY | Acceptable values: |
EXISTS | Pass the value 1 | |
age | EQUALS_ANY | Acceptable values: integer from 0 to 12, 16, or 18. |
EXISTS | Pass the value 1 |
Feed field | Operators | Restrictions on values |
---|---|---|
Rsis | GREATER_THAN, LESS_THAN | Single number, up to 2 decimal places |
EQUALS_ANY | Max 50 numbers, up to 2 decimal places | |
RANGE | Max 10 ranges, up to 2 decimal places. See the example. | |
Description max_score name location url | CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
class | EQUALS_ANY | Acceptable values: |
EXISTS | Pass the value 1 | |
OfferID Score | GREATER_THAN, LESS_THAN | Single integer |
EQUALS_ANY | Max 50 integers | |
RANGE | Max 10 ranges or integers. See the example. |
Feed field | Operators | Restrictions on values |
---|---|---|
Rsis | GREATER_THAN, LESS_THAN | Single number, up to 2 decimal places |
EQUALS_ANY | Max 50 numbers, up to 2 decimal places | |
RANGE | Max 10 ranges, up to 2 decimal places. See the example. | |
Description max_score name location url | CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
class | EQUALS_ANY | Acceptable values: |
EXISTS | Pass the value 1 | |
OfferID Score | GREATER_THAN, LESS_THAN | Single integer |
EQUALS_ANY | Max 50 integers | |
RANGE | Max 10 ranges or integers. See the example. |
Feed field | Operators | Restrictions on values |
---|---|---|
body_type color folder_id mark_id | CONTAINS_ANY, NOT_CONTAINS_ALL, | Max 50 lines, max 175 characters per line |
wheel | CONTAINS_ANY | Recommended values: |
metallic | EQUALS_ANY | Recommended values: |
availability | EQUALS_ANY | Recommended values: |
year | EQUALS_ANY | Max 10 numbers |
url | CONTAINS_ANY, NOT_CONTAINS_ALL, EQUALS_ANY | Max 50 lines, max 175 characters per line |
price | GREATER_THAN, LESS_THAN | Single integer |
EQUALS_ANY | Max 50 integers | |
RANGE | Max 10 ranges. See example. |
Feed field | Operators | Restrictions on values |
---|---|---|
body_type color folder_id mark_id | CONTAINS_ANY, NOT_CONTAINS_ALL, | Max 50 lines, max 175 characters per line |
wheel | CONTAINS_ANY | Recommended values: |
metallic | EQUALS_ANY | Recommended values: |
availability | EQUALS_ANY | Recommended values: |
year | EQUALS_ANY | Max 10 numbers |
url | CONTAINS_ANY, NOT_CONTAINS_ALL, EQUALS_ANY | Max 50 lines, max 175 characters per line |
price | GREATER_THAN, LESS_THAN | Single integer |
EQUALS_ANY | Max 50 integers | |
RANGE | Max 10 ranges. See example. |
Feed field | Operators | Restrictions on values |
---|---|---|
url | EQUALS_ANY, CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
description name | CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
EXISTS | Pass the value 1 | |
price oldprice | GREATER_THAN, LESS_THAN | Single number, up to 2 decimal places |
EQUALS_ANY | Max 50 numbers, up to 2 decimal places | |
RANGE | Max 10 ranges, up to 2 decimal places. See the example. |
Feed field | Operators | Restrictions on values |
---|---|---|
url | EQUALS_ANY, CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
description name | CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
EXISTS | Pass the value 1 | |
price oldprice | GREATER_THAN, LESS_THAN | Single number, up to 2 decimal places |
EQUALS_ANY | Max 50 numbers, up to 2 decimal places | |
RANGE | Max 10 ranges, up to 2 decimal places. See the example. |
Feed field | Operators | Restrictions on values |
---|---|---|
category description name second_title | CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
EXISTS | Pass the value 1 | |
url | EQUALS_ANY, CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
price sale_price | GREATER_THAN, LESS_THAN | One number, up to two decimal places |
IN_RANGE | Max 10 ranges, up to two decimal places | |
EQUALS_ANY | Max 50 values, up to two decimal places |
Feed field | Operators | Restrictions on values |
---|---|---|
category description name second_title | CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
EXISTS | Pass the value 1 | |
url | EQUALS_ANY, CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
price sale_price | GREATER_THAN, LESS_THAN | One number, up to two decimal places |
IN_RANGE | Max 10 ranges, up to two decimal places | |
EQUALS_ANY | Max 50 values, up to two decimal places |
Feed field | Operators | Restrictions on values |
---|---|---|
Category destination origin Title | CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
EXISTS | Pass the value 1 | |
url | EQUALS_ANY, CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
price sale_price | GREATER_THAN, LESS_THAN | One number, up to two decimal places |
IN_RANGE | Max 10 ranges, up to two decimal places | |
EQUALS_ANY | Max 50 numbers, up to two decimal places |
Feed field | Operators | Restrictions on values |
---|---|---|
Category destination origin Title | CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
EXISTS | Pass the value 1 | |
url | EQUALS_ANY, CONTAINS_ANY, NOT_CONTAINS_ALL | Max 50 lines, max 175 characters per line |
price sale_price | GREATER_THAN, LESS_THAN | One number, up to two decimal places |
IN_RANGE | Max 10 ranges, up to two decimal places | |
EQUALS_ANY | Max 50 numbers, up to two decimal places |
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": ["left"] }
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.