customisable counter
API: Zones / API / Knowledge Base - Trafficspaces Support

or Create a profile

Home → Knowledge Base → API →

API: Zones

A Zone resource represents a spot in which ads can be displayed. It describes the physical and behavioural attributes of the spot, and specifies how it is priced.

Zones can configured to display various forms of ad such images, text, flash, video and audio. They can also be priced on a CPM, CPC or Pay-Per-Day (Tenancy) basis.

Each Zone has a unique handle and an ad tag which can be used to fetch ads that are running on it. Where ads are not available, the Zone can be configured to load a default ad or choose from several ad networks.

Supported Methods

URI GET POST PUT DELETE
/resources/zones/ List Create - -
/resources/zones/<zone_id>.<format> Read - Update Delete
/resources/zones/statistics/<zone_id>.<format> List - - -

List ad zones


  • URL - http://<subdomain>.trafficspaces.com/resources/zones/
  • Method - GET
  • Parameters -
    • channel - (string, optional) the channel code filter.
    • geographic - (string, optional) the geographic code that's used to filter and sort the results. Ad zones with more traffic from the specified location appear first. For the full list of geographic codes, download the geographic configuration from your ad store.
    • page - (unsigned, optional) an integer value that specifies which page of results to fetch, starting at 1. Default: 1. Minimum: 1.
    • pagesize - (unsigned, optional) how many results to fetch in each request. Default: 25. Maximum: 100
  • Response
    • Status - 200, if successful.
    • Body - A collection of up to pagesize ad zones in the requested format

Read an ad zone


  • URL - http://<subdomain>.trafficspaces.com/resources/zones/<zone_id>.<format>
  • Method - GET
  • Parameters - None
  • Response
    • Status - 200, if successful.
    • Body - The requested ad zone in the requested format

List ad zone stats


  • URL - http://<subdomain>.trafficspaces.com/resources/zones/statistics/<zone_id>.<format>
  • Method - GET
  • Parameters -
    • fromdate - (date, optional) the date from which the stats are fetched
    • todate - (date, optional) the date to which the stats are fetched.
    • page - (unsigned, optional) an integer value that specifies which page of results to fetch, starting at 1. Default: 1. Minimum: 1.
    • pagesize - (unsigned, optional) how many results to fetch in each request. Default: 25. Maximum: 100
      Note: If the fromdate and todate parameters are not specified, the latest stats will be fetched instead.
  • Response
    • Status - 200, if successful.
    • Body - A collection of up to pagesize ad zone statistics in the requested format.

Create a new ad zone


  • URL - http://<subdomain>.trafficspaces.com/resources/zones/
  • Method - POST
  • Parameters - XML or JSON data. See the Attributes below
  • Response
    • Status - 201, if successful.
    • Body - The created ad zone in the requested format.
    • Headers
      • Location - A relative URL for the newly created ad zone

Update an existing ad zone


  • URL - http://<subdomain>.trafficspaces.com/resources/zones/<zone_id>.<format>
  • Method - PUT
  • Parameters - XML or JSON data. See the Attributes below
  • Response
    • Status - 200, if successful.
    • Body - The updated ad zone in the requested format

Delete an existing ad zone


  • URL - http://<subdomain>.trafficspaces.com/resources/zones/<zone_id>.<format>
  • Method - DELETE
  • Parameters - None
  • Response
    • Status - 200, if successful.

