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 newtargeting-expressionsendpoint. 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 - Unknown1 - First Price2 - 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 9 months ago