get

Returns parameters of ads that match the specified criteria.

Learn more

Restrictions

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

The method returns a maximum of 10,000 objects.

Request

Request structure in JSON format:

{
  "method": "get",
  "params": { /* params */
    "SelectionCriteria": {  /* AdsSelectionCriteria */
      "Ids": [(long), ... ],
      "States": [( "OFF" | ... | "ARCHIVED" ), ... ],
      "Statuses": [( "ACCEPTED" | ... | "REJECTED" ), ... ],
      "CampaignIds": [(long), ... ],
      "AdGroupIds": [(long), ... ],
      "Types": [( "TEXT_AD" | "MOBILE_APP_AD" | "DYNAMIC_TEXT_AD" | "IMAGE_AD"
                  | "CPC_VIDEO_AD" | "CPM_BANNER_AD" | "CPM_VIDEO_AD"
                  | "SMART_AD" | "SHOPPING_AD" | "LISTING_AD" ), ... ],
      "Mobile": ( "YES" | "NO" ),
      "VCardIds": [(long), ... ],
      "SitelinkSetIds": [(long), ... ],
      "AdImageHashes": [(string), ... ],
      "VCardModerationStatuses": [( "ACCEPTED" | ... | "REJECTED" ), ... ],
      "SitelinksModerationStatuses": [( "ACCEPTED" | ... | "REJECTED" ), ... ],
      "AdImageModerationStatuses": [( "ACCEPTED" | ... | "REJECTED" ), ... ],
      "AdExtensionIds": [(long), ... ]
    }, /* required */
    "FieldNames": [( "AdCategories" | ... | "Subtype" ), ... ], /* required */
    "TextAdFieldNames": [( "AdImageHash" | ... | "BusinessId" | "PreferVCardOverBusiness" | "ErirAdDescription" | "AutogeneratedErirAdDescription" ), ... ],
    "TextAdPriceExtensionFieldNames": [( "Price" | "OldPrice" | "PriceCurrency" | "PriceQualifier" ), ... ],
    "MobileAppAdFieldNames": [( "AdImageHash" | ... | "TrackingUrl" | "ErirAdDescription" | "AutogeneratedErirAdDescription" ), ... ],
    "DynamicTextAdFieldNames": [( "AdImageHash" | ... | "AdExtensions" | "ErirAdDescription" | "AutogeneratedErirAdDescription" ), ... ],
    "TextImageAdFieldNames": [( "AdImageHash" | "Href" | "TurboPageId" | "TurboPageModeration" | "ErirAdDescription" | "AutogeneratedErirAdDescription" ), ... ],
    "MobileAppImageAdFieldNames": [( "AdImageHash" | "TrackingUrl" | "ErirAdDescription" | "AutogeneratedErirAdDescription" ), ... ],
    "TextAdBuilderAdFieldNames": [( "Creative" | "Href" | "TurboPageId" | "TurboPageModeration" | "ErirAdDescription" | "AutogeneratedErirAdDescription" ), ... ],
    "MobileAppAdBuilderAdFieldNames": [( "Creative" | "TrackingUrl" | "ErirAdDescription" | "AutogeneratedErirAdDescription" ), ... ],
    "MobileAppCpcVideoAdBuilderAdFieldNames" : [ ("Creative" | "TrackingUrl" | "ErirAdDescription" | "AutogeneratedErirAdDescription"), ... ],
    "CpcVideoAdBuilderAdFieldNames": [( "Creative" | "Href" | "TurboPageId" | "TurboPageModeration" | "ErirAdDescription" | "AutogeneratedErirAdDescription" ), ... ],
    "CpmBannerAdBuilderAdFieldNames": [( "Creative" | "Href" | "TrackingPixels" | "TurboPageId" | "TurboPageModeration" | "ErirAdDescription" | "AutogeneratedErirAdDescription" ), ... ],
    "CpmVideoAdBuilderAdFieldNames": [( "Creative" | "Href" | "TrackingPixels" | "TurboPageId" | "TurboPageModeration" | "ErirAdDescription" | "AutogeneratedErirAdDescription" ), ... ],
    "SmartAdBuilderAdFieldNames" : [( "Creative" ), ... ],
    "ShoppingAdFieldNames" : [ ("SitelinkSetId"|"SitelinksModeration"|"AdExtensions"|"BusinessId"|"FeedId"|"FeedFilterConditions"|"FeedProcessingStatus"|"TitleSources"|"TextSources"|"DefaultTexts") ],
    "ListingAdFieldNames" : [ ("SitelinkSetId"|"SitelinksModeration"|"AdExtensions"|"BusinessId"|"FeedId"|"FeedFilterConditions"|"FeedProcessingStatus"|"TitleSources"|"TextSources"|"DefaultTexts") ]
    "Page": {  /* LimitOffset */
      "Limit": (long),
      "Offset": (long)
    }
  }
}

Parameters are described below.

Parameter

Type

Description

Required

params structure (for JSON) / GetRequest (for SOAP)

SelectionCriteria

AdsSelectionCriteria

Criteria for selecting ads.

Yes

FieldNames

array of AdFieldEnum

Names of top-level parameters to get.

Yes

TextAdFieldNames

array of TextAdFieldEnum

Names of parameters to get for a Text & Image ad. See Ad type.

Note

If a different type of ad is selected according to SelectionCriteria, parameters from TextAdFieldNames are not returned.

No

TextAdPriceExtensionFieldNames

TextAdPriceExtensionFieldEnum

Names of price parameters to get for the product or service in the Text & Image ad.

