Link Search Menu Expand Document

PDF

Targeting Dimension Reference

Platform API

Last updated on August 10, 2020


Use the following reference sections to view targeting parameters and sample code.


Targeting API Calls that Require an Account ID

Some targeting API calls require that you include an account id to list targetable options for the user to target against.

The following table lists the options that require an account ID:

DimensionSyntax and exampleAccount type required
Inventoryoxsearch/targetable?account_id=<parent_account_id>

Example:
http://openx_server_name.openx.net/ox/4.0/oxsearch/targetable?account_id=account_id
The parent account of the object to which you are adding targeting data.
OpenX Audiencetargetable_audiencesegment_options?account_id=<current_account_id>

Example:
http://openx_server_name.openx.net/ox/4.0/options/targetable_audiencesegment_options?account_id=account_id
Current user’s account.
Third-party Audiencetargetable_audiencesegment_options?dmp=1&account_id=<current_account_id>

Example:
http://openx_server_name.openx.net/ox/4.0/options/targetable_audiencesegment_options?dmp=1&account_id=account_id
Current user’s account.

Audience Segment

Use the audience dimension to target specific audience types.

Audience

Attributes and values

AttributeValue
opValues include:
   • AND
   • OR
dmp_segmentsRepresents dimensions for the Data Management Platform (DMP).
   • op: List of accepted values for the following attribute:
      • INTERSECTS: Contains any of
      • INVERSE IN: Contains all of
   • val: A comma-separated list of DMP sources prefixed by DMP audience segment IDs obtained using the following:
      • An options url, such as: /options/targetable_audiencesegment_options?account_id=account_id&dmp=1
      • Using an ID key (DMP source prefixed id)
audience_typeRepresents the intended audience for exchange line items.
   • op: Accepted value for this attribute is INTERSECTS (Contains any of).
   • val: A comma-separated string of audience IDs. The default value is 1,2 (Everyone over 12 years old).

audience type val example

{
	'All' : '1,2,3',  //All Audiences
	'>12' : '1,2',    //Everyone over 12 years
	'>17' : '1',      //Everyone over 17 years
	'<13' : '3',      //Child directed
	'<18' : '2,3'     //Minor directed
}

Sample

"audience": {
        "op": "AND",
        "val": [{
                "attr": null,
                "op": "INTERSECTS",
                "val": "1610753366"
        }],
        "dmp_segments": {
                "op": "INTERSECTS",
                "val": "krux-1,krux-2,krux-4"
        },
        "audience_type": {
                "op": "INTERSECTS",
                "val": "1,2"
        }
}

Content

Use the content dimension to target specific content types such as inventory, ad unit sizes, content topic, content type, page url, and screen location.

Inventory

Attributes and parameters

You can specify the type of audience you want to target by specifying multiple key-value pairs with the key as the object type and the value as a comma-separated list of ids for the following:

AttributeParameter
includes
excludes
key: Object type
val: A comma-separated list of legacy IDs for the object. These IDs can be obtained by making a separate call to /oxsearch/targetable.

Sample

"content": {
        "excludes": {
                "adunit": "1610612798"
        },
        "includes": {
                "account": "537237763",
                "adunit": "1610747154",
                "site": "1610612798,1610750644"
        }
}

Additional inventory targeting details

URL: ox/4.0/oxsearch/targetable?account_uid=account_uid

POST data

Encoded

q=name%3A*<QUERY>*%20AND%20((type%3Aadunitgroup%20AND%20delivery_medium_id%3A<DELIVERY_MEDIUM_ID>)%20OR%20type%3Aaccount%20OR%20type%3Asite%20OR%20(type%3Aadunit%20AND%20type_full%3A(<ADUNIT_DELIVERY_TYPE_FULLS>))%20OR%20type%3Asitesection)

Parsed

q:name:*<QUERY>* AND ((type:adunitgroup AND delivery_medium_id:<DELIVERY_MEDIUM_ID>) OR type:account OR type:site OR (type:adunit AND type_full: (<ADUNIT_DELIVERY_TYPE_FULLS>)) OR type:sitesection)
Search objectDescription
<QUERY>Name of the search object.

Note: The following Lucene special characters must be escaped in the query: + - && || ! ( ) { } [ ] ^ " ~ * ? : \
<DELIVERY_MEDIUM_ID>• Options URL: /ox/4.0/options/delivery_medium_options
• Key: Legacy ID
• Example value: 2 (web delivery medium)
<ADUNIT_DELIVERY_TYPE_FULLS>• Options URL: /ox/4.0/options/delivery_medium_options
• Key: Legacy ID
• Example value: adunit.web OR adunit.videocompanion

