Beeswax

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.

Updated 8 months ago

List of Targeting Modules and Keys


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.