Allowed only with the TextAdFieldNames parameter.

No

MobileAppAdFieldNames

array of MobileAppAdFieldEnum

Names of parameters to get for a mobile app ad.

Note

If a different type of ad is selected according to SelectionCriteria, parameters from MobileAppAdFieldNames are not returned.

No

DynamicTextAdFieldNames

array of DynamicTextAdFieldEnum

Names of parameters to get for a dynamic ad.

Note

If a different type of ad is selected according to SelectionCriteria, parameters from DynamicTextAdFieldNames are not returned.

No

TextImageAdFieldNames

array of TextImageAdFieldEnum

Names of parameters to get for an image ad that was created from an image (in a group of Text & Image ads).

Note

If a different type or subtype of ad is selected according to SelectionCriteria, parameters from TextImageAdFieldNames are not returned.

No

MobileAppImageAdFieldNames

array of MobileAppImageAdFieldEnum

Names of parameters to get for an image ad that was created from an image (in a group of mobile app ads).

Note

If a different type or subtype of ad is selected according to SelectionCriteria, parameters from MobileAppImageAdFieldNames are not returned.

No

TextAdBuilderAdFieldNames

array of TextAdBuilderAdFieldEnum

Names of parameters to get for an image ad that was created from a creative (in a group of Text & Image ads).

Note

If a different type or subtype of ad is selected according to SelectionCriteria, parameters from TextAdBuilderAdFieldNames are not returned.

No

MobileAppAdBuilderAdFieldNames

array of MobileAppAdBuilderAdFieldEnum

Names of parameters to get for an image ad that was created from a creative (in a group of mobile app ads).

Note

If a different type or subtype of ad is selected according to SelectionCriteria, parameters from MobileAppAdBuilderAdFieldNames are not returned.

No

MobileAppCpcVideoAdBuilderAdFieldNames

array of MobileAppCpcVideoAdBuilderAdFieldEnum

Names of parameters to get for a video ad that was created from a creative (in a group of ads for mobile apps).

Note

If a different type or subtype of ad is selected according to SelectionCriteria, parameters from MobileAppCpcVideoAdBuilderAdFieldNames are not returned.

No

CpcVideoAdBuilderAdFieldNames

array of CpcVideoAdBuilderAdFieldNames

Names of the requested video ad parameters in the “Text & Image Ads” campaigns. See

Note

If a different type or subtype of ad is selected according to SelectionCriteria, parameters from CpcVideoAdBuilderAdFieldNames are not returned.

No

CpmBannerAdBuilderAdFieldNames

array of CpmBannerAdBuilderAdFieldEnum

Names of parameters to get for a display banner. See Ad type.

Note

If a different type of ad is selected according to SelectionCriteria, parameters from CpmBannerAdBuilderAdFieldNames are not returned.

No

CpmVideoAdBuilderAdFieldNames

array of CpmVideoAdBuilderAdFieldNames

Names of the requested display video ad parameters in display campaigns. See Ad type.

Note

If a different type or subtype of ad is selected according to SelectionCriteria, parameters from CpmVideoAdBuilderAdFieldNames are not returned.

No

SmartAdBuilderAdFieldNames

array of SmartAdBuilderAdFieldEnum

The names of smart banner parameters to get. See Ad type.

Note

If a different type of ad is selected according to SelectionCriteria, parameters from SmartAdBuilderAdFieldNames are not returned.

No

ShoppingAdFieldNames

array of ShoppingAdFieldEnum

Names of requested product ad parameters. See Ad type.

Note

If a different type of ad is selected according to SelectionCriteria, parameters from ShoppingAdFieldNames are not returned.

No

ListingAdFieldNames

array of ListingAdFieldEnum

Names of parameters to get for a catalog page ad. See Ad type.

Note

If a different type of ad is selected according to SelectionCriteria, parameters from ShoppingAdFieldNames are not returned.

No

Page

LimitOffset

Structure that defines the page for paginated selection of data.

No

AdsSelectionCriteria structure

Ids

array of long

Selects ads with the specified IDs. From 1 to 10,000 items in the array.

At least one of the parameters: CampaignIds, AdGroupIds, or Ids (or all may be present)

AdGroupIds

array of long

Selects ads from the specified groups. From 1 to adgroup-ids-select items in the array.

CampaignIds

array of long

Selects ads from the specified campaigns. From 1 to 10 items in the array.

States

array of AdStateSelectionEnum

Selects ads based on the specified states. See Ad status and state.

No

Statuses

array of AdStatusSelectionEnum

Selects ads based on the specified statuses. See Ad status and state.

No

Types

array of AdTypeEnum

Selects ads based on the specified types. See Ad type.

Note

Filtering ads by subtype is not supported. When the IMAGE_AD value is specified, image ads are returned regardless of the subtype.

No

Mobile

YesNoEnum

Selects ads based on whether the ad is a mobile ad:

  • YES — Mobile ads.
  • NO — Regular ads.

If the YES value is set, only Text & Image ads are received. Don't set this value if you need to get other types of ads.

No

VCardIds

array of long

Selects ads with the specified vCards. From 1 to 50 items in the array.

If this parameter is set, only Text & Image ads and dynamic ads will be returned. Don't set it if you need to get other types of ads.

No

SitelinkSetIds

array of long

Selects ads with the specified sets of sitelinks. From 1 to 50 items in the array.

If this parameter is set, only Text & Image ads and dynamic ads will be returned. Don't set it if you need to get other types of ads.

No

AdImageHashes