Note: delivery_medium_id only accepts one value. adunit_delivery_type_fulls can accept multiple values that are OR’ed together.
Ad Unit Size

Attributes and parameters

AttributeParameter
adunit_sizeop: List of accepted values for this attribute:
      • INTERSECTS: Contains any of
      • NOT INTERSECTS: Contains none of
val: A comma-separated list of of width by height values. For example: 100x100,200x200.

Note: Custom width and heights are accepted as well. These values can be obtained by making a separate call to any of the following options urls (dependent on delivery_medium):
      • options/web_size_options
      • options/linearvideo_size_options
      • options/nonlinearvideo_size_options
      • options/mobile_size_options
      • options/native_size_options
      • options/email_size_options
      • options/exchange_size_options
      • options/videocompanion_size_options

Sample

"content": {
        "adunit_size": {
                "op": "INTERSECTS",
                "val": "970x250,728x90,88x31"
        }
}
Content Topic

Attributes and parameters

AttributeParameter
content_topicop: List of accepted values for this attribute:
   • INTERSECTS: Contains any of
   • NOT INTERSECTS: Contains none of
val: A comma-separated list of IDs which can be obtained by making a separate call to options/content_topic_options or by using a legacy ID.

Sample

"content": {
        "content_topic": {
                "op": "INTERSECTS",
                "val": "305,306,307"
        }
}
Content Type

Attributes and parameters

AttributeParameter
content_typeop: List of accepted values for this attribute:
   • INTERSECTS: Contains any of
   • NOT INTERSECTS: Contains none of
val: A comma-separated list of IDs which can be obtained by making a separate call to options/content_type_options or by using a legacy ID.

Sample

"content": {
        "content_type": {
                "op": "INTERSECTS",
                "val": "1,2,3"
        }
}
Page URL/Referring URL

Attributes and parameters

AttributeParameter
page_url
referring_url
op: List of accepted values for this attribute:
   • AND: Both parameters must be true
   • OR: One or the other parameter must be true.
val: An array of objects with the following keys:
      • op: List of accepted values for this attribute:
         • ==: Equals
         • !=: Does not equal
         • =?: Contains
         • NOT =?: Does not contain
         • =^: Begins with
         • NOT =^: Does not begin with
         • =$: Ends with
         • NOT =$: Does not end with
      • val: A user-defined string.
NOTE

Page URLs and Referring URLs are case-sensitive.

Sample

"content": {
        "page_url": {
                "op": "AND",
                "val": [{
                        "op": "==",
                        "val": "test"
                }, {
                        "op": "==",
                        "val": "someurl"
                }]
        }
}
Screen Location

Attributes and parameters

AttributeParameter
screen_locationop: List of accepted values for this attribute:
   • INTERSECTS: Contains any of
   • INVERSE IN: Contains all of
val: A comma-separated list of IDs. These IDs can be obtained using the following:
      • key: legacy_id
      • an options url, such as:
         • options/web_location_options
         • options/linearvideo_location_options
         • options/nonlinearvideo_location_options
         • options/mobile_location_options
         • options/videocompanion_location_options
         • options/email_location_options

Sample

"content": {
        "screen_location": {
                "op": "NOT INTERSECTS",
                "val": "2,1,3"
        }
}

Geographic

Use the geographic dimension to target specific locations by country, state, and city. Also target geographic areas by bounding box and/or radius.

Location

Attributes and parameters

You can specify the type of audience you want to target by specifying multiple key/value pairs with the key as the object type and the value as a comma-separated list of IDs for both the include and exclude parameter.

AttributeParameter
includes
excludes
city: Name of city. For example, New York or city code.
dma: Direct Marketing Area.
state: Name of State. For example, California or state code.
country: Name of Country. For example, Canada or country code.
region: Name of Region. For example, Bahamas or region code.
msa: Name of Metropolitan Statistical Area. For example, Los Angeles or msa code.
postal_code: Postal code. For example, 90120.

Sample

"geographic": {
        "excludes": {
                "city": "122985"
        },
        "includes": {
                "dma": "2",
                "state": "3588"
        }
}

Additional geographic targeting details

URL: /ox/4.0/geo/search?order=asc&sort=name.none

POST data

Encoded

q=((type%3Acontinent%20AND%20continent%3A<QUERY>*)%20OR%20(type%3Acountry%20AND%20country%3A<QUERY>*)%20OR%20(type%3Aregion%20AND%20region%3A<QUERY>*)%20OR%20(type%3Astate%20AND%20state%3A<QUERY>*)%20OR%20(type%3Acity%20AND%20city%3A<QUERY>*)%20OR%20(type%3Adma%20AND%20dma%3A<QUERY>*)%20OR%20(type%3Amsa%20AND%20msa%3A<QUERY>*)%20OR%20(type%3Apostal_code%20AND%20postal_code%3A<QUERY>*))