Attributes

  • zone - (object, rwa)
    • id - (string, r) the alphanumeric unique identifier
    • handle - (string, r) the unique handle that is used to fetch ads for the ad zone
    • name - (string, rwa) the display name in the ad store.
    • width - (unsigned, rw) the display width of the ad zone
    • height - (unsigned, rw) the display height of the ad zone
    • formats - (string, rwa) a comma separated list of codes that represent the supported ad types. Valid values include
      • text - 135-character text ads
      • shorttext - 70-character text ads
      • textlink - 25-character text links.
      • image - JPEG, GIF of PNG images
      • flash - Adobe compiled Flash (SWF) files
      • flashtemplate - Customizable Adobe Flash (SWF) files
      • html - HTML or Javascript code
      • audio - MP3 & OGA audio files
      • video - MPEG4 (H.264), OGG, WEBM, & FLV video files
    • language - (string, rwa, optional) the code that denotes the default language of the ad zone. Defaults to en. For the full list of language codes, download the language configuration from your ad store.
    • channel - (string, rwa, optional) the code that denotes the default category / channel of the ad zone. For the full list of category codes, download the category configuration from your ad store.
    • position - (string, rwa, optional) the code that denotes the placement position of the ad zone. Valid values include
      • anywhere - the zone can be placed any where
      • above_left - the zone will be placed above the fold and left aligned
      • above_center - the zone will be placed above the fold and center aligned
      • above_right - the zone will be placed above the fold and right aligned
      • below_left - the zone will be placed below the fold and left aligned
      • below_center - the zone will be placed below the fold and center aligned
      • below_right - the zone will be placed below the fold and right aligned
      • overlay - the zone will be placed in a content overlay
      • interstitial - the zone will be placed as an intersitial i.e before content
      • pre_roll - the zone will be placed before the video or audio stream starts
      • mid_roll - the zone will be placed in the middle of the video or audio stream
      • post_roll - the zone will be placed after the video or audio stream is finished

        The default value is anywhere.

    • scope - (string, rwa, optional) the code that denotes the visibility of the ad zone in the ad store. Valid values include
      • public - the zone will be visible to everybody
      • private - the zone will only be visible to system operators.

        The default value is public.

    • info_url - (string, rwa, optional) a fully qualified URL to a resource that provides more information about the ad zone such as a website, or media kit file
    • preview_url - (string, rwa, optional) a fully qualified URL to a live preview or screenshot of the ad zone.
    • default_ad_tag - (string, rwa, optional) the code that describes how to fetch ads when there are no self-service or directly sold ads are available. Valid values include
      • An empty space
      • A valid ad tag. See the Ad Tag Specification for more details.
      • tsadfeed - specifies that the ad servers should choose an ad from one of the ad feeds that is mapped to the same channel as the ad zone.

        If no value is specified, the ad zone will show a blank space.

    • description - (string, rwa, optional) a description of the ad zone.
    • creation_date - (datetime, r) the date on which the ad zone was created.
    • last_modified_date - (datetime, r) the date on which the ad zone was last modified.
    • realm - (string, r) the subdomain name of the ad store
    • linked_user - (object, rw)
      • id - (string, rw) the alphanumeric unique identifier of the user that created the zone
      • name - (string, r) the username of the user that created the zone
    • pricing - (object, rwa)
      • model - (string, rw) specifies the pricing method used for the ad zone. Valid values include
        • cpm - cost per thousand impressions
        • cpc - cost per click
        • cpd - cost per day (tenancy)
      • accept_bids - (boolean, rwa) if true, it allows advertisers to set their own bid prices
      • price - (double, rwa) the fixed price of the ad zone. If the accept_bids value is set, then this is the minimum bid price.
      • volume_minimum - (unsigned, rwa) the minimum order quantity.
      • volume_maximum - (unsigned, rwa) the maximum order quantity.
      • volume_minimum - (unsigned, rwa) the incremental order quantity.
      • order_concurrency - (unsigned, rwa) the maximum number of orders that can run concurrently. For unlimited concurrency, set it to 0. Applies to Pay Per Day ad zones only.
      • discounts - (collection, rwa, optional) contains one or more discount objects each of which represents a discount band
        • discount - (object, rwa, optional)
          • discount_rate - (double, rwa) the discount rate in the range 0 to 100.
          • volume_minimum - (unsigned, rwa) the minimum order quantity required for the discount
    • zone_statistic - (object, r) the latest traffic stats. Each stat is expressed as a daily moving average
      • hits - (double, r) the number of ad calls
      • uniques - (double, r) the number of unique visitors to making ad calls
      • clicks - (double, r) the number of valid clicks on ads
      • conversions - (double, r) the number of valid conversions from ads that have been shown previously
      • views - (double, r) the number of ad playbacks (video and audio ads only)..
      • duration - (double, r) the average time spent per ad playback video and audio ads only.
      • timespent - (double, r) the average time spent making ad calls per unique visitor
      • very_short_stay_uniques - (double, r) the number of unique visitors for whom timespent is <= 30 seconds
      • short_stay_uniques - (double, r) the number of unique visitors for whom timespent is > 30 seconds and <= 5 minutes
      • medium_stay_uniques - (double, r) the number of unique visitors for whom timespent is > 5 minutes and <= 20 minutes
      • long_stay_uniques - (double, r) the number of unique visitors for whom timespent is > 20 minutes and <= 45 minutes
      • very_long_stay_uniques - (double, r) the number of unique visitors for whom timespent is > 45 minutes
      • date - (datetime, r) the time for which the the statistic was calculated
      • linked_zone - (object, r)
        • id - (string, r) the alphanumeric unique identifier of zone for which this stat was calculated
        • name - (string, r) the name of the zone for which this stat was calculated

