This is the 0.5 version of Beeswax’s API documentation. For the updated 2.0 version, you can navigate by clicking the dropdown located near the top left of this site.

For more information about the ongoing migration from 0.5 to 2.0, please visit the 2.0 version.
Guides
Beeswax HomeGuidesAPI ReferenceChangelog

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.

Updated about 1 year ago