array of string

Selects ads with the specified images. From 1 to 50 items in the array.

No

VCardModerationStatuses

array of ExtensionStatusSelectionEnum

Selects ads based on results of vCard review. For a description of the statuses, see the section Ad extensions.

If this parameter is set, only Text & Image ads and dynamic ads will be returned. Don't set it if you need to get other types of ads.

No

SitelinksModerationStatuses

array of ExtensionStatusSelectionEnum

Selects ads based on results of sitelink review: For a description of the statuses, see the section Ad extensions.

If this parameter is set, only Text & Image ads and dynamic ads will be returned. Don't set it if you need to get other types of ads.

No

AdImageModerationStatuses

array of ExtensionStatusSelectionEnum

Selects ads based on results of image review. For a description of the statuses, see the section Ad extensions.

If this parameter is set, only Text & Image ads, dynamic ads, and ads for mobile apps will be returned. Don't set it if you need to get other types of ads.

No

AdExtensionIds

array of long

Selects ads with the specified extensions. From 1 to 50 items in the array.

If this parameter is set, only Text & Image ads and dynamic ads will be returned. Don't set it if you need to get other types of ads.

No

Response

Response structure in JSON format:

{
  "result": { /* result */
    "Ads": [{  /* AdGetItem */
      "Id": (long),
      "CampaignId": (long),
      "AdGroupId": (long),
      "Status": ( "ACCEPTED" | ... | "UNKNOWN" ),
      "State": ( "OFF" | ... | "UNKNOWN" ),
      "StatusClarification": (string),
      "AdCategories": {  /* ArrayOfAdCategoryEnum */
        "Items": [( "ABORTION" | ... | "TOBACCO" ), ... ] /* required */
      }, /* nillable */
      "AgeLabel": ( "AGE_0" | ... | "MONTHS_12"), /* nillable */
      "Type": ( "TEXT_AD" | "MOBILE_APP_AD" | "DYNAMIC_TEXT_AD" | "IMAGE_AD" | "CPC_VIDEO_AD"
                | "CPM_BANNER_AD" | "CPM_VIDEO_AD" | "SMART_AD" | "SHOPPING_AD" | "LISTING_AD" ),
      "Subtype": ( "NONE" | "TEXT_IMAGE_AD" | "MOBILE_APP_IMAGE_AD" | "MOBILE_APP_CPC_VIDEO_AD_BUILDER_AD" | "TEXT_AD_BUILDER_AD" | "MOBILE_APP_AD_BUILDER_AD" ),
      "TextAd": {  /* TextAdGet */
        "Title": (string),
        "Title2": (string), /* nillable */
        "Text": (string),
        "Href": (string), /* nillable */
        "Mobile": ( "YES" | "NO" ),
        "DisplayDomain": (string), /* nillable */
        "DisplayUrlPath": (string), /* nillable */
        "VCardId": (long), /* nillable */
        "AdImageHash": (string), /* nillable */
        "SitelinkSetId": (long), /* nillable */
        "DisplayUrlPathModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string)
        }, /* nillable */
        "VCardModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string)
        }, /* nillable */
        "SitelinksModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string)
        }, /* nillable */
        "AdImageModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string)
        }, /* nillable */
        "AdExtensions": [{  /* AdExtensionAdGetItem */
          "AdExtensionId": (long), /* required */
          "Type": ( "CALLOUT" | "UNKNOWN" ) /* required */
        }, ... ],
        "VideoExtension": {  /* VideoExtensionGetItem */
          "CreativeId": (long), /* required */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ),
          "ThumbnailUrl": (string), /* required */
          "PreviewUrl": (string) /* required */
        }, /* nillable */
        "PriceExtension": {  /* PriceExtensionGetItem */
          "Price": (long),
          "OldPrice": (long), /* nillable */
          "PriceQualifier": ( "FROM" | "UP_TO" | "NONE" ),
          "PriceCurrency": ( "RUB" | "BYN" | "CHF" | "EUR" | "KZT" | "TRY" | "UAH" | "USD" | "UZS" )
        }, /* nillable */
        "TurboPageId": (long), /* nillable */
        "TurboPageModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string)
        }, /* nillable */
        "BusinessId": (long) /* nillable */,
        "PreferVCardOverBusiness": ( "YES" | "NO" ),
        "ErirAdDescription" : (string), /* nillable */
        "AutogeneratedErirAdDescription" : (string) /* nillable */
      },
      "DynamicTextAd": {  /* DynamicTextAdGet */
        "VCardId": (long), /* nillable */
        "AdImageHash": (string), /* nillable */
        "SitelinkSetId": (long), /* nillable */
        "VCardModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string)
        }, /* nillable */
        "SitelinksModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string)
        }, /* nillable */
        "AdImageModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string)
        }, /* nillable */
        "AdExtensions": [{  /* AdExtensionAdGetItem */
          "AdExtensionId": (long), /* required */
          "Type": ( "CALLOUT" | "UNKNOWN" ) /* required */
        }, ... ],
        "Text": (string)
      },
      "MobileAppAd": {  /* MobileAppAdGet */
        "Title": (string),
        "Text": (string),
        "TrackingUrl": (string), /* nillable */
        "Action": ( "DOWNLOAD" | "GET" | "INSTALL" | "MORE" | "OPEN" | "UPDATE" | "PLAY" | "BUY_AUTODETECT" ),
        "AdImageHash": (string), /* nillable */
        "Features": [{  /* MobileAppAdFeatureGetItem */
          "Feature": ( "PRICE" | "ICON" | "CUSTOMER_RATING" | "RATINGS" ), /* required */
          "Enabled": ( "YES" | "NO" ), /* required */
          "IsAvailable": ( "YES" | "NO" | "UNKNOWN" ) /* required */
        }, ... ],
        "AdImageModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string)
        }, /* nillable */
        "VideoExtension": {  /* VideoExtensionGetItem */
          "CreativeId": (long), /* required */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ),
          "ThumbnailUrl": (string), /* required */
          "PreviewUrl": (string) /* required */
        }, /* nillable */
        "ErirAdDescription" : (string), /* nillable */
        "AutogeneratedErirAdDescription" : (string) /* nillable */
      },
      "TextImageAd": {  /* TextImageAdGet */
        "AdImageHash": (string),
        "Href": (string), /* nillable */
        "TurboPageId": (long), /* nillable */
        "TurboPageModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string)
        }, /* nillable */
        "ErirAdDescription" : (string), /* nillable */
        "AutogeneratedErirAdDescription" : (string) /* nillable */
      },
      "MobileAppImageAd": {  /* MobileAppImageAdGet */
        "AdImageHash": (string),
        "TrackingUrl": (string), /* nillable */
        "ErirAdDescription" : (string), /* nillable */
        "AutogeneratedErirAdDescription" : (string) /* nillable */
      },
      "TextAdBuilderAd": {  /* TextAdBuilderAdGet */
        "Creative": { /* AdBuilderAdGetItem */
          "CreativeId": (long), /* required */
          "ThumbnailUrl": (string),
          "PreviewUrl": (string),
          "ErirAdDescription" : (string), /* nillable */
          "AutogeneratedErirAdDescription" : (string) /* nillable */
        },
        "Href": (string), /* nillable */
        "TurboPageId": (long), /* nillable */
        "TurboPageModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string)
        }, /* nillable */
        "ErirAdDescription" : (string), /* nillable */
        "AutogeneratedErirAdDescription" : (string) /* nillable */
      },
      "MobileAppAdBuilderAd": {  /* MobileAppAdBuilderAdGet */
        "Creative": { /* AdBuilderAdGetItem */
          "CreativeId": (long), /* required */
          "ThumbnailUrl": (string),
          "PreviewUrl": (string)
        },
        "TrackingUrl": (string), /* nillable */
        "ErirAdDescription" : (string), /* nillable */
        "AutogeneratedErirAdDescription" : (string) /* nillable */
      },
      "MobileAppCpcVideoAdBuilderAd" : {  /* MobileAppCpcVideoAdBuilderAdGet */
        "Creative" : { /* AdBuilderAdGetItem */
          "CreativeId" : (long) /* required */,
          "ThumbnailUrl" : (string),
          "PreviewUrl" : (string)
        },
        "TrackingUrl" : (string), /* nillable */
        "ErirAdDescription" : (string), /* nillable */
        "AutogeneratedErirAdDescription" : (string) /* nillable */
      },
      "CpmBannerAdBuilderAd": {  /* CpmBannerAdBuilderAdGet */
        "Creative": { /* AdBuilderAdGetItem */
          "CreativeId": (long), /* required */
          "ThumbnailUrl": (string),
          "PreviewUrl": (string)
        },
        "Href": (string), /* nillable */
        "TrackingPixels": { /* TrackingPixelGetArray */
          "Items": [{ /* TrackingPixelGetItem */
            "TrackingPixel": (string), /* required */
            "Provider": (string) /* required */
          }, ... ] /* required */
        }, /* nillable */
        "TurboPageId": (long), /* nillable */
        "TurboPageModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string)
        }, /* nillable */
        "ErirAdDescription" : (string), /* nillable */
        "AutogeneratedErirAdDescription" : (string) /* nillable */
      },
      "CpcVideoAdBuilderAd": {  /* CpcVideoAdBuilderAdGet */
        "Creative": { /* AdBuilderAdGetItem */
          "CreativeId": (long), /* required */
          "ThumbnailUrl": (string),
          "PreviewUrl": (string)
        },
        "Href": (string), /* nillable */
        "TurboPageId": (long), /* nillable */
        "TurboPageModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string)
        }, /* nillable */
        "ErirAdDescription" : (string), /* nillable */
        "AutogeneratedErirAdDescription" : (string) /* nillable */
      },
      "CpmVideoAdBuilderAd": {  /* CpmVideoAdBuilderAdGet */
        "Creative": { /* AdBuilderAdGetItem */
          "CreativeId": (long), /* required */
          "ThumbnailUrl": (string),
          "PreviewUrl": (string)
        },
        "Href": (string), /* nillable */
        "TrackingPixels": { /* TrackingPixelGetArray */
          "Items": [{ /* TrackingPixelGetItem */
            "TrackingPixel": (string), /* required */
            "Provider": (string) /* required */
          }, ... ] /* required */
        }, /* nillable */
        "TurboPageId": (long), /* nillable */
        "TurboPageModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string)
        }, /* nillable */
        "ErirAdDescription" : (string), /* nillable */
        "AutogeneratedErirAdDescription" : (string) /* nillable */
      },
      "SmartAdBuilderAd": {  /* SmartAdBuilderAdGet */
        "Creative": { /* AdBuilderAdGetItem */
          "CreativeId": (long), /* required */
          "ThumbnailUrl": (string),
          "PreviewUrl" : (string)
        },
        "ErirAdDescription" : (string), /* nillable */
        "AutogeneratedErirAdDescription" : (string) /* nillable */
      },
      "ShoppingAd" : {
        "SitelinkSetId" : (long) /* nillable */,
        "SitelinksModeration" : { /* nillable */
            "Status" : ("ACCEPTED"|"DRAFT"|"MODERATION"|"PREACCEPTED"|"REJECTED"|"UNKNOWN") /* required */,
            "StatusClarification" : (string)
        },
        "AdExtensions" : [{
            "AdExtensionId" : (long) /* required */,
            "Type" : ("CALLOUT"|"UNKNOWN") /* required */
        }, ... ],
        "BusinessId" : (long) /* nillable */,
        "FeedId" : (long),
        "FeedFilterConditions" : { /* nillable */
            "Items" : [{ /* required */
                "Operand" : (string) /* required */,
                "Operator" : ("CONTAINS_ANY"|"EQUALS_ANY"|"EXISTS"|"GREATER_THAN"|"IN_RANGE"|"LESS_THAN"|"NOT_CONTAINS_ALL") /* required */,
                "Arguments" : [ (string) ] /* required */
            }, ... ]
        },
        "FeedProcessingStatus" : ("EMPTY_RESULT"|"PROCESSED"|"UNKNOWN"|"UNPROCESSED"),
        "TitleSources" : { /* nillable */
            "Items" : [ (string) ] /* required */
        },
        "TextSources" : { /* nillable */
            "Items" : [ (string) ] /* required */
        },
        "DefaultTexts" : [ (string) ]
      },
      "ListingAd" : {
        "SitelinkSetId" : (long) /* nillable */,
        "SitelinksModeration" : { /* nillable */
            "Status" : ("ACCEPTED"|"DRAFT"|"MODERATION"|"PREACCEPTED"|"REJECTED"|"UNKNOWN") /* required */,
            "StatusClarification" : (string)
        },
        "AdExtensions" : [{
            "AdExtensionId" : (long) /* required */,
            "Type" : ("CALLOUT"|"UNKNOWN") /* required */
        }, ... ],
        "BusinessId" : (long) /* nillable */,
        "FeedId" : (long),
        "FeedFilterConditions" : { /* nillable */
            "Items" : [{ /* required */
                "Operand" : (string) /* required */,
                "Operator" : ("CONTAINS_ANY"|"EQUALS_ANY"|"EXISTS"|"GREATER_THAN"|"IN_RANGE"|"LESS_THAN"|"NOT_CONTAINS_ALL") /* required */,
                "Arguments" : [ (string) ] /* required */
            }, ... ]
        },
        "FeedProcessingStatus" : ("EMPTY_RESULT"|"PROCESSED"|"UNKNOWN"|"UNPROCESSED"),
        "TitleSources" : { /* nillable */
            "Items" : [ (string) ] /* required */
        },
        "TextSources" : { /* nillable */
            "Items" : [ (string) ] /* required */
        },
        "DefaultTexts" : [ (string) ]
      }
    }, ... ],
    }, ... ],
    "LimitedBy": (long)
  }
}