Parsed

q:((type:continent AND continent:<QUERY>*) OR (type:country AND country:<QUERY>*) OR (type:region AND region:<QUERY>*) OR (type:state AND state:<QUERY>*) OR (type:city AND city:<QUERY>*) OR (type:dma AND dma:<QUERY>*) OR (type:msa AND msa:<QUERY>*) OR (type:postal_code AND postal_code:<QUERY>*))

<QUERY>

Name of search object. The following Lucene special characters must be escaped in the query: + - && || ! ( ) { } [ ] ^ " ~ * ? : \

Bounding Box

Attributes and parameters

AttributeParameter
latitude
longitude
op: Accepted value for this attribute is IN (Compares a value to a list of literal values that have been specified).
val: Valid latitude and longitude values. Must be formatted as: "min_value - max_value".

Sample

"geographic": {
        "latitude": {
                "op": "IN",
                "val": "1 - 6"
        },
        "longitude": {
                "op": "IN",
                "val": "2 - 7"
        }
}
Radius

Attributes and parameters

AttributeParameter
circleop: Accepted value for this attribute is < (Less than).
val: A JSON string that contains an array of objects with keys: (rad - radius; lat - latitude; lon - longitude).

Restrictions for each value:
   Latitude:
      • /^[+\-]?(90|[1-8]?[0-9])([\.,]\d{0,6})?$/
      • between -90 and 90
    Longitude:
      • /^[+\-]?(180|1[0-7][0-9]|[1-9]?[0-9])([\.,]\d{0,6})?$/
      • between -180 and 180
   Radius:
      • /^[-+]?[0-9]*\.?[0-9]+$/
      • between 0 and 7000
      • Note that the radius value is in miles.

Sample

"geographic": {
        "circles": {
                "op": "<",
                "val": "[{\"rad\":\"5\",\"lon\":\"12\",\"lat\":\"12\"},{\"rad\":\"20\",\"lon\":\"13\",\"lat\":\"13\"}]"
        }
}

Technographic

Use the technographic dimension to target your audience by technology types such as browser type, connection speed, connection type, device type, mobile carrier, language, operating system, screen resolution, user agent, page position, cookies, device, and HTTPS.

Browser

Attributes and parameters

AttributeParameter
browserop: The following are accepted values for this attribute:
   • INTERSECTS: Contains any of
   • NOT INTERSECTS: Contains none of
val: A comma-separated list of IDs. These IDs can be obtained by making a separate call to options/browser_options.

Sample

"technographic": {
        "browser": {
                "op": "NOT INTERSECTS",
                "val": "23,128"
        }
}
Connection Speed

Attributes and parameters

AttributeParameter
connection_speedop: The following are accepted values for this attribute:
   • INTERSECTS: Contains any of
   • NOT INTERSECTS: Contains none of
val: A comma-separated list of IDs. These IDs can be obtained by making a separate call to options/connection_speed_options.

Sample

"technographic": {
        "connection_speed": {
                "op": "NOT INTERSECTS",
                "val": "3"
        }
}
Connection Type

Attributes and parameters

AttributeParameter
connection_typeop: The following are accepted values for this attribute:
   • INTERSECTS: Contains any of
   • NOT INTERSECTS: Contains none of
val: A comma-separated list of IDs. These IDs can be obtained by making a separate call to options/connection_type_options.

Sample

"technographic": {
        "connection_type": {
                "op": "INTERSECTS",
                "val": "6,3"
        }
}
Device Type

Attributes and parameters

AttributeParameter
device_typeop: The following are accepted values for this attribute:
   • INTERSECTS: Contains any of
   • NOT INTERSECTS: Contains none of
val: A comma-separated list of IDs. These IDs can be obtained by making a separate call to options/device_type_options.

Sample

"technographic": {
        "device_type": {
                "op": "INTERSECTS",
                "val": "3,2"
        }
}
Mobile Carrier

Attributes and parameters

AttributeParameter
isp_carrierop: The following are accepted values for this attribute:
   • INTERSECTS: Contains any of
   • NOT INTERSECTS: Contains none of
   • WIFI: WiFi option
val: A comma-separated list of IDs or NO_VALUE if WIFI is selected for op. These IDs can be obtained by making a separate call to options/isp_carrier.

Sample

"technographic": {
        "isp_carrier": {
                "op": "WIFI",
                "val": "NO_VALUE"
        }
}
Language