Examples


Ad Zone - JSON


{
    "id": "140f0e6a",
    "handle": "MDEyMzQzOTkzNTQzMjE=",
    "name": "My First Ad Zone",
    "width": 300,
    "height": 250,
    "formats": "image,flash,video",
    "language": "en",
    "channel": "lifestyle"
    "position": "top_right",
    "scope": "public",
    "info_url": "http://www.mywebsite.com/advertising/",
    "thumbnail_url": "http://cdn.trafficspaces.com/adspaces/.../310c4445-a5b2-3bf7-8e60-730edcc8a2a5_img.jpg",
    "preview_url": "",
    "default_ad_tag": "http://www.mywebsite.com/defaultad.jpg",
    "description": "Ads will appear above the fold on all pages",
    "realm": "demo",
    "creation_date": "2010-11-19T00:25:01",
    "last_modified_date": "2010-11-19T00:25:01",
    "linked_user": {
        "id": "0937111d0e6b33150a0e6f66",
        "name": "admin@mywebsite.com"
    },
    "pricing": {
        "model": "cpm",
        "accept_bids": "Y",
        "price": 1.5,
        "price_increment": 0.1,
        "volume_minimum": 10000,
        "volume_maximum": 1000000,
        "volume_increment": 10000,
        "order_concurrency": 0,
        "discounts": {
            "discount": [
                {
                    "discount_rate": 5.0,
                    "volume_minimum": 500000
                },
                {
                    "discount_rate": 10.0,
                    "volume_minimum": 1000000
                }
            ]
        }
    },
    "zone_statistic": {
        "hits": 167.29166666666669,
        "uniques": 60.833333333333336,
        "clicks": 0,
        "conversions": 0,
        "views": 3,
        "duration": 55.416666666699996,
        "timespent": 23.499999999955797,
        "very_short_stay_uniques": 45.625,
        "short_stay_uniques": 15.208333333333334,
        "medium_stay_uniques": 0,
        "long_stay_uniques": 0,
        "very_long_stay_uniques": 0,
        "date": "2011-04-05T00:00:00",
        "linked_zone": {
            "id": "140f0e6a",
            "name": "My First Ad Zone"
        }
    }
}

Ad Zone - XML