Parameters are described below.

Parameter

Type

Description

result structure (for JSON) / GetResponse (for SOAP)

Ads

array of AdGetItem

Ads.

LimitedBy

long

Sequential number of the last object returned. It is included if there was a limit on the number of objects in the response. See the section Paginated data selection.

AdGetItem structure

Id

long

The ad ID.

CampaignId

long

ID of the campaign that the ad belongs to.

AdGroupId

long

ID of the group that the ad belongs to.

Status

StatusEnum

Status of the ad. For a description of the statuses, see the section Status and state of an ad.

State

StateEnum

State of the ad. For a description of the states, see the section Status and state of an ad.

StatusClarification

string

Text explanation of the status and/or reasons for rejection after review.

AdCategories

ArrayOfString, nillable

Special category.

AgeLabel

AgeLabelEnum, nillable

Age label.

Type

AdTypeEnum

Type of ad. See Ad type.

Subtype

AdSubtypeEnum

The ad subtype. For ads with a type other than IMAGE_AD or CPC_VIDEO_AD (in "Ads for mobile apps" campaigns), the value NONE is returned.

TextAd

TextAdGet

Parameters of a text and image ad.

DynamicTextAd

DynamicTextAdGet

Parameters of a dynamic ad.

MobileAppAd

MobileAppAdGet