Attributes and parameters

AttributeParameter
languageop: The following are accepted values for this attribute:
•    INTERSECTS: Contains any of
•    NOT INTERSECTS: Contains none of
val: A comma-separated list of IDs. These IDs can be obtained by making a separate call to options/targeting_language_options.

Sample

"technographic": {
        "language": {
                "op": "INTERSECTS",
                "val": "en,de"
        }
}
OS

Attributes and parameters

AttributeParameter
osop: The following are accepted values for this attribute:
•    INTERSECTS: Contains any of
•    NOT INTERSECTS: Contains none of
val: A comma-separated list of IDs. These IDs can be obtained by making a separate call to options/os_options.

Sample

"technographic": {
        "os": {
                "op": "INTERSECTS",
                "val": "21,42"
        }
}
Screen Resolution

Attributes and parameters

AttributeParameter
screen_resolutionop: The following are accepted values for this attribute:
   • INTERSECTS: Contains any of
   • NOT INTERSECTS: Contains none of
val: A comma-separated list of IDs. These IDs can be obtained by making a separate call to options/screen_resolution_options.

Sample

"technographic": {
        "screen_resolution": {
                "op": "NOT INTERSECTS",
                "val": "1,11,7"
        }
}
User Agent

Attributes and parameters

AttributeParameter
user_agentop: The following are accepted values for this attribute:
   • AND: Both parameters must be true.
   • OR: One or the other parameter must be true.

val: An array of objects with the following keys:
   • op: List of accepted values for this key:
      • ==: Equals
      • !=: Does not equal
      • =?: Contains
      • NOT =?: Does not contain
      • =^: Begins with
      • NOT =^: Does not begin with
      • =$: Ends with
      • NOT =$: Does not end with
   • val: user-defined string, such as "my_string".

Sample

"technographic": {
        "user_agent": {
                "op": "AND",
                "val": [{
                        "op": "==",
                        "val": "123"
                }]
        }
}
Page Position

Attributes and parameters

AttributeParameter
page_positionop: The following are accepted values for this attribute:
   • `` (empty string): All
   • ==: Only above the fold
   • !=: Exclude above the fold
val: null if operator (op) is blank, ATF for other op values.

Feature flag restrictions

Can only be changed if feature.page_position is set.

NOTE

This option is only enabled for Exchange/Network line items.

Sample

"technographic": {
        "page_position": {
                "op": "",
                "val": null
        }
}
Cookies

Attributes and parameters

AttributeParameter
cookiesop: The following are accepted values for this attribute:
   • ==: Accepted
   • !=: Not accepted
val: 1

Sample

"technographic": {
        "cookies": {
                "val": 1
                "op": "=="
        }
}
Device

Attributes and parameters

AttributeParameter
deviceop: The following are accepted values for this attribute:
   • INTERSECTS: Contains any of
   • NOT INTERSECTS: Contains none of
val: A comma-separated list of IDs. These IDs can be obtained by making a separate call to options/device_options.

Sample

"technographic": {
        "device": {
                "op": "INTERSECTS",
                "val": "21"
        }
}
HTTPS

Attributes and parameters

AttributeParameter
httpsop: The following are accepted values for this attribute:
   • ==: Served through HTTPS
   • !=: Not served through HTTPS
val: 1

Sample

"technographic": {
        "https": {
                "val": 1,
                "op": "=="
        }
}

Custom

Use the custom dimension to target your own custom targeting options.

Custom

Attributes and parameters

AttributeParameter
customop: The following are a list of accepted values for this attribute:
    • AND: Both parameters must be true.
    • OR: One or the other parameter must be true.

val: An array of objects with the following keys:
   • attr: attribute defined by the user
   • val: value defined by the user
   • op: Accepts the following values:

      String
      • ==: equals
      • !=: does not equal
      • =?: contains
      • NOT =?: does not contain
      • =^: begins with
      • NOT =^: does not begin with
      • =$: ends with
      • NOT =$: does not end with

      Numeric
      • <: less than
      • >=: less than or equal to
      • >: greater than
      • <=: greater than or equal to

      Date
      • BEFORE: before
      • AFTER: after

      List
      • INTERSECTS: contains any of
      • INVERSE IN: contains all of
      • EQ: contains only
      • NOT INTERSECTS: contains none of

Sample

"custom": {
        "op": "OR",
        "val": [{
                "attr": "a",
                "op": "==",
                "val": "123"
        }, {
                "attr": "b",
                "op": "==",
                "val": "234"
        }, {
                "attr": "b",
                "op": "EQ",
                "val": "1,2,3"
        }]
}