API: Targeting Plans

A Targeting Plan resource describes the how an ad can be targeted to a relevant audience.

It allows advertisers to describe an ad's target audience by specifying criteria such as the geographic location, demographic descriptors, contextual keywords, interest categories, days of week, etc.

A single Targeting Plan object can be reused across multiple ads and the underlying targeting criteria can be integrated with a publisher's proprietary database.

Supported Methods

List targeting plans

• URL - http://<subdomain>.trafficspaces.com/resources/targetingplans/
• 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 targeting plans in the requested format

Read a targeting plan

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

Create a new targeting plan

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

Update an existing targeting plan

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

Delete an existing targeting plan

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

Attributes

• targeting_plan - (object, rwa)
  • id - (string, r) the alphanumeric unique identifier
  • name - (string, rwa) the display name in the ad store.
  • realm - (string, r) the subdomain name of the ad store
  • creation_date - (datetime, r) the date on which the targeting plan was created.
  • last_modified_date - (datetime, r) the date on which the targeting plan was last modified.
  • targets - (object, rwa, optional) contains a set of key and value pairs that describe how the ad 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, rwa, optional) codes that describe the geographic locations to which ads can be targeted.
    • keywords - (string, rwa, optional) contextual keywords to which ads can be targeted.
    • interests - (string, rwa, optional) codes that describe the publisher-defined interest categories to which ads can be targeted.
    • coordinates - (string, rwa, 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, rwa, optional) codes that describe the gender groups to which ads can be targeted.
    • ageranges - (string, rwa, optional) codes that describe the age range groups to which ads can be targeted.
    • incomeranges - (string, rwa, optional) codes that describe the income range groups to which ads can be targeted.
    • ethnicities - (string, rwa, optional) codes that describe the ethnic groups to which ads can be targeted.
    • relationships - (string, rwa, optional) codes that describe the relationship status groups to which ads can be targeted.
    • qualifications - (string, rwa, optional) codes that describe the academic qualification groups to which ads can be targeted.
    • jobs - (string, rwa, optional) codes that describe the job groups to which ads can be targeted.
    • industries - (string, rwa, optional) codes that describe the commercial industry groups to which ads can be targeted.
    • religions - (string, rwa, optional) codes that describe the religious groups to which ads can be targeted.
    • politics - (string, rwa, optional) codes that describe the political groups to which ads can be targeted.
    • urls - (string, rwa, optional) URLs to which ads can be targeted.
    • ipaddresses - (string, rwa, optional) IP addresses to which ads can be targeted.
    • daysofweek - (string, rwa, optional) codes that describe the days of week to which ads can be targeted.
    • hoursofday - (string, rwa, optional) codes that describe the hours of day to which ads can be targeted.
  • linked_user - (object, rw)
    • id - (string, rw) the alphanumeric unique identifier of the user that created the targeting plan
    • name - (string, r) the username of the user that created the targeting plan

Examples

Targeting Plan - JSON

{
    "id": "160f1e66",
    "name": "US and Canada Only",
    "realm": "demo",
    "creation_date": "2010-04-30T19:58:17",
    "last_modified_date": "2011-04-27T15:04:14",
    "targets": {
        "keywords": "baseball,basketball,football",
        "geographics": "us,ca"
    },
    "linked_user": {
        "id": "0937111d0e6b33150a0e6f66",
        "name": "advertiser@advertiser.com"
    }
}

Targeting Plan - XML

<?xml version="1.0" encoding="UTF-8"?>
<targeting_plan>        
    <id>160f1e66</id>
    <name>US and Canada Only</name>
    <realm>demo</realm>
    <creation_date>2010-04-30T19:58:17</creation_date>
    <last_modified_date>2011-04-27T15:04:14</last_modified_date>
    <targets>
        <keywords>baseball,basketball,football</keywords>
        <geographics>us,ca</geographics>
    </targets>
    <linked_user>
        <id>0937111d0e6b33150a0e6f66</id>
        <name>advertiser@advertiser.com</name>
    </linked_user>
</targeting_plan>