API: Placements

A placement is an instance of an ad zone on your page or app, in which you wish to display an ad. A single ad zone can have multiple placements on a single page or across a network of sites.

Each ad zone that you create in the Ad Store has a unique handle and an tage which can be used to create placements of the ad zone on a web page, and fetch ads into the placement.

You can also create chained placements by concatenating their handles and separating them with commas to form a single composite placement that can be used to fetch ads in a chain.

Supported Methods

URI	GET	POST	PUT	DELETE
/resources/placements	List	-	-	-

List placements

URL - http://ads.trafficspaces.net/resources/placements.<format>. The format may be either xml, json or custom.
Method - GET
Parameters -
- request - (object) contains the input data if the request method is an HTTP GET.
- callback - (string, optional) the name of a Javascript function that's automatically invoked with the response data as its single parameter. Useful if fetching the zone placements with a <script> tag.
- template - (string, optional) the specification of the output format when custom formatting is enabled. See Custom Formatting for information on how to specify your own output format.
- redirect - (boolean, optional) specifies whether the ad server should send a 302 redirect to the output format. If the resource is empty, then the ad servers will send a `HTTP/1.0 404 Not Found` response code. The default value is false.
Response
- Status - 200, if successful.
- Body - an array of up to zone placements enriched with ads in the requested format

Input Attributes

request - (object, rwa)
- placements - (collection, rw) contains zone placement objects, each of which requests a specification of the ads required for each instance of an ad zone
  - placement - (object, rw)
    - handle - (string, rw) the handle of the zone placement. To chain multiple zones together, it should contain a comma separated list of individual handles.
    - medium - (string, rw, optional) indicates the type of ad required. Valid values include
      - textlink - text link ads i.e. text ad titles only
      - shorttext - 75 character text ads only
      - text - All text ads (excluding text links)
      - image - GIF, JPEG and PNG ads
      - flash - All flash ads (includes template-based ads)
      - template - Flash template based ads only
      - video - All video ads
      - audio - All audio ads
      - banner - All image and flash ads
      - html - HTML or Javascript ads
      - feed - Ad feeds only
      - all - All types of ad.
        The default value is all.
    - count - (integer, rw, optional) indicates the number of instances of the placements for which ads are required. The default value is 1
    - useiframe - (boolean, rw, optional) indicates whether the generated ad should be displayed in its own frame.
    - frame - (string, rw, optional) the name of the target frame. The default value is _self
    - title - (string, rw, optional) used as the alt and hover text in image ads
- flags - (object, rw, optional) contains a set of key and value pairs that describe how the ads should be targeted. Each value can be a single string or a comma separated list of string codes. You can download and edit the list of valid codes for each targeting criteria from the Setup->System->Preferences->Advanced section of your ad store.
  - geographics - (string, rw, optional) codes that describe the geographic locations to which ads can be targeted.
  - keywords - (string, rw, optional) contextual keywords to which ads can be targeted.
  - interests - (string, rw, optional) codes that describe the publisher-defined interest categories to which ads can be targeted.
  - coordinates - (string, rw, optional) Longitude and latitude pairs that describe the geographic areas to which ads can be targeted. Each pair consists of the longitude and latitude specified in positive or negative decimal degrees separated by an empty space.
  - genders - (string, rw, optional) codes that describe the gender groups to which ads can be targeted.
  - ageranges - (string, rw, optional) codes that describe the age range groups to which ads can be targeted.
  - incomeranges - (string, rw, optional) codes that describe the income range groups to which ads can be targeted.
  - ethnicities - (string, rw, optional) codes that describe the ethnic groups to which ads can be targeted.
  - relationships - (string, rw, optional) codes that describe the relationship status groups to which ads can be targeted.
  - qualifications - (string, rw, optional) codes that describe the academic qualification groups to which ads can be targeted.
  - jobs - (string, rw, optional) codes that describe the job groups to which ads can be targeted.
  - industries - (string, rw, optional) codes that describe the commercial industry groups to which ads can be targeted.
  - religions - (string, rw, optional) codes that describe the religious groups to which ads can be targeted.
  - politics - (string, rw, optional) codes that describe the political groups to which ads can be targeted.
  - languages - (string, rw, optional) codes that describe the languages to which ads can be targeted.
