Skip to end of metadata
Go to start of metadata

Bonsai Features

The AppNexus Programmable Bidder is currently in Alpha and available to a limited set of clients. For more information about this offering and potential use cases that may apply to your business, reach out to your AppNexus representative.

This page lists the Bonsai features that you can use to evaluate impressions as part of your custom model logic. For each feature, we explain the syntax and provide an example to demonstrate usage. 

The bids calculated by the model are always expressed in the currency set on the advertiser, even if you have specified a different currency for the line item or campaign.

Bids that are negative or zero (0) are not supported unless explicitly specified in the feature description. Do not use these expressions or unexpected results may occur. It is best to specify no_bid explicitly using Smart Leaves.

On This Page

Simple Features

Country

Evaluate impressions based on the user's country

Keywordcountry
OperatorAny except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Country ID or code, such as 233 or "US"

Use the Country Service to retrieve these IDs or codes.

Example

Region

Evaluate impressions based on the user's geographic region. 

Keywordregion
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Region ID or country/region code combination, such as  "US:NY".

Use the Region Service  to retrieve these IDs and codes. 

Example

City

Evaluate impressions based on the user's city. 

Keywordcity
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

City ID or country/region/city code combination, such as  "US:NY:New York"

Use the City Service to retrieve these IDs and codes. 

Example

DMA

Evaluate impressions based on the user's DMA (designated market area).

Keyworddma
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

DMA ID, such as 602 (for Chicago metro area). 

Use the City Service  to retrieve DMA IDs. 

Example

Postal Code

Evaluate impressions based on the user's postal code. Postal code is available only for some mobile impressions and impressions from external supply partners.

Keywordpostal_code
OperatorAny except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Postal code ID (an integer) or country/postal code combination (a string such as "CA:J0K 1B0" or "US:10010"). Includes US zip codes.

Use the Postal Code Service (documented in the Profile Service) to retrieve postal code IDs.

Example

Size

Evaluate impressions based on placement size. Please note that in case promo_sizes are passed in the ad call, the evaluation will be performed using the primary size only.

Keywordsize
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

String representing placement dimensions, formatted as  "WIDTHxHEIGHT".  

Example

Day of Week

Evaluate impressions based on specific days of the week.

Keyworduser_day
OperatorAny
Value

Day of the week. Possible values: 0  -  6, where 0 is Sunday and 6 is Saturday.   

Example

Hour of Day

Evaluate impressions based on specific hours of the day.

Keyworduser_hour
OperatorAny
Value

Hour of the day, in the user's timezone. Possible values:  0  -  23, where 0 is midnight and 23 is 11pm. 

Example

Operating System Family

Evaluate impressions based on the user's operating system.

Keyword os_family
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Operating System Family ID or name, such as  2  or  "Android".

Use the Operating System Family Service  to retrieve these IDs and names. 

Example

Operating System Version

Evaluate impressions based on the specific version of the user's operating system.

Keywordos_extended
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Operating System Extended ID, such as  81  for  "10.8 Mountain Lion".

Use the Operating System Extended Service  to retrieve these IDs. 

Operating system ID is listed as operating_system  in log-level data.

Example

Browser

Evaluate impressions based on the user's browser.

Keywordbrowser
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Browser ID or name, such as  8  or  "Chrome (all versions)".

Use the Browser Service  to retrieve these IDs and names. 

Example

Browser Language

Evaluate impressions based on the browser language.

Keywordlanguage
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Language ID. 

Use the Language Service to retrieve these IDs.   

Example

Gender

Evaluate impressions based on the user's gender. Note that gender is available only in cases where the publisher passes it in the ad call. For more information on ad calls, see Placement Tag Parameters (customer login required).

Keyworduser_gender
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Gender of the user.  Possible values: 

  • "female"
  • "male" 
  • "unknown"      
Example

Domain

Evaluate impressions based on domain.

Keyworddomain
OperatorAny except <, >, <=, >=, and range. To test for multiple values, use in.
Value

String representing a top-level domain name, such as "food.com" or "books".  

Example

IP Address

