"docs.beeswax.com" has a new address: "api-docs.freewheel.tv/beeswax." Please update your bookmarks accordingly.

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.

ModuleVerbKeysExampleNotes
ad_sizeNone, see notead_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>
contentI,Econtent_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.
domainI,Edomain_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
geoI,Ecountry"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
inventoryI,Eauction_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_addressI,Eip_address_list"ip_address_list":["3”]Ip_address_list defined using Custom List object.
IR, ERip_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_listI, Emulti_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_appI,Eapp_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
platformI,Ebandwidth"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>
segmentI,E,segment"segment":["FOO-1", "FOO-2"]Segments keys defined using segment object.
user_id"user_id":[true]
timeIR, ERtime_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, ERuser_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.
IRline_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>].
videoI,Ecompanion_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:

AbbreviationVerbUsageExample
Iinclude"include":[{<key>:[<value>,<value>]}}{"ip_address":[{"include":{"ip_address":["0.0.0.0"]}}]}
Eexclude"exclude":[{<key>:[<value>,<value>]}} {"ip_address":[{"exclude":{"ip_address":["0.0.0.0"]}}]}
IRinclude_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"]]}}]}
ERexclude_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"]]}}]}
Rrequire"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.