- medium - See the definition in the placement objects.
- useiframe - See the definition in the placement objects.
- frame - See the definition in the placement objects.
- title - See the definition in the placement objects.

Note: The medium, useiframe, frame, and title properties can be set at the request level or overridden in each placement object.

Example - JSON

This example shows a request to fetch one untargeted ad.

{
    "placements": [
        {"handle" : "MTk0MzI0NjY4MjE3NQ=="}
    ],
    "medium" : "all"
};

Example - XML

This example shows a request to fetch three ads (one text, and two images) that are targeted to the United States and Canada, in the fishing interest category. Each ad is loaded in a frame and opens a new window when it is clicked.

<?xml version="1.0" encoding="UTF-8"?>
<request>
    <placements>
        <placement>
            <handle>MDEyMzQzOTMzNTQzMjE=</handle>
            <medium>text</medium>
        </placement>
        <placement>
            <handle>MDEyMzQzOTMzNTQzMjE=</handle>
            <medium>image</medium>
            <count>2</count>
        </placement>
    </placements>
    <flags>
        <geographics>us, ca</geographics>
        <interests>fishing</interests>
    <flags>
    <useiframe>true</useiframe>
    <targetframe>_blank</targetframe>
</request>

Example - XML chaining

This example shows a request to fetch one banner ad (image or flash) sourced from either of the three zones in the comma separated list of handles.

<?xml version="1.0" encoding="UTF-8"?>
<request>
    <placements>
        <placement>
            <handle>MDEyMzQzOTMzNTQzMjE=, MDEyMzQzODc5NTQzMjE=, MDEyMzQzPvT3BWQzMjE=</handle>
            <medium>banner</medium>
        </placement>
    </placements>
</request>

Output Attributes

The output contains a collection of zone placement objects, each of which has been enriched with ads

placement - (object, r)
- handle - (string, r) represents the handle of the ad zone placement for which the ads were fetched
- ads - (collection, r) contains ad objects
  - ad - (object, r)
    - medium - (string, r) the type of ad.
    - width - (integer, r) the ad's width
    - height - (integer, r) the ad's height
    - creative - (object, r) represents the actual creative. It includes
      - flash_url - (string, r) the URL to the flash content
      - video_url - (string, r) the URL to the video content
      - audio_url - (string, r) the URL to the audio content
      - image_url - (string, r) the URL to the image content. If the medium is set to flash, video, or audio, then this is the substitute image
      - target_url - (string, r) the URL to fetch when the ad is clicked upon.
      - title - (string, r) the URL to fetch when the ad is clicked upon.
      - caption - (string, r) the URL to fetch when the ad is clicked upon.
      - anchor - (string, r) the anchor text.

Example - JSON

[
    {
        "handle": "MTk0MzI0NjY4MjE3NQ==",
        "ads": [
            {
                "medium": "image",
                "width": 728,
                "height": 90,
                "creative": {
                    "image_url": "http://cdn.trafficspaces.net/ads/36077501-df52-38b4-bd8b-3700c3f2ce7c/054be7e3-aaa4-39dc-885a-9c0c36629287/054be7e3-aaa4-39dc-885a-9c0c36629287_img",
                    "target_url": "http://ads.trafficspaces.net/adclick.php?a=MDEyMzQ0NjY1NDMyMQ%3D%3D&b=203&c=207&d=272&e=6be4f4216eb454e2b40a40729d68e1a0&url=http%3A%2F%2Fwww.johansendesign.com"
                }
            }
        ]
    }
]

Example - XML

