banner

Get a list of banners.

Request format

Note

Pagination available.

Note

Access to the request for a user with the “website owner” type.

https://adfox.yandex.com/api/v1
  ? object=account
  & action=list
  & actionObject=banner
  & [actionObjectID=<integer>]
  & [listCampaignIDs=<integer>]
  & [show=<string>]
  & [search=<string>]

actionObjectID

To get data for only one banner, specify its ID.

Default value: 0 (display the list of all banners).

listCampaignIDs

Display the result for specified campaigns only. A comma-separated list of campaign IDs.

See also:

show

Configuring data completeness in the list of campaigns/flights:

Acceptable values:

  • advanced (full display format).

  • common (brief display format):

    • ID.

    • name.

  • short (limited display format):

    • ID.

    • bannerTypeID.

    • templateID.

    • campaignID.

    • status.

    • dateStart.

    • dateEnd.

Default value: advanced.

search

Filtering by substring in a campaign/flight name.

An entry can contain Russian and Latin letters, numbers, and any special characters.

* Required

Response format

<response>
<status>
  <code>{integer}</code>
</status>
<result>
<data>
  <row0>
    <ID>{integer}</ID>
    <name>{string}</name>
    <campaignID>{integer}</campaignID>
    <campaignName>{string}</campaignName>
    <campaignDateStart>{date}</campaignDateStart>
    <campaignDateEnd>{date}</campaignDateEnd>
    <bannerTypeID>{integer}</bannerTypeID>
    <bannerTypeName>{string}</bannerTypeName>
    <status>{integer}</status>
    <isUnplaced>{integer}</isUnplaced>
    <priority>{integer}</priority>
    <impressions>{integer}</impressions>
    <impressionsToday>{integer}</impressionsToday>
    <impressionsHour>{integer}</impressionsHour>
    <clicks>{integer}</clicks>
    <clicksToday>{integer}</clicksToday>
    <clicksHour>{integer}</clicksHour>
    <targetingProfileID>{integer}</targetingProfileID>
    <targetingProfileName>{string}</targetingProfileName>
    <isEvents>{integer}</isEvents>
    <templateID>{integer}</templateID>
    <templateName>{string}</templateName>
    <imageURL>{string}</imageURL>
    <hitURL>{string}</hitURL>
    <target>{string}</target>
    <alt>{string}</alt>
    <isParameter1Required>{integer}</isParameter1Required>
    <parameter1Name>{string}</parameter1Name>
    <parameter1Type>{string}</parameter1Type>
    <parameter1Length>{integer}</parameter1Length>
    <parameter1Default>{string}</parameter1Default>
    <parameter1>{integer}</parameter1>
    <isParameter2Required>{integer}</isParameter2Required>
    <parameter2Name>{string}</parameter2Name>
    <parameter2Type>string</parameter2Type>
    <parameter2Length>{integer}</parameter2Length>
    <parameter2Default>{string}</parameter2Default>
    <parameter2>{integer}</parameter2>
    <impressionCode>{html}</impressionCode>
    <maxImpressions>{integer}</maxImpressions>
    <maxImpressionsPerDay>{integer}</maxImpressionsPerDay>
    <maxImpressionsPerHour>{integer}</maxImpressionsPerHour>
    <maxClicks>{integer}</maxClicks>
    <maxClicksPerDay>{integer}</maxClicksPerDay>
    <maxClicksPerHour>{integer}</maxClicksPerHour>
    <dateStart>{date}</dateStart>
    <dateEnd>{date}</dateEnd>
    <dateAdded>{date}</dateAdded>
      <sendToErir>{integer}</sendToErir>
        <markingSettings>
          <adLabel>{integer}</adLabel>
          <domain>{string}</domain>
          <showMenu>{integer}</showMenu>
        </markingSettings>
        <markingInfo>
        <token>{string}</token>
        <description>{string}</description>
        <contentType>{integer}</contentType>
        <targetURL>{string}</targetURL>
        <okveds>
          <row0>{string}</row0>
        </okveds>
        <creatives>
          <row0>
            <textData>{string}</textData>
            <mediaData>{string}</mediaData>
            <mediaDataDescription>{string}</mediaDataDescription>
            <fromTemplate>{integer}</fromTemplate>
          </row0>
        </creatives>
        </markingInfo>
  </row0>
</data>
</result>
</response>

Response parameters

code

Request processing status. If the value is 0, the request was completed successfully. For the key, see Error handling.

rows

Number of items in the response tree.

rowN

Item number in the response tree, where N is a number from 0 to rows-1 (where rows is the total number of items in the response).

ID

Unique banner ID.

name

Banner name.

campaignID

ID of the campaign the banner belongs to.

campaignName

Name of the campaign the banner belongs to.

campaignDateStart

Campaign start date.

campaignDateEnd

Campaign end date.

bannerTypeID

ID of the banner type used to create the banner.

bannerTypeName

Name of the banner type used to create the banner.

status

Status.

