GuidesAPI ReferenceChangelogBeeswax.com

Migration Notes from 0.5 API

While the Buzz 0.5 and 2.0 APIs co-exist, your individual account must be set to work with one or the other APIs with regard to targeting. If you are not sure whether your account is ready to work with the new `targeting-expressions` resources please contact your account manager.

Targeting is at the heart of any bidding system. In Buzz, every Line Item must be associated with a set of targeting parameters that determines which ads are eligible to serve on which auctions. This process of _matching_ yields a binary result: either the Line Item is eligible or it is not eligible. This is separate from the process of determining the amount to bid on an auction, which may be accomplished using a wide variety of technology and techniques.

## Targeting Modules and Keys

Using the Buzz API you may create complex and powerful **Targeting Expressions** that use boolean relationships to determine whether to match a given auction. Targeting Expressions are built around a framework of targeting _modules_ and targeting _keys_ within those modules (see: [List of Targeting Modules and Keys](🔗)).

A _targeting module_ is a grouping for related keys that may be used for targeting. For example, the `geo` module groups fields relating to geography. Within the `geo` module are multiple _targeting keys_ such as `cities`, `regions`, `zip_code_lists`, etc. Targeting modules are useful for organizing related fields, but also they play a role in generating boolean expressions. The table below summarizes the how different combinations of targeting modules and keys are evaluated.

## How Targeting Expressions are Evaluated

Scope of Targeting ValuesBehaviorPseudo-code Example
Within a single targeting keyValues are always ORed together (outside of segment targeting, below).`country = (UK OR US OR CA)`
Different targeting keys within a single targeting moduleValues are ORed together within a targeting key. Values can then either be ANDed or ORed across targeting keys within the same module.`country = (US OR CA) AND region = Detroit` OR `country = (US OR CA) OR region = London`
Across targeting keys across modulesValues are ORed together within a targeting key, then ANDed across keys in different modules. You cannot OR across modules.`country = (US OR CA) AND domain = cnn.com`
Segment targetingSegment targeting may optionally use fully free-form boolean expressions.`(Segment-A AND Segment-B) AND NOT (Segment-C or Segment-D)`

## Exploring Targeting Modules and Keys

Migration Notes from 0.5 API

  • Targeting Modules and Keys are largely unchanged between the Buzz 0.5 and Buzz 2.0 APIs, but some Keys have moved into different Modules.

  • The Buzz 0.5 `/targeting` resource for discovering keys with a `GET` request has been replaced by `/ref/targeting-keys`.

  • The Buzz 0.5 `POST` to `/targeting` for testing targeting expressions is not supported in 2.0.

A list of targeting modules and keys may be found at: [List of Targeting Modules and Keys](🔗).

To use the API to explore targeting keys and retrieve other metadata use the [/ref/targeting-keys](🔗) resource as shown below:


This resource will return useful metadata about the targeting key, including the available `comparators` and the resource to query for value values. An example is shown below: 

## Targeting Expressions
To create or edit targeting for a Line Item you use the [/targeting-expressions](🔗) resource. This replaces the `targeting_template` endpoint from the Buzz 0.5 API and should be both more powerful and easier to use.
The syntax of a `targeting-expression` is a set of expressions organized by targeting module and targeting key. Each expression includes two layers of "predicates" which determine the and/or logic both between targeting keys and within targeting keys.
PredicateBehavior
`all`All targeting within the expression must be true to match.
`any`If any targeting within the expression is true, match.
`none`All targeting **within** the expression must NOT be true to match
The first predicate determines how to evaluate targeting keys within a targeting module. As described above, the default behavior is to "AND" these keys, in which case the `all` predicate is used. But you may also use `any` between keys in order to change the evaluation logic to "OR".
Within a targeting key's predicate the expression then contains a comparator and a value. For example, the JSON snippet `"comparator":"equals", "value":"foo"` means "match if the value is `foo`". Not all comparators are supported for all targeting keys -- you can see which ones in the response to the `/ref/targeting-keys` endpoint described above.
ComparatorBehavior
`equals`Value must be an exact match to the value field.
`in_range`Value must be between the range of values, where the value field are expressed as a list like `[1,100]`.
`boolean_expression`Evaluate the boolean expression contained in the value field.
Below are some truncated snippet examples of expressions:

## Segment Recency
When evaluating a Targeting Expression that contains the `segment` targeting key, you may also optionally specify the time range in which the user must have been placed within the segment in order to match targeting by including the `recency` object. This can be useful, for example, if you wish to show different ads to users who recently visited a website, versus those who may have visited the site several days ago.
The `recency` object includes the `start` and `end` fields. Validation is as follows:
  • Either must be present or the `recency` object must be set to `null`
  • Values must be greater than zero
  • Values must be less than or equal to 129,600 (e.g. 90 days)
  • `start` must be less than `end` when both are present
Below is an example snippet of a Targeting Expression specifying that users within the segment must be between one hour and one day old.

## Associating a Targeting Expression to a Line Item
Migration Notes from 0.5 API
  • Buzz 0.5 uses a different object, the `targeting_template`, to define targeting. Once your account is enabled for `targeting-expressions` the `targeting_template_id` field in the Line Item object will no longer be used and will not be editable.
  • In Buzz 0.5 a `targeting_template` could be associated with multiple Line Items (API only, not supported in the UI). In the 2.0 API a `targeting-expression` may only be associated with one Line Item.
  • The Buzz 0.5 concept of `strategy` is not included in 2.0. The strategy object limits the available targeting keys based on the `line_item_type`. For example the targeting keys within the `video` targeting module could only be used on video line items. In Buzz 2.0 this restriction is removed and simplified, though you should be cautious that video-specific targeting may not make logical sense when used on a non-video Line Item.
In order for a Line Item to be made active it must be associated with a `targeting-expression`. To associate, get the `id`  of the `targeting-expression`, then `PUT` that ID on the Line Item resource as shown below (Line Items are still only supported only in the 0.5 API):

## Programmatic Guaranteed
Programmatic Guaranteed deals are arrangements between publishers and buyers where the expectation is that the buyer will bid and win virtually all available auctions under a specific deal. As a result of this business arrangement, the bidder cannot use many of the targeting, budget and pacing features since they would cause variations in bidding.
A Line Item can be setup as Programmatic Guaranteed by setting the `guaranteed` field to `true`. When set, the `targeting-expression` associated with that Line Item must also have the `guaranteed`  field set to `true` and targeting will be limited to only include the `deal-id` targeting parameter. Below is a sample snippet of an expression for a guaranteed Line Item:

## Example Targeting Expression
Complete example of  of a `targeting-expression`: