banner

Get a list of banners.

Request format

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: Get a list of campaigns/flights.
`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>
                <videoDuration>{float}</videoDuration>
            </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).
`videoDuration`	Video duration in seconds.

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.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>
                    <adLabel>0</adLabel>
                    <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>
                <videoDuration>10.0</videoDuration>
            </row0>
        </data>
    </result>
</response>

Other actions with the object

See more actions with the banner object:

Add a banner.
Delete a banner.
Edit a banner.
Get information about banner placement.
Edit banner placement.
Get statistics on campaigns/banners/placements for the day.
Target a banner by frequency.
Target a banner by geography.
Target a banner by keywords.
Target a banner by gender, age, or income.
Target a banner by user characteristics.
Target a banner by time.

Was the article helpful?

assistant

bannerKktu