Acceptable values:

  • 0: Active.
  • 1: Paused.
  • 2: Completed.

isUnplaced

Disabled on new placements (additional module).

priority

Priority of the banner relative to other banners in this campaign.

impressions

Tag information. Total number of impressions.

impressionsToday

Tag information. Number of impressions today.

impressionsHour

Tag information. Number of impressions in the current hour.

clicks

Tag information. Total number of clicks.

clicksToday

Tag information. Number of clicks today.

clicksHour

Tag information. Number of clicks in the current hour.

targetingProfileID

Targeting profile ID.

targetingProfileName

Targeting profile names.

isEvents

Getting links to events is enabled.

templateID

Banner template ID.

templateName

Banner template name.

imageURL

Link to the banner image or a flash banner placeholder.

hitURL

Link to the advertiser's website. Shown only for placements with the 1x1 banner type.

target

Determines the window where the link opens.

alt

Alternative text for the image.

isParameterNRequired

Required/optional additional parameter (user variable), where N is the parameter number from 1 to 25.

parameterNName

Name of the additional parameter, where N is the parameter number from 1 to 25.

parameterNType

Data type of the additional parameter, where N is the parameter number from 1 to 25.

parameterNLength

Maximum length of the additional parameter value, where N is the parameter number from 1 to 25.

parameterNDefault

Default value for the additional parameter, where N is the parameter number from 1 to 25.

impressionCode

The HTML code of the banner.

maxImpressions

Maximum number of impressions.

maxImpressionsPerDay

Maximum number of impressions per day.

maxImpressionsPerHour

Maximum number of impressions per hour.

maxClicks

Maximum total number of clicks.

maxClicksPerDay

Maximum number of clicks per day.

maxClicksPerHour

Maximum number of clicks per hour.

dateStart

Delivery start date.

dateEnd

Delivery end date.

dateAdded

Add date.

sendToErir

Submit data to the Russian state register.

Acceptable values:

  • 0: Don't submit data to the Russian state register.
  • 1: Submit data to the Russian state register (ad register is enabled).

markingSettings

Setting up the banner menu and the “Ad” label.

markingSettings.adLabel

Show the “Ad” or the “Social Ad” label on the banner.

Acceptable values:

  • 0: The “Ad” label is disabled.
  • 1: Show the “Ad” label.
  • 2: Show the “Social Ad” label.

markingSettings.domain

Domain next to the “Ad” label.

markingSettings.showMenu

Show the menu on the banner.

Acceptable values:

  • 0: Don't show the menu.
  • 1: Show the menu.

markingInfo

Information about a creative.

markingInfo.token

Banner token.

markignInfo.description

Description of a creative.

markingInfo.contentType

Creative type.

Acceptable values:

  • 0: Other.
  • 1: Banner.
  • 2: Text and image unit.
  • 3: Text unit.
  • 4: Video.
  • 5: Live video.
  • 6: Live audio.
  • 7: Audio.

markingInfo.targetUrl

Target URL.

markingInfo.okveds.rowN

List of OKVED codes of advertised products.

markingInfo.creatives.rowN.textData

Array with text data of creatives.

markingInfo.creatives.rowN.mediaData

Array with media data of creatives.

markingInfo.creatives.rowN.mediaDataDescription

Description of a creative.

markingInfo.creatives.rowN.fromTemplate

Creatives are filled in automatically using the banner parameters (if the option is enabled for the template).

Sample request and response

Request:

https://adfox.yandex.com/api/v1?object=account&action=list&actionObject=banner

Response:

<response>
<status>
  <code>0</code>