Evaluates impressions based on IP address.

Keywordip_address
Operatorin 
Value

String representing any valid IP address, including subnet notation.

For example, the range (192.168.0.1, 10.0.0.0/24) indicates IP addresses 192.168.0.1 and 10.0.0.0-10.0.0.255.

Example

Fold Position

Evaluate impressions based on specific placement positions relative to the fold of the page.

Currently, this feature cannot be use to evaluate fold positions for Facebook impressions.

Keywordposition
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Fold position. Possible values: 

  • 0 or "unknown" - Use these values to target placements where the fold position is unknown.
  • 1 or "above" - Use these values to target placements above the fold. 
  • 2 or "below" - Use these values to target placements below the fold. 
Example

Placement

Evaluate impressions based on specific placements.

Keywordplacement
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Placement ID.  

Placement ID is listed as  tag_id  in log-level data. 

Example

Placement Group

Evaluate impressions based on specific placements groups.

Keywordplacement_group
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Placement group ID. 

Placement group ID is listed as  site_id  in log-level data. 

Example

Publisher

Evaluate impressions based on specific publishers.

Keywordpublisher
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Publisher ID. 

Publisher ID is listed as publisher_id in log-level data. 

Example

Seller Member

Evaluate impressions based on specific seller members.

Keywordseller_member_id
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Member ID of the seller. 

Example

Supply Type

Evaluate impressions based on specific types of supply.

Keywordsupply_type
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Supply type ID or name. Possible values: 

  • 0 or "web" - Use either of these values to target standard web sites. 
  • 1  or "mobile_web" - Use either of these values to target web sites optimized for browsers on mobile tablets and phones.
  • 2  or "mobile_app" - Use either of these values to target apps installed on mobile tablets and phones.
  • 3 or "facebook_sidebar" - Deprecated. These values may appear in historical data, indicating Facebook Newsfeed and Right-Hand Side inventory.
Example

Device Type

Evaluate impressions based on specific types of physical devices.

Keyworddevice_type
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Device type name. Possible values:

  • "pc & other devices" - Use this value to target desktops and laptops.
  • "phone" - Use this value to target mobile phones. 
  • "tablet"- Use this value to target mobile tablets.
Example

Device Model

Evaluate impressions based on specific models of physical devices.

Keyworddevice_model
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Device model ID. 

 Use the Device Model Service to retrieve these IDs. 

Device model ID is listed as  device_id   in log-level data.

Example

Carrier

Evaluate impressions based on specific mobile carriers.

Keywordcarrier
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Mobile carrier ID or name, such as  14  or  "Verizon" .

Use the Carrier Service to retrieve these IDs and names.

Example

Mobile App

 Evaluate impressions based on specific mobile apps.

Keywordmobile_app
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Mobile app ID or names.

Use Mobile App Service to retrieve these IDs or names.

Example

Mobile App Instance

 Evaluate impressions based on specific mobile app installations.

Keywordmobile_app_instance
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Mobile app instance ID.

Use Mobile App Instance Service to retrieve these IDs.

Example

Mobile App Bundle

Evaluate impressions based on specific mobile app bundles.

Keywordmobile_app_bundle
Operator Any except <, >, <=, >=, and range. To test for multiple values, use in.
Value

Mobile app bundle ID.

Example

Cookie Age

Evaluate impressions based on how long, in minutes, the user has had an AppNexus cookie.

Keywordcookie_age
OperatorAny
Value

Positive integer representing the number of minutes that the user has had an AppNexus cookie.

This value can be absent, which indicates that the user does not have an AppNexus cookie.

Example

Predicted IAB Viewability Rate

(Previously known as "Estimated IAB Viewability Rate".) Evaluate web display impressions by how likely they are to be measured as viewable by the IAB standard, as determined by AppNexus optimization (customer login required).

Keywordpredicted_iab_view_rate
Alias (deprecated)
estimated_iab_viewthrough_rate
Operator
Any   
ValueDecimal number between 0 and 1, representing a percentage. 
Example

Predicted IAB Viewability Rate Over Total

Evaluate web display impressions by how likely they are to be measured as viewable, over the total number of impressions (viewed / total impressions), by the IAB standard, as determined by AppNexus optimization (customer login required).

Keywordpredicted_iab_view_rate_over_total
OperatorAny   
ValueDecimal number between 0 and 1, representing a percentage. 
Example

Predicted IAB Video Viewability Rate

Evaluate web video impressions by how likely they are to be measured as viewable by the IAB standard, as determined by AppNexus optimization (customer login required).

Keywordpredicted_iab_video_view_rate
OperatorAny   
ValueDecimal number between 0 and 1, representing a percentage. 
Example

Predicted IAB Video Viewability Rate Over Total

Evaluate web video impressions by how likely they are to be measured as viewable, over the total number of impressions (viewed / total impressions), by the IAB standard, as determined by AppNexus optimization (customer login required).

 Keywordpredicted_iab_video_view_rate_over_total
OperatorAny   
ValueDecimal number between 0 and 1, representing a percentage. 
Example

Predicted Video Viewability Rate (100% View, 50% Duration, Sound On)

Evaluate web video impressions by how likely they are to be measured as viewable (viewed/measured impressions) where a "view" is defined as an ad which is 100% visible and has played for at least 50% of its duration, with the sound on. Likelihood is determined by AppNexus optimization (customer login required).

Keywordpredicted_100pv50pd_video_view_rate
OperatorAny   
ValueDecimal number between 0 and 1, representing a percentage. 
Example

Predicted Video Viewability Rate Over Total (100% View, 50% Duration, Sound On)

Evaluate web video impressions by how likely they are to be measured as viewable, over total number of impressions (viewed/total impressions), where a "view" is defined as an ad which is 100% visible and has played for at least 50% of its duration, with the sound on. Likelihood is determined by AppNexus optimization (customer login required).

Keywordpredicted_100pv50pd_video_view_rate_over_total
OperatorAny   
ValueDecimal number between 0 and 1, representing a percentage.
Example

Predicted Video Completion Rate

This feature is not yet available.

Evaluate web video impressions by how likely they are to be completed, as determined by AppNexus optimization (customer login required).

Keyword

predicted_video_completion_rate

Alias (Deprecated)
estimated_video_completion_rate
OperatorAny   
ValueDecimal number between 0 and 1, representing a percentage. 0 represents non-video inventory.
Example

AppNexus Intended Audience

Evaluates impressions based on their intended audience as determined by the AppNexus platform audit. For more information, see Inventory Standards and Auditing (customer login required) and Profile Service.

Keywordappnexus_intended_audience
OperatorAny except <, >, <=, >=, and range. To test for multiple values, use in.
Value"general","children", "young_adult", or "mature"
Example

Seller Intended Audience

Evaluates impressions based on their intended audience as determined by self-audit. For more information, see Inventory Self-Classification (customer login required) and Profile Service.

Keywordseller_intended_audience
OperatorAny except <, >, <=, >=, and range. To test for multiple values, use in.  
Value"general","children", "young_adult", or "mature"
Example

 

 

AppNexus Audited Status

Evaluates whether inventory has been audited by AppNexus.

Keywordappnexus_audited
OperatorAny except <, >, <=, >=, and range.  
ValueTrue or False
Example

Self-Audited Status

Evaluates whether inventory has been audited by the publisher.

Keywordself_audited
OperatorAny except <, >, <=, >=, and range.
Value True or False
Example

Spend Protection

Evaluates whether inventory meets AppNexus Spend Protection standards. Available only for buyers who participate in AppNexus Spend Protection (customer login required).

Keywordspend_protection
OperatorAny except <, >, <=, >=, and range.  
Value True or False.
Example

User Group

Evaluates whether the user belongs to a randomly-assigned group. Each AppNexus user has a persistent user group from 0 to 999. You may want to use the user group to test various strategies in parallel and compare their performance. Different tests should partition the thousand user groups differently; otherwise, concurrent tests will interact with each other and it will be difficult to interpret results.  For more information, see Test and Control Targeting (customer login required).

Keyworduser_group
OperatorAny  
Value