<?xml version="1.0" encoding="UTF-8"?>
<placements>
    <placement>
        <handle>MDEyMzQzOTMzNTQzMjE=</handle>
        <ads>
            <ad>
                <medium>text</medium>
                <width>300</width>
                <height>250</height>
                <creative>
                    <image_url>http://cdn.trafficspaces.net/ads/36077501-df52-38b4-bd8b-3700c3f2ce7c/51245e6a-61c7-3726-8f48-999e701ecfc3_img</image_url>
                    <title>Get Bob Marley's Hits</title>
                    <caption>Own Bob Marley's classics at an all time low price. 25% discount on all orders before Dec 21st. Order now. </caption>
                    <anchor>ClassicCDs.com</anchor>
                    <target_url>http://ads.trafficspaces.net/adclick.php?a=MDEyMzQ0NjY1NDMyMQ%3D%3D&b=180&c=184&d=274&e=d9266799f6cfa46ce8b1754859bb5b5b&url=http%3A%2F%2Fwww.classiccds.com</target_url>
                </creative>
            </ad>
            <ad>
                <type>image</type>
                <width>300</width>
                <height>250</height>
                <creative>
                    <image_url>http://cdn.trafficspaces.net/ads/29aff649-8d03-3306-af4d-d001dfe3992d/de2167d7-ab1a-3064-b68f-825ac35a7da0_img.gif</image_url>
                    <target_url>http://ads.trafficspaces.net/click.php?a=MDEyMzQzOTMzNTQzMjE%3D&amp;b=1418&amp;c=3479&amp;d=1606&amp;e=52fc87c215265bdf317cfa5c3ba5d7a7&amp;url=http%3A%2F%2Fwww.seattleboatshow.com%2F</target_url>
                </creative>
            </ad>
            <ad>
                <type>flash</type>
                <width>300</width>
                <height>250</height>
                <creative>
                    <flash_url>http://cdn.trafficspaces.net/ads/29aff649-8d03-3306-af4d-d001dfe3992d/de2167d7-ab1a-3064-b68f-825ac35a7da0_rm</flash_url>
                    <image_url>http://cdn.trafficspaces.net/ads/29aff649-8d03-3306-af4d-d001dfe3992d/de2167d7-ab1a-3064-b68f-825ac35a7da0_img.gif</image_url>
                    <target_url>http://ads.trafficspaces.net/click.php?a=MDEyMzQzOTMzNTQzMjE%3D&amp;b=1418&amp;c=3479&amp;d=1606&amp;e=52fc87c215265bdf317cfa5c3ba5d7a7&amp;url=http%3A%2F%2Fwww.seattleboatshow.com%2F</target_url>
                </creative>
            </ad>
        </ads>
    </placement>
<placements>

Custom Formatting

The Placements API has a special feature that allows you to specify the format of the response data by specifying a set of placeholders.

The placeholders include

ts.handle - (string) represents the handle of the ad zone placement for which the ads were fetched
ts.medium - (string) the type of ad.
ts.width - (integer) the ad's width
ts.height - (integer) the ad's height
ts.flash_url - (string) the URL to the flash content
ts.video_url - (string) the URL to the video content
ts.audio_url - (string) the URL to the audio content
ts.image_url - (string) the URL to the image content. If the medium is set to flash, video, or audio, then this is the substitute image
ts.target_url - (string) the URL to fetch when the ad is clicked upon.
ts.title - (string) the URL to fetch when the ad is clicked upon.
ts.caption - (string) the URL to fetch when the ad is clicked upon.
ts.anchor - (string) the anchor text.
ts.creative - (string) this is a pseudonym for any of the placeholders that represent the main creative i.e ts.flash_url, ts.video_url, ts.audio_url, ts.image_url or ts.caption.

Each placeholder must be enclosed in curly braces e.g. {ts.width}

To use the custom formatting feature, your request URL must be http://ads.trafficspaces.net/resources/placements.custom and you must specify the output format in the template parameter.

Examples

To fetch only the image URL, set template to {ts.image_url}

To fetch a video URL via a 302 redirect (or to recieve a HTTP/1.0 404 Not Found if there is no ad), set template to {ts.video_url} and set redirect to true

To fetch all the parameters of a text ad as a comma separated list, set template to {ts.handle},{ts.medium},{ts.width},{ts.height},{ts.title},{ts.caption},{ts.anchor},{ts.target_url}

Recent Discussions

	21 Feb, 2012 09:38 PM	Some questions and overview of how ad selection works
	11 Jul, 2011 11:27 PM	Compliance with IAB standards for Serving Video Ads
	01 Dec, 2010 03:46 PM	Delete Ads Clear Account
	16 Feb, 2012 09:43 AM	Counting stats-only tag in impressions?

Recent Articles

	API: Placements
	API: Targeting Plans
	API: Introduction
	API: Code Samples & Libraries
	API: Authentication

Trafficspaces Support

API: Placements

Supported Methods

List placements

Input Attributes

Example - JSON

Example - XML

Example - XML chaining

Output Attributes

Example - JSON

Example - XML

Custom Formatting

Examples

General Questions - Publishers

API

Recent Discussions

Recent Articles