</status>
<result>
<data>
  <row0>
    <ID>940132</ID>
    <name>example</name>
    <campaignID>321516</campaignID>
    <campaignName>test campaign</campaignName>
    <campaignDateStart>2020-11-27 00:00:00</campaignDateStart>
    <campaignDateEnd/>
    <bannerTypeID>24</bannerTypeID>
    <bannerTypeName>Stretching banner 100</bannerTypeName>
    <status>2</status>
    <isUnplaced>0</isUnplaced>
    <priority>100</priority>
    <impressions>184</impressions>
    <impressionsToday>0</impressionsToday>
    <impressionsHour>0</impressionsHour>
    <clicks>0</clicks>
    <clicksToday>0</clicksToday>
    <clicksHour>0</clicksHour>
    <targetingProfileID>306331</targetingProfileID>
    <targetingProfileName/>
    <isEvents>0</isEvents>
    <templateID>16602</templateID>
    <templateName>Image [Sync_Async]</templateName>
    <imageURL>http://banners.adfox.ru/000000/adfox/0000000/940132.jpg</imageURL>
    <hitURL>http://www.yandex.ru/</hitURL>
    <target>_blank</target>
    <alt/>
    <isParameter1Required>1</isParameter1Required>
    <parameter1Name>Image width</parameter1Name>
    <parameter1Type>string</parameter1Type>
    <parameter1Length>0</parameter1Length>
    <parameter1Default/>
    <parameter1>120</parameter1>
    <isParameter2Required>1</isParameter2Required>
    <parameter2Name>Image height</parameter2Name>
    <parameter2Type>string</parameter2Type>
    <parameter2Length>0</parameter2Length>
    <parameter2Default/>
    <parameter2>120</parameter2>
    <impressionCode>
      <img src="http://banners.adfox.ru/0000000/adfox/000000/940132.jpg" width="120" height="120" alt="" border=0 />
    </impressionCode>
    <maxImpressions>0</maxImpressions>
    <maxImpressionsPerDay>0</maxImpressionsPerDay>
    <maxImpressionsPerHour>0</maxImpressionsPerHour>
    <maxClicks>0</maxClicks>
    <maxClicksPerDay>0</maxClicksPerDay>
    <maxClicksPerHour>0</maxClicksPerHour>
    <dateStart>2021-02-05 00:00:00</dateStart>
    <dateEnd/>
    <dateAdded>2021-02-05 18:28:35</dateAdded>
    <sendToErir>1</sendToErir>
      <markingSettings>
      <showLabel>0</showLabel>
      <domain></domain>
      <showMenu>1</showMenu>
      </markingSettings>
      <markingInfo>
      <token>4CQwVszH9pQMNLzJn7q</token>
      <description>test</description>
      <contentType>1</contentType>
      <targetURL></targetURL>
      <okveds>
        <row0>123</row0>
      </okveds>
      <creatives>
        <row0>
          <textData>test</textData>
          <mediaData></mediaData>
          <mediaDataDescription></mediaDataDescription>
          <fromTemplate>0</fromTemplate>
        </row0>
       </creatives>
       </markingInfo>
  </row0>
</data>
</result>
</response>

<response>
<status>
  <code>0</code>
</status>
<result>
<data>
  <row0>
    <ID>940132</ID>
    <name>example</name>
    <campaignID>321516</campaignID>
    <campaignName>test campaign</campaignName>
    <campaignDateStart>2020-11-27 00:00:00</campaignDateStart>
    <campaignDateEnd/>
    <bannerTypeID>24</bannerTypeID>
    <bannerTypeName>Stretching banner 100%</bannerTypeName>
    <status>2</status>
    <isUnplaced>0</isUnplaced>
    <priority>100</priority>
    <impressions>184</impressions>
    <impressionsToday>0</impressionsToday>
    <impressionsHour>0</impressionsHour>
    <clicks>0</clicks>
    <clicksToday>0</clicksToday>
    <clicksHour>0</clicksHour>
    <targetingProfileID>306331</targetingProfileID>
    <targetingProfileName/>
    <isEvents>0</isEvents>
    <templateID>16602</templateID>
    <templateName>Image [Sync_Async]</templateName>
    <imageURL>
      http://banners.adfox.com/000000/adfox/0000000/940132.jpg
    </imageURL>
    <hitURL>http://www.yandex.com/</hitURL>
    <target>_blank</target>
    <alt/>
    <isParameter1Required>1</isParameter1Required>
    <parameter1Name>Image width</parameter1Name>
    <parameter1Type>string</parameter1Type>
    <parameter1Length>0</parameter1Length>
    <parameter1Default/>
    <parameter1>120</parameter1>
    <isParameter2Required>1</isParameter2Required>
    <parameter2Name>Image height</parameter2Name>
    <parameter2Type>string</parameter2Type>
    <parameter2Length>0</parameter2Length>
    <parameter2Default/>
    <parameter2>120</parameter2>
    <impressionCode>
      <img src="http://banners.adfox.com/0000000/adfox/000000/940132.jpg" width="120" height="120" alt="" border=0>
    </impressionCode>
    <maxImpressions>0</maxImpressions>
    <maxImpressionsPerDay>0</maxImpressionsPerDay>
    <maxImpressionsPerHour>0</maxImpressionsPerHour>
    <maxClicks>0</maxClicks>
    <maxClicksPerDay>0</maxClicksPerDay>
    <maxClicksPerHour>0</maxClicksPerHour>
    <dateStart>2021-02-05 00:00:00</dateStart>
    <dateEnd/>
    <dateAdded>2021-02-05 18:28:35</dateAdded>
    <sendToErir>1</sendToErir>
      <markingSettings>
      <showLabel>0</showLabel>
      <domain></domain>
      <showMenu>1</showMenu>
      </markingSettings>
      <markingInfo>
      <token>4CQwVszH9pQMNLzJn7q</token>
      <description>test</description>
      <contentType>1</contentType>
      <targetURL></targetURL>
      <okveds>
        <row0>123</row0>
      </okveds>
      <creatives>
        <row0>
          <textData>test</textData>
          <mediaData></mediaData>
          <mediaDataDescription></mediaDataDescription>
          <fromTemplate>0</fromTemplate>
        </row0>
       </creatives>
       </markingInfo>
  </row0>
</data>
</result>
</response>

Other actions with the object

See more actions with the banner object:

Previous
assistant
Next
bannerPlacements
In this article: