List of Targeting Modules and Keys

❗️

Upgrade Notice

The Targeting API (targeting_template) has been upgraded as part of the Buzz 2.0 API. We strongly recommend you use the new targeting-expressions endpoint. Read more about targeting using the new API.

This document summarizes the existing targeting modules and keys.

Module

Verb

Keys

Example

Notes

ad_size

None, see note

ad_size

"ad_size":["160x600","600x160"]

ad_size is not available as a targeting criteria, but may be used in a bid_modifier expression. Sizes should be passed as <width>x<height>

content

I,E

content_category

"content_category":["IAB1","IAB2"]

IAB categories from OpenRTB

content_rating

"content_rating":[1,2]

Content rating types according to OpenRTB 6.18

coppa

"coppa":[true]

Whether the request falls under the COPPA regulations, passed as a boolean

language

“language”:[”am”,”ar”]

Language of site on which ad is shown. Lookup based on ISO 639-1.

domain

I,E

domain_list

"domain_list":[1,2]

Domain lists defined using custom_list object. Targeting domain_list[-1] matches any request with a blank or no domain

geo

I,E

country

"country":["USA","GBR"]

Validated against ISO 3166-1 alpha-3

city

"city":["12345","12346"]

IDs based on MaxMind database which is based on Geonames. The IDs can be found in the Cities view.

lat_long_list

"lat_long_list":[123]

List of latitude and longitudes using the custom_list object. A value of -1 will match when no lat/long is available.

lat_long_present

"lat_long_present":[true]

Whether the user's latitude and longitude are present on the request. Note, this does not actually target the user's location, just filters impressions where the data is present.

location_type

"location_type":[1]

The type of location data available, as specified in OpenRTB 2.5. 1 - GPS, 2 - IP, 3 - Registration

region

"region":["USA/NJ","USA/NM","GBR/DEV"]

Region in format <country_code>/<region_code> where country_code is ISO 3166-1 alpha-3 and regions are based on ISO_3166-2.

metro

"metro":[500,501]

Validated against DMA table, based on Google's metro codes, which are similar to Nielsen DMAs

zip

"zip":["12345","23456"]

5 or more characters

zip_code_list

"zip_code_list":[115,116]

List of zip codes to include or exclude

inventory

I,E

auction_type

“auction_type”:[1]

The type of auction as declared by the inventory source:
-1 - Unknown
1 - First Price
2 - Second Price

ad_position

“ad_position”:[1,2,3]

Publisher declared ad position such as "above the fold". Codes are in the ad_position view. Note, these values are not validated and do not guarantee viewability.

deal_id

"deal_id":["adx/foo_bar"]

Deal ID in the format <inventory_source>/<deal_id> for example if the deal_id is foo_bar and it is from inventory_source adx, the deal_id is adx/foo_bar. Note, there is no validation currently that this is a valid deal.

deal_id_list

"deal_id_list":[123]

List of deal IDs to include or exclude

environment_type

"environment_type":[1]

0=web, 1=in-app

inventory_source

“inventory_source”:[1,2]

List of sources, eg. 1=”Rubicon”

interstitial

“interstitial”:[true]

Whether the impression is an interstitial, passed as a boolean

rewarded

“rewarded”:[true]

Whether the end user is incentivized to interact with the ad. Typically this would be for rewarded video ads in mobile environments.

site

“site”:[“adx/1”,”lr/2”]

Site names in form <inventory_source>/<site_id>. IDs can be found in post-campaign reporting.

site_list

“site_list”:[123,124]

List of sites to include or exclude

top_frame

“top_frame”:[true]

Whether the ad is being served in the top browser frame (true) or in an iframe (false).

placement

“placement”:[”rb/1”,”adx/2”]

ID in the form <inventory_source>/<placement_name>. Placement name is not validated but can be found in post-campaign reporting. Buzz includes an incomplete list of Placements in the "placements" view.

placement_list

“placement_list”:[123,124]

List of placements to include or exclude

publisher_id

“publisher_id”:[”rb/1”,”adx/2”]

ID in the form <inventory_source>/<publisher_id>. Publisher ID is not validated but can be found in post-campaign reporting.

publisher_id_list

“publisher_id_list”:[123]

List of publisher IDs to include or exclude

video_api

“video_api”:[1]

List of API frameworks defined in OpenRTB 5.6. e.g. VPAID, MRAID, etc.

ip_address

I,E

ip_address_list

"ip_address_list":["3”]

Ip_address_list defined using Custom List object.

IR, ER

ip_address

"ip_address":[["1.1.1.1",”2.2.2.2”],["3.3.3.3",”4.4.4.4”]]

Validates a range of IP addresses

multi_list

I, E

multi_list

"multi_list":[123,234,567]

Allows ORing of many kinds of lists, for example either a domain_list or an app_bundle_list.

mobile_app

I,E

app_bundle_list

"app_bundle_list":[1,2]

AppBundle lists defined using Custom Lists object. Targeting app_list [-1] matches any request with a blank or no app bundle

app_id_list

"app_id_list":[1,2]

AppID lists defined using Custom Lists object. Targeting app_list [-1] matches any request with a blank or no app ID

app_name

“app_name”:[”facebook”]

Strings, no validation

platform

I,E

bandwidth

"bandwidth":[1,2]

Validates against connectiontype field defined in OpenRTB 5.18. Note, "WIFI" is a valid value.

browser

“browser”:[”Firefox”,"IE"]

Browser name as a string.

browser_version

“browser_version”:["Firefox/1”,"Firefox/2"]

Browser version to target, most typically to exclude. Most commonly, you will want to include a browser and exclude one or more browser_versions. If you exclude a browser, but include browser_versions, nothing will serve.

carrier

"carrier":["Verizon","AT&T"]

List of mobile carriers by name.

js_support

"js_support":[true]

Whether the device supports JavaScript, passed as a boolean.

device_type

“device_type”:[1,2]

Device type id as described in OpenRTB 2.5 section 5.21.

device_make

"device_make":["Apple","Samsung"]

Device make as a string.

device_model

"device_model":["iPhone/6s","iPhone/6c"]

Device model as a string, including version number. Note OpenRTB keeps the model and the version as separate fields.

device_screen_size

"device_screen_size":["S","M"]

Device screen size. Valid values are "S", "M", "L", "XL", and "NA"

os

“os”:["Windows", "OSX"]

Specific OS versions identified by strings such as Windows

os_version

"os_version":["Windows/7","Windows/Vista"]

Specific version of OSes such as Windows 7 or OSX 10.8 in the format <OS>/<Version>

segment

I,E,

segment

"segment":["FOO-1", "FOO-2"]

Segments keys defined using segment object.

user_id

"user_id":[true]

time

IR, ER

time_of_week

"time_of_week"=[["0","5000”],[”5600","1000”]]

Count in minutes from Sunday at midnight (0) to Saturday at 11:59 (10079) in range format [<start>,<end>]. Calculation is against EST. See user_time_of_week below for relative time.

IR, ER

user_time_of_week

"user_time_of_week"=[["0","5000”],[”5600","1000”]]

Count in minutes from Sunday at midnight (0) to Saturday at 11:59 (10079) in range format [<start>,<end>]. Calculation is against the user's timezone at the time the ad is served.

Note, when using user_time_of_week with pacing, the user_timezones field at the Line Item-level must be utilized to assure paced delivery.

IR

line_item_start_end

"line_item_start_end"=[[ 1436891253, 1439510400]]

This targeting key is set internally by the system. The line item start and end times are converted into seconds since epoch and stored in the range format [<start>, <end>].

video

I,E

companion_required

"companion_required":[true]

playback_method

“playback_method”:[1,2]

Codes from 1-4 based on OpenRTB 6.6. Example 1= Auto-play with sound on.

player_size

“player_size”:[“S”,"M",”L”]

Small, medium, or large.

start_delay

“start_delay”:[0,-1]

Codes from -2 to 0 based on OpenRTB 6.9. Buzz does not support an exact offset in seconds.

video_placement_type

"video_placement_type":[1]

Whether the video is in-banner (0), in-stream (1), in-article (2), in-feed (3), or interstitial/slider/floating (4)

Verbs

Different targeting modules can support different "verbs" in targeting. The table below describes the verbs:

Abbreviation

Verb

Usage

Example

I

include

"include":[{<key>:[<value>,<value>]}}

{"ip_address":[{"include":{"ip_address":["0.0.0.0"]}}]}

E

exclude

"exclude":[{<key>:[<value>,<value>]}}

{"ip_address":[{"exclude":{"ip_address":["0.0.0.0"]}}]}

IR

include_range

"include_range":[{<key>:[[<start>,<end>],[<start>,<end>]]}}

{"ip_address":[{"include_range":{"ip_address":[["1.1.1.1","2.2.2.2"],["1.1.1.1","2.2.2.2"]]}}]}

ER

exclude_range

"exclude_range":[{<key>:[[<start>,<end>],[<start>,<end>]]}}

{"ip_address":[{"exclude_range":{"ip_address":[["1.1.1.1","2.2.2.2"],["1.1.1.1","2.2.2.2"]]}}]}

R

require

"require":[{<key>:[<value>,<value>]}}

{"segment":[{"require":{"segment":["foo-1"]}}]}

The Segment module also allows two special verbs. First, boolean verb with the syntax:

{"segment":[{"boolean":"segment=FOO-1 OR (segment=FOO-2 AND segment=FOO-3)"}]}

And second, the require verb, which essentially acts like an AND and should be used in conjunction with an include verb. For example, if you wish to target a set of segments in an OR relationship you would use an include verb. But if you also wanted to assure that you matched a quality scoring segment, you would require that segment.