Parameters of a mobile app ad.

TextImageAd

TextImageAdGet

Parameters of an image ad that was created from an image (in a group of Text & Image ads).

MobileAppImageAd

MobileAppImageAdGet

Parameters of an image ad that was created from an image (in a group of mobile app ads).

TextAdBuilderAd

TextAdBuilderAdGet

Parameters of an image ad that was created from a creative (in a group of Text & Image ads).

MobileAppAdBuilderAd

MobileAppAdBuilderAdGet

Parameters of an image ad that was created from a creative (in a group of mobile app ads).

MobileAppCpcVideoAdBuilderAd

MobileAppCpcVideoAdBuilderAdGet

Parameters of a video ad that was created from a creative (in a group of ads for mobile apps).

CpmBannerAdBuilderAd

CpmBannerAdBuilderAdGet

Parameters of a display banner.

CpcVideoAdBuilderAd

CpcVideoAdBuilderAdGet

Parameters of a display video ad in a “Text & Image ads” campaign.

CpmVideoAdBuilderAd

CpmVideoAdBuilderAdGet

Parameters of a display video ad in a display campaign.

SmartAdBuilderAd

SmartAdBuilderAdGet

Smart banner parameters.

ShoppingAd

ShoppingAdGet

Product ad parameters.

ListingAd

