API: Ads

An Ad resource describes the attributes of an advertisement such as its creative (image, target URL, caption etc), dimensions, targeting preferences etc.

Every ad has a creative format which can either be an image, text, flash, video or audio. In addition, each ad can be linked to an ad targeting plan, which specifies how the ad should be targeted to users.

Supported Methods

List ads

• URL - http://<subdomain>.trafficspaces.com/resources/ads/
• Method - GET
• Parameters -
  • 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 ads in the requested format

Read an ad

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

Create a new ad

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

Update an existing ad

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

Delete an existing ad

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

Attributes

• ad - (object, rwa)
  • id - (string, r) the alphanumeric unique identifier
  • name - (string, rwa) the display name in the ad store.
  • width - (unsigned, rw) the display width of the ad (excludes text, video and audio).
  • height - (unsigned, rw) the display height of the ad (excludes text, video and audio).
  • status - (string, r) the code that denotes the publishing status of the ad. Valid values include
    • draft - the ad is currently in edit mode and will not shown live.
    • pending - the ad has been submitted for approval and is awaiting a response from the admin.
    • approved - the ad has been approved by the admin and is locked for live use.
    • rejected - the ad has been rejected by the admin but has not yet being re-edited by the submitter.

      Note: Ads that are created by a privileged user (such as the admin) are moved automatically into the approved state.

  • format - (string, rw) the code that specifies what type of ad it is. 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
    • raw - HTML or Javascript code
    • audio - MP3 & OGA audio files
    • video - MPEG4 (H.264), OGG, WEBM, & FLV video files
  • creative - (object, rwa) represents the actual creative
    • flash_url - (string, rwa) the URL to the flash rich media content. Applies to flash and flashtemplate ads only.
    • video_url - (string, rwa) the URL to the video rich media content. Applies to video ads only.
    • audio_url - (string, rwa) the URL to the audio rich media content. Applies to audio ads only.
    • image_url - (string, rwa) the URL to the image content. If the format is set to flash or flashtemplate then this is the substitute image. Applies to image, text, flash and flashtemplate ads only.
    • title - (string, rwa) the URL to fetch when the ad is clicked upon. Applies to text ads only.
    • caption - (string, rwa) the URL to fetch when the ad is clicked upon. Applies to text ads only.
    • raw - (string, rwa) the raw data. Applies to HTML / Javascript ads only.
    • anchor - (string, rwa) the anchor text. Applies to text ads only.
    • target_url - (string, rwa) the URL to fetch when the ad is clicked upon.
  • creation_date - (datetime, r) the date on which the ad was created.
  • last_modified_date - (datetime, r) the date on which the ad 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 ad
    • name - (string, r) the username of the user that created the ad
  • linked_contact - (object, rwa, optional)
    • id - (string, rwa, optional) the alphanumeric unique identifier of the managed advertiser for whom the ad was created
    • name - (string, r) the name of the ad's managed advertiser
  • linked_targeting_plan - (object, rwa, optional)
    • id - (string, rwa) the alphanumeric unique identifier of targeting plan that describes how the ad should be shown
    • name - (string, r) the name of the ad's targeting plan

Examples

Ad - JSON

{
    "id": "16311a6a",
    "name": "Fine Home Designs",
    "width": 0,
    "height": 0,
    "status": "approved",
    "format": "text",
    "realm": "demo",
    "creative": {
        "title": "Get A Free Design Quote",
        "image_url": "",
        "caption": "Need a free interior design quote from Fine Home Designs. Offer lasts till Mar 31st. Register today.",
        "target_url": "http://www.FineHomeDesigns.com"
    },
    "linked_user": {
        "id": "0937111d0e6b33150a0e6f66",
        "name": "admin@mywebsite.com"
    },
    "linked_contact": {
        "id": "150a6666",
        "name": "Chris Parks"
    },
    "creation_date": "2010-03-13T21:22:41",        
    "last_modified_date": "2011-04-05T23:58:11"
}

Ad - XML

<?xml version="1.0" encoding="UTF-8"?>
<ad>
    <id>16311a21</id>
    <name>Johansen Design</name>
    <width>728</width>
    <height>90</height>
    <status>approved</status>
    <format>image</format>
    <realm>demo</realm>
    <creative>
        <image_url>http://cdn.trafficspaces.com/ads/.../054be7e3-aaa4-39dc-885a-9c0c36629287_img</image_url>
        <target_url>http://www.johansondesign.se</target_url>
    </creative>
    <linked_user>
        <id>0937111d0e6b33150a0e6f66</id>
        <name>advertiser@advertiser.com</name>
    </linked_user>
    <linked_targeting_plan>
        <id>160f1e66</id>
        <name>Sweden Only</name>
    </linked_targeting_plan>
    <creation_date>2010-03-13T20:40:33</creation_date>
    <last_modified_date>2011-04-07T19:30:09</last_modified_date>
</ad>