Integer between 0 and 999.

Example

Compound Features

The simple features above let you evaluate a single aspect of the impression (country, cookie age, mobile app, etc.). The compound Segment and Frequency/Recency features are more nuanced; they let you evaluate multiple attributes of these features, such as the age of a segment or the segment value.

Segment

Segment Presence/Absence

Evaluate impressions based on the presence of the user in a first-party or third-party segment. 

Keyword

segment[ID]

where ID is the segment ID. Use Segment Service to retrieve segment IDs.

Attribute

None

Operator

None for presence, not for absence

ValueNone
Example

Segment Age

Evaluate impressions based on the minutes since the user was added to a first-party or third-party segment.

If the user is not in the segment, this feature evaluates to False.

Keyword

segment[ID]

where ID is the segment ID. Use Segment Service to retrieve segment IDs.

Attribute

.age

Operator< , > , or =
ValuePositive integer representing the minutes since the user was added to the segment.
Example

Segment Value

Evaluate impressions based on a user-defined value.  The value may be passed in a number of ways, for example, through the Batch Segment Service or a first-party or third-party segment query string. For more information on passing values through segment query strings, see Segment Pixels Advanced (customer login required).

If the user is not in the segment, this feature evaluates to False.

Keyword

segment[ID]

where ID is the segment ID. Use the Segment Service to retrieve segment IDs.

Attribute

.value

Operator

< , > , or =

ValueNon-zero, positive integer representing the user-defined value.
Example

Frequency/Recency

Frequency Presence/Absence

Evaluate whether or not frequency data is available for the user. This can be determined for all ads under an advertiser, line item, or campaign.

Keyword

frequency

Attribute

OBJECT[ID].

where OBJECT is advertiser, line_item, or campaign, and ID is the object ID. Use the Advertiser Service, Line Item Service, or Campaign Service to retrieve IDs.

Operator< , > , or =
Value

0 indicates that the user has never seen an impression for this object; a positive integer indicates that frequency information is available.

Unlike recency, frequency data is never null. If a user has never seen an impression for this object, frequency is 0.

Example

Lifetime Frequency

Evaluate impressions based on the number of ads seen by a user over the lifetime of an advertiser, line item, or campaign.  

Keyword

lifetime_frequency

Attribute

OBJECT[ID].

where OBJECT is advertiser, line_item, campaign, or creative, and ID is the object ID. Use the Advertiser Service, Line Item Service, or Campaign Service to retrieve IDs.

Operator><, or =
ValuePositive integer representing the number of ads seen by a user over the lifetime of the object. 0 indicates no frequency information is available (the user has never seen this object).
Example

Daily Frequency

Evaluate impressions based on the number of ads seen by a user on the current day. This can be determined for an advertiser, line item, or campaign.  

Keyword

day_frequency

Attribute

OBJECT[ID].

where OBJECT is advertiser, line_item, or campaign, and ID is the object ID. Use the Advertiser Service, Line Item Service, or Campaign Service  to retrieve IDs.

Operator><, or =
ValuePositive integer representing the number of ads seen by a user on the current day. 0 indicates no frequency information is available (the user has not seen this object on the current day).
Example

Recency Presence/Absence and Data

Evaluates whether recency data is available for a user, and, if available, the number of minutes since a user has seen an ad. This can be determined for a user for all ads under an advertiser, line item, or campaign.

Keyword

recency

Attribute

OBJECT[ID].

where OBJECT is advertiser, line_item, or campaign, and ID is the object ID. Use the Advertiser Service, Line Item Service, or Campaign Service to retrieve IDs.

Operatornot, ><, or =
ValueA positive integer indicating the number of minutes since a user has seen an impression, rounded down. 59 seconds will evaluate to 0, 61 seconds will evaluate to 1. 0 means the impression was seen very recently. Null means no recency data is available (the user has not seen this impression before).
Example

 Examples of Compound Feature Syntax Using Multiple Attributes

Example of multiple segment attributes

Example of recency/frequency syntax with multiple attributes

Example of multiple compound attributes

Related Topics