ListingAdGet

Parameters of an ad for catalog pages.

TextAdGet structure

Title

string

Title 1.

Maximum of 56 characters, counting "narrow" characters. Maximum of 22 characters per word. When using a template, the # character doesn't count towards the length.

Note

"Narrow" characters are: !,.;:".

Title2

string, nillable

Title 2.

A maximum of 30 characters not counting “narrow” characters, plus up to 15 “narrow” characters. Maximum of 22 characters per word. When using a template, the # character doesn't count towards the length.

Note

"Narrow" characters are: !,.;:"

Text

string

Ad text.

Maximum of 81 characters not counting "narrow" characters, plus up to 15 "narrow" characters. Maximum of 23 characters per word. When using a template, the # character doesn't count towards the length.

Note

"Narrow" characters are: !,.;:"

Href

string, nillable

Link to the advertiser's website. Maximum of 1024 characters. When using a template, the # character doesn't count towards the length.

It must include the protocol and domain name. May contain substitution variables.

Mobile

YesNoEnum

Indicates whether this is a mobile ad: YES or NO. See Mobile ads in Yandex Direct Help.

DisplayDomain

string, nillable

Domain being advertised. Detected automatically from the ad link.

DisplayUrlPath

string, nillable

Display link. Allowed only with the Href parameter. Maximum of 20 characters. When using a template, the # character doesn't count towards the length.

It may contain letters, numbers, and the symbols -, №, /, %, #. Spaces, underscores (_), and double characters -- and // are not allowed.

See Display link in the Yandex Direct Help.

VCardId

long, nillable

ID of the vCard. The vCard must belong to the same campaign as the ad.

SitelinkSetId

long, nillable

ID of a set of sitelinks. Allowed only with the Href or TurboPageId parameter.

AdImageHash

string, nillable

Hash of the image.

For Text & Image ads, only images of the REGULAR or WIDE type are acceptable. See Type of image.

DisplayUrlPathModeration

ExtensionModeration, nillable

Result of reviewing the display link.

VCardModeration

ExtensionModeration, nillable

Result of vCard review.

SitelinksModeration

ExtensionModeration, nillable

Result of reviewing the set of sitelinks.

AdImageModeration

ExtensionModeration, nillable

Result of image review.

AdExtensions

array of AdExtensionAdGetItem

Extensions.

VideoExtension

VideoExtensionGetItem, nillable

Video extension.

See Video extensions in the Yandex Direct Help.

PriceExtension

PriceExtensionGetItem, nillable

Price in the ad.

TurboPageId

long, nillable

ID of the Turbo page.

TurboPageModeration

ExtensionModeration, nillable

Result of Turbo page moderation.

BusinessId

long, nillable

ID of the business profile on Yandex.

Note

The business profile is available at https://yandex.ru/profile/<profile_id>

PreferVCardOverBusiness

YesNoEnum

Indicates which data source takes priority when displaying an ad: YES — vCard, NO — business profile.

Alert

This parameter is used if the VCardID and BusinessId values are specified. If one of these values is deleted, you must set the PreferVCardOverBusiness parameter to NO.

ErirAdDescription

string

Ad object description.

AutogeneratedErirAdDescription

string

Automatically generated description of an ad object.

ExtensionModeration structure

Status

StatusEnum

Result of reviewing the association between an ad and an add-on. For a description of the statuses, see the section Ad extensions.

StatusClarification

string

Text explanation of the status and/or reasons for rejection after review.

AdExtensionAdGetItem structure

AdExtensionId

long

Extension ID.

Type

AdExtensionTypeEnum

Extension type. Only one type of extension is available at this time — the Callout (CALLOUT).

VideoExtensionGetItem structure

CreativeId

long

ID of the creative.

Status

StatusEnum

Result of reviewing the video extension assignment to the ad. For a description of the statuses, see the section Ad extensions.

ThumbnailUrl

string

URL for the preview image.

PreviewUrl

string

URL for the preview video.

PriceExtensionGetItem structure

Price

long

The price of a product or service multiplied by 1,000,000. An integer that is a multiple of 10,000 (the price with two digits after the decimal point). Maximum value: 10,000,000,000,000,000.

OldPrice

long, nillable

The previous price of a product or service multiplied by 1,000,000. An integer that is a multiple of 10,000. The old price must be higher than the current price.

PriceQualifier

PriceQualifierEnum

Text explanation of the price:

  • FROM — "From".
  • UP_TO — "To".
  • NONE — No explanation.

PriceCurrency

PriceCurrencyEnum

The currency that the price is shown in.

DynamicTextAdGet structure

VCardId

long, nillable

ID of the vCard. The vCard must belong to the same campaign as the ad.

AdImageHash

string, nillable

Hash of the image.

For dynamic ads, only images of the REGULAR or WIDE type are acceptable. See Type of image.

SitelinkSetId

long, nillable

ID of a set of sitelinks.

VCardModeration

ExtensionModeration, nillable

Result of vCard review.

SitelinksModeration

ExtensionModeration, nillable

Result of reviewing the set of sitelinks.

AdImageModeration

ExtensionModeration, nillable

Result of image review.

AdExtensions

array of AdExtensionAdGetItem

Extensions.

Text

string

Ad text.

Maximum of 81 characters not counting "narrow" characters, plus up to 15 "narrow" characters. Maximum of 23 characters per word. When using a template, the # character doesn't count towards the length.

Note