<?xml version="1.0" encoding="UTF-8"?>
<zone>
    <id>140f0e6a</id>
    <handle>MDEyMzQzOTkzNTQzMjE=</handle>
    <name>My First Ad Zone</name>
    <width>300</width>
    <height>250</height>
    <formats>image,flash,video</formats>
    <language>en</language>
    <channel>lifestyle</channel>
    <position>top_right</position>
    <scope>public</scope>
    <info_url>http://www.mywebsite.com/advertising/</info_url>
    <thumbnail_url>http://cdn.trafficspaces.com/adspaces/.../310c4445-a5b2-3bf7-8e60-730edcc8a2a5_img.jpg</thumbnail_url>
    <preview_url></preview_url>
    <default_ad_tag>&lt;!--#config timefmt="%e%m%Y%H%m%S" --&gt; &lt;script language="JavaScript" src="http://ad.doubleclick.net/adj/www.mywebsite.com/boxe;tile=1;dcopt=ist;sz=728x90;ord=&lt;!--#echo var="DATE_LOCAL"--&gt;?" type="text/javascript"&gt;&lt;/script&gt; &lt;noscript&gt; &lt;a href="http://ad.doubleclick.net/jump/www.mywebsite.com/boxe;tile=1;sz=728x90;ord=&lt;!--#echo var="DATE_LOCAL"--&gt;?" target="_blank"&gt; &lt;img src="http://ad.doubleclick.net/ad/www.mywebsite.com/boxe;tile=1;sz=728x90;ord=&lt;!--#echo var="DATE_LOCAL"--&gt;?" width="728" height="90" border="0" alt=""&gt; &lt;/a&gt; &lt;/noscript&gt;</default_ad_tag>
    <description>Ads will appear above the fold on all pages</description>
    <creation_date>2010-11-19T00:25:01</creation_date>
    <last_modified_date>2010-11-19T00:25:01</last_modified_date>
    <realm>demo</realm>
    <linked_user>
        <id>0937111d0e6b33150a0e6f66</id>
        <name>admin@mywebsite.com</name>
    </linked_user>
    <pricing>
        <model>cpm</model>
        <accept_bids>true</accept_bids>
        <price>1.5</price>
        <price_increment>0.1</price_increment>
        <volume_minimum>10000</volume_minimum>
        <volume_maximum>1000000</volume_maximum>
        <volume_increment>10000</volume_increment>
        <order_concurrency>0</order_concurrency>
        <discounts>
            <discount>
                <discount_rate>5.0</discount_rate>
                <volume_minimum>500000</volume_minimum>
            </discount>
            <discount>
                <discount_rate>10.0</discount_rate>
                <volume_minimum>1000000</volume_minimum>
            </discount>
        </discounts>
    </pricing>
    <zone_statistic>
        <hits>167.29166666666669</hits>
        <uniques>60.833333333333336</uniques>
        <clicks>0.0</clicks>
        <conversions>0.0</conversions>
        <views>3.0</views>
        <duration>55.416666666699996</duration>
        <timespent>23.499999999955797</timespent>
        <very_short_stay_uniques>45.625</very_short_stay_uniques>
        <short_stay_uniques>15.208333333333334</short_stay_uniques>
        <medium_stay_uniques>0.0</medium_stay_uniques>
        <long_stay_uniques>0.0</long_stay_uniques>
        <very_long_stay_uniques>0.0</very_long_stay_uniques>
        <date>2011-04-05T00:00:00</date>
        <linked_zone>
            <id>140f0e6a</id>
            <name>My First Ad Zone</name>
        </linked_zone>
    </zone_statistic>
</zone>

Ad Zone Statistics - JSON


[
    {
        "hits": 167.29166666666669,
        "uniques": 60.833333333333336,
        "clicks": 0,
        "conversions": 0,
        "views": 3,
        "duration": 55.416666666699996,
        "timespent": 23.499999999955797,
        "very_short_stay_uniques": 45.625,
        "short_stay_uniques": 15.208333333333334,
        "medium_stay_uniques": 0,
        "long_stay_uniques": 0,
        "very_long_stay_uniques": 0,
        "date": "2011-04-05T00:00:00",
        "linked_zone": {
            "id": "140f0e6a",
            "name": "My First Ad Zone"
        }
    }
]

Ad Zone Statistics - XML


<?xml version="1.0" encoding="UTF-8"?>
<zone_statistics>
    <zone_statistic>
        <hits>167.29166666666669</hits>
        <uniques>60.833333333333336</uniques>
        <clicks>0.0</clicks>
        <conversions>0.0</conversions>
        <views>3.0</views>
        <duration>55.416666666699996</duration>
        <timespent>23.499999999955797</timespent>
        <very_short_stay_uniques>45.625</very_short_stay_uniques>
        <short_stay_uniques>15.208333333333334</short_stay_uniques>
        <medium_stay_uniques>0.0</medium_stay_uniques>
        <long_stay_uniques>0.0</long_stay_uniques>
        <very_long_stay_uniques>0.0</very_long_stay_uniques>
        <date>2011-04-05T00:00:00</date>
        <linked_zone>
            <id>140f0e6a</id>
            <name>My First Ad Zone</name>
        </linked_zone>
    </zone_statistic>
</zone_statistics>
Section:
API
Last Updated:
04 Mar, 2012 12:39 AM

Recent Discussions

25 Apr, 2012 05:25 PM Reg : API in asp.net
08 May, 2012 08:34 PM Unconventional use of TrafficSpaces
02 May, 2012 11:13 PM iPad SDK information

Recent Articles

API: Code Samples & Libraries
API: Authentication
API: Placements
API: Orders
API: Campaigns