"Narrow" characters are: !,.;:"

MobileAppAdGet structure

Title

string

Title.

Maximum of 56 characters, counting "narrow" characters. Maximum of 22 characters per word. When using a template, the # character doesn't count towards the length.

Text

string

Ad text.

Maximum of 75 characters, counting "narrow" characters. Maximum of 23 characters per word. When using a template, the # character doesn't count towards the length.

TrackingUrl

string, nillable

Tracking link for tracking app installations.

Action

MobileAppAdActionEnum

The button label:

  • DOWNLOAD — "Download"

  • GET — "Get"

  • INSTALL — "Install"

  • MORE — "More"

  • OPEN — "Open"

  • UPDATE — "Update"

  • PLAY — "Play"

  • BUY_AUTODETECT — The text changes based on the app's price: "Buy" if the price is non-zero, or "Free" if the price is set to zero.

AdImageHash

string, nillable

Hash of the image.

For mobile app ads, only images of the WIDE type are acceptable. See Type of image.

Features

array of MobileAppAdFeatureGetItem

Add-ons that need to be automatically downloaded from the app store and displayed in the ad.

AdImageModeration

ExtensionModeration, nillable

Result of image review.

VideoExtension

VideoExtensionGetItem, nillable

Video extension.

See Video extensions in the Yandex Direct Help.

ErirAdDescription

string

Ad object description.

AutogeneratedErirAdDescription

string

Automatically generated description of an ad object.

MobileAppAdFeatureGetItem structure

Feature

MobileAppFeatureEnum

Type of extension:

  • PRICE — price
  • ICON — icon
  • CUSTOMER_RATING — rating
  • RATINGS — number of ratings (shown only if the rating is displayed)

Note

Returns data about add-ons that were specified when creating or editing the ad, as well as add-ons that were downloaded from the app store.

Enabled

YesNoEnum

Whether to display an add-on in the ad.

Note

  • If the add-on couldn't be downloaded from the app store, the YES value is available, but this add-on is not shown when displaying the ad.
  • The number of ratings is only shown together with the average rating: if NO is set for the CUSTOMER_RATING type, but YES is set for RATINGS, the number of ratings is not displayed.

IsAvailable

YesNoUnknownEnum

Whether the add-on was successfully downloaded from the app store:

  • YES — Add-on was downloaded.
  • NO — Add-on couldn't be downloaded.
  • UNKNOWN — Downloading the add-on hasn't been attempted yet.

TextImageAdGet structure

AdImageHash

string

Hash of the image.

For image ads, only images of the FIXED_IMAGE type are acceptable. See Type of image.

Href

string, nillable

Link to the advertiser's website. Maximum of 1024 characters. When using a template, the # character doesn't count towards the length.

It must include the protocol and domain name. May contain substitution variables.

TurboPageId

long, nillable

ID of the Turbo page.

TurboPageModeration

ExtensionModeration, nillable

Result of Turbo page moderation.

ErirAdDescription

string

Ad object description.

AutogeneratedErirAdDescription

string

Automatically generated description of an ad object.

MobileAppImageAdGet structure

AdImageHash

string

Hash of the image.

For image ads, only images of the FIXED_IMAGE type are acceptable. See Type of image.

TrackingUrl

string, nillable

Tracking link for tracking app installations.

ErirAdDescription

string

Ad object description.

AutogeneratedErirAdDescription

string

Automatically generated description of an ad object.

TextAdBuilderAdGet structure

Creative

AdBuilderAdGetItem

A creative that was created in the Ad Builder.

See Creative Ad Builder for image ads in the Yandex Direct Help.

Href

string, nillable

Link to the advertiser's website. Maximum of 1024 characters. When using a template, the # character doesn't count towards the length.

It must include the protocol and domain name. May contain substitution variables.

TurboPageId

long, nillable

ID of the Turbo page.

TurboPageModeration

ExtensionModeration, nillable

Result of Turbo page moderation.

ErirAdDescription

string

Ad object description.

AutogeneratedErirAdDescription

string

Automatically generated description of an ad object.

MobileAppAdBuilderAdGet structure

Creative

AdBuilderAdGetItem

A creative that was created in the Ad Builder.

See Creative Ad Builder for image ads in the Yandex Direct Help.

TrackingUrl

string, nillable

Tracking link for tracking app installations.

ErirAdDescription

string

Ad object description.

AutogeneratedErirAdDescription

string

Automatically generated description of an ad object.

MobileAppCpcVideoAdBuilderAdGet structure

Creative

AdBuilderAdGetItem

A creative that was created in the Ad Builder.

See Creative Ad Builder for video extensions in Yandex Direct Help.

TrackingUrl

string, nillable

Tracking link for tracking app installations.

ErirAdDescription

string

Ad object description.

AutogeneratedErirAdDescription

string

Automatically generated description of an ad object.

CpmBannerAdBuilderAdGet structure

Creative

AdBuilderAdGetItem

A creative that was uploaded in the web interface or created in the Ad Builder.

See Creating a display campaign in the Yandex Direct Help.

Href

string, nillable

Link to the advertiser's website. Maximum of 1024 characters. When using a template, the # character doesn't count towards the length.

It must include the protocol and domain name. May contain substitution variables.

TrackingPixels

TrackingPixelGetArray, nillable

A Yandex Audience pixel and/or an ADFOX impression tag.

TurboPageId

long, nillable

ID of the Turbo page.

TurboPageModeration

ExtensionModeration, nillable

Result of Turbo page moderation.

ErirAdDescription

string

Ad object description.

AutogeneratedErirAdDescription

string

Automatically generated description of an ad object.

CpcVideoAdBuilderAdGet structure

Creative

AdBuilderAdGetItem

A creative that was created in the Ad Builder.

See the section Video ads / Creative Ad Builder in the Help for Yandex Direct.

Href

string, nillable

Link to the advertiser's website. Maximum of 1024 characters. When using a template, the # character doesn't count towards the length.

It must include the protocol and domain name. May contain substitution variables.

TurboPageId

long, nillable

ID of the Turbo page.

TurboPageModeration

ExtensionModeration, nillable

Result of Turbo page moderation.

ErirAdDescription

string

Ad object description.

AutogeneratedErirAdDescription

string

Automatically generated description of an ad object.

CpmVideoAdBuilderAdGet structure

Creative

AdBuilderAdGetItem

A creative that was created in the Ad Builder.

See Video advertising / How to launch in Yandex Direct Help.

Href

string, nillable

Link to the advertiser's website. Maximum of 1024 characters. When using a template, the # character doesn't count towards the length.

It must include the protocol and domain name. May contain substitution variables.

TrackingPixels

TrackingPixelGetArray, nillable

An ADFOX tracking tag.

TurboPageId

long, nillable

ID of the Turbo page.

TurboPageModeration

ExtensionModeration, nillable

Result of Turbo page moderation.

ErirAdDescription

string

Ad object description.

AutogeneratedErirAdDescription

string

Automatically generated description of an ad object.

SmartAdBuilderAdGet structure

Creative

AdBuilderAdGetItem

A creative that was created in the Ad Builder.

See Creative Ad Builder for smart banners in the Help for Yandex Direct.

ErirAdDescription

string

Ad object description.

AutogeneratedErirAdDescription

string

Automatically generated description of an ad object.

AdBuilderAdGetItem structure

CreativeId

long

ID of the creative.

To get the ID of a creative, use the Creatives.get method.

ThumbnailUrl

string

URL for the preview thumbnail.

PreviewUrl

string

URL for the preview image.

TrackingPixelGetArray structure

Items

array of TrackingPixelGetItem

Pixel and/or tag and their providers.

TrackingPixelGetItem structure

TrackingPixel

string

Link to a Yandex Audience pixel or an ADFOX impression tag.

Provider

string

Provider of the pixel or impression tag.

ShoppingAdGet structure

SitelinkSetId

long

ID of a set of sitelinks.

AdExtensions

AdExtensions

Extensions.

BusinessId

long

ID of the business profile on Yandex.

To get data from business profiles, use the Businesses.get method.

A business profile can be linked to an ad only if the YES value is returned for the IsPublished parameter.

Note

The business profile is available at https://yandex.ru/profile/<profile_id>

FeedFilterConditions

FeedFilterConditionsItem

Rules for selecting product offers. No more than 30 filters in the array. The total length of the selection rules is a maximum of 65 KB (in JSON).
A product offer is selected for ad generation if it meets all the selection rules at the same time. If this parameter is omitted, all product offers from the feed are used for ad generation.

FeedProcessingStatus

FeedProcessingStatusEnum

Ad generation status for a feed. Possible values:

  • UNPROCESSED — Ad generation has not finished.
  • PROCESSED — Ads have been created.
  • EMPTY_RESULT — No ads could be created.

TitleSources

array of string

Names of feed fields used to generate ad titles. You can retrieve the acceptable field names through the TitleAndTextSources field of the feeds.get method.

TextSources

array of string

Names of feed fields used to generate ad texts. You can retrieve the acceptable field names through the TitleAndTextSources field of the feeds.get method.

DefaultTexts

array of string

Default texts.

ListingAdGet structure

SitelinkSetId

long

ID of a set of sitelinks.

AdExtensions

AdExtensions

Extensions.

BusinessId

long

ID of the business profile on Yandex.

To get data from business profiles, use the Businesses.get method.

A business profile can be linked to an ad only if the YES value is returned for the IsPublished parameter.

Note

The business profile is available at https://yandex.ru/profile/<profile_id>

FeedFilterConditions

FeedFilterConditionsItem

Rules for selecting product offers. No more than 30 filters in the array. The total length of the selection rules is a maximum of 65 KB (in JSON).

A product offer is selected for ad generation if it meets all the selection rules at the same time. If this parameter is omitted, all product offers from the feed are used for ad generation.

FeedProcessingStatus

FeedProcessingStatusEnum

Ad generation status for a feed. Possible values:

  • UNPROCESSED — Ad generation has not finished.
  • PROCESSED — Ads have been created.
  • EMPTY_RESULT — No ads could be created.

TitleSources

array of string

Names of feed fields used to generate ad titles. You can retrieve the acceptable field names through the TitleAndTextSources field of the feeds.get method.

TextSources

array of string

Names of feed fields used to generate ad texts. You can retrieve the acceptable field names through the TitleAndTextSources field of the feeds.get method.

DefaultTexts

array of string

Default texts.

AdExtensions structure

AdExtensionId

long

Extension ID.

Type

string

Extension type.

Possible values:

  • CALLOUT
  • UNKNOWN

FeedFilterConditionsItem structure

Operand

string

Feed parameter.

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

Operator

OperatorEnum

Comparison operator. For information on the compatibility of feed fields and operators, as well as restrictions on values, see Rules for selecting product ads.

Arguments

array of string

An array of strings to compare the operand to. Maximum of 10 strings in the array.
Previous
delete
Next
moderate