Formatting Targeting Rules in the Booking and Avails APIs

This document is a companion to the Triton Digital Booking API ("BAPI") documentation.

The Triton Digital ad delivery engine does criteria matching using a language very similar to Druid's. The criteria is expressed in JSON format and supports multiple levels of operators.

The object supports the syntax described below.

AND/OR

The and/or criteria takes a list of criteria in an array, defined in the fields dimension. (Plural; note the "s" in "fields.")

Example: AND
{
"type":"and"
"fields":[{<criteria>},{<criteria>}]
}
 
Example: OR
{
"type":"or"
"fields":[{<criteria>},{<criteria>}]
}

NOT

The not criteria takes one criteria defined in the field dimension. (Singular; no "s" in "field.")

{
 "type":"not",
 "field":{<criteria>}
}

EQUALS

Defines a criteria where the values must match. Letter case is ignored when values match. ("tomato" = "TomaTO").

Value must be specified as a String, even if the value is numeric.

{
 "type":"equals",
 "dimension":"city-geonames-id",
 "value":"6077243"
}

ISDEFINED

Defines a criteria where a given dimension must have a value. Most probably used in conjunction with equals and bound criteria.

{
 "type":"isDefined",
 "dimension":"age"
}

IN

Defines a criteria where a list of values can match. At least one element from the list must match in order for the criteria to be true. (Plural; note the "s" in "values.")

Values must be specified as Strings, even if the values are numeric.

{
 "type":"in",
 "dimension":"dma",
 "values":["631", "734", "724"]
}

BOUND

Bound represents ranges of numbers. A bound must specify at least the lower or upper bound. A bound is inclusive.

Basic validation will be applied in order to ensure:

"lower" must be lower than "upper."
"lower" and "greater" must be positive integers.
At least one of "lower" or "greater" must be specified.

# 18+
{
 "type":"bound",
 "dimension":"age",
 "lower":18
} 

# 40-49
{
 "type":"bound",
 "dimension":"age",
 "lower":40,
 "upper":49
}

SPATIAL

Spatial represents a group of properties to describe a coordinate. Only the coordinate dimension currently supports this type. The radius is expressed in kilometers.

{
 "type": "spatial",
 "dimension": "coordinates",
 "bound": {
    "type": "radius",
    "coords": [45.5376917, -73.9279362],
    "radius": 10
 }
}

Note: "coords" = [<latitude>, <longitude>]

All-In-One Example

This format allows targeting to be applied using any and/or/not logic that is needed.

Below is an example that uses all notions described above:

Click to expand an example that uses all notions described above:

{
 "type": "or",
 "fields": [
   {
     "type": "and",
     "fields": [
       {
         "type": "and",
         "fields": [
           {
             "type": "or",
             "fields": [
               {
                 "type": "equals",
                 "dimension": "agent-device",
                 "value": "android-generic"
               }
             ]
           }
         ]
       },
       {
         "type": "and",
         "fields": [
           {
             "type": "or",
             "fields": [
               {
                 "type": "equals",
                 "dimension": "country",
                 "value": "US"
               }
             ]
           }
         ]
       },
       {
         "type": "and",
         "fields": [
           {
             "type": "or",
             "fields": [
               {
                 "type": "bound",
                 "dimension": "age",
                 "lower": 18
               }
             ]
           }
         ]
       }
     ]
   },
   {
     "type": "and",
     "fields": [
       {
         "type": "and",
         "fields": [
           {
             "type": "or",
             "fields": [
               {
                 "type": "equals",
                 "dimension": "dmp-segments",
                 "value": "71"
               }
             ]
           }
         ]
       }
     ]
   }
 ]
}

Targeting Dimensions

In order for the Tap UI to render the targeting rules properly, the following structure should be respected in the Booking API (not applicable to the Avails API):

{
 "_comment": "Ruleset Level: Multiple Rulesets can be created, each evaluated as OR",
 "type": "or",
 "fields": [
   {
     "_comment": "Within a Ruleset, each rule is evaluated as AND. Same dimension can be repeated but usually different dimensions are used at this level",
     "type": "and",
     "fields": [
       {
         "_comment": "Within a Rule, each value set to EXCLUDE is evaluated as AND."
         "type": "and",
         "fields": [
           {
             "_comment": "Within a Rule, each INCLUDE value is evaluated as OR. At this level we should always have the same logical dimension",
             "type": "or",
             "fields": [
               {"type": "equals", "dimension": "postalcode", "value": "90210"},
               {"type": "spatial", "dimension": "coordinates", "latitude": 40.5478735, "longitude": -74.3378837, "radius": 2}
               }
             ]
           }
         ]
       }
     ]
   }
 ]
}

Content Targeting

Scheme: https://platformservices.streamtheworld.com/content-targeting/schemes/c.xml

Dimension	PossibleValue(s)	Supported Type(s)	Validator / Notes	Flight	Ad Quality	Exclusivity	Forecasting	Deal
station	<id>	equals, in	https://tritonsecurity.tritondigital.com/v2/docs#operation/search-stations (requires JWT Bearer token)	Yes	Yes	Yes	Yes	Yes
episode-id-rss	<string>	equals, in	No validation This value is the result of the RSS ID, hashed with SHA256.	Yes	No	No	No	Yes
publish-date-epoch-days	<number>	bound	Basic BOUND validation. Evaluates against pubDate	Yes	No	No	Yes	Yes
publish-date-age-days	<number>	bound	Basic BOUND validation. Evaluates against pubDate	Yes	No	No	Yes	Yes
content-tags	<string>	equals, in	No validation All "tags" will be evaluated against this dimension. List of tags found in Scheme: break-tags episode-tags podcast-tags Station Tags: https://tag-api.api.tritondigital.com/docs Match should allow AND statements.	Yes	No	No	Yes	Yes
contextual-tags	<string>	equals, in	List size is > 0 and <= 2000. Provided UUIDs need to exist for the given publisher. Only applies to podcast delivery. Contextual Targeting must be enabled in the publisher's TAP setup. More information: Contextual Targeting. For a list of existing tags, call this endpoint: `https://starship.api.tritondigital.com/api/tags/search` Endpoint documentation.	Yes	No	No	Yes	No
station-genre-shoutcast	<string>	equals, in	Open API: https://tritonsecurity.tritondigital.com/v2/docs#operation/get-genres (requires JWT Bearer token)	Yes	No	No	Yes	No
iab-v2-category	<string>	equals, in	Open API: https://refdata.tritondigital.com/docs#operation/iab-get-categories(requires JWT Bearer token)	No	No	No	No	Yes
content-language	<string>	equals, in	Open API: https://yield-op-api.tritondigital.com/doc/openapi#operation/getLanguages(requires JWT Bearer token)	No	No	No	No	Yes
station-market	<string>	equals, in	Open API: https://tritonsecurity.tritondigital.com/v2/docs#operation/get-markets (requires JWT Bearer token)	Yes	Yes	No	Yes	Yes
station-group	<string>	equals, in	Open API: https://tritonsecurity.tritondigital.com/v2/docs#operation/get-groups (requires JWT Bearer token)	Yes	Yes	No	Yes	Yes
position-in-break	<string>	equals, in	first, last Value "last" is only valid for podcast delivery method.	Yes	No	No	Yes	Yes
delivery-method	<string>	in	Possible values: "streaming", "progressive", "download"	No	No	No	No	Yes
feed-type	<string>	in	Possible values: "instream", "ondemand", "podcast"	No	No	No	No	Yes
position	<string>	in	Possible values: "preroll", "midroll", "postroll"	No	No	No	No	Yes
reseller-contract	<string>	equals, in	Possible values: Existing, active contract IDs for which the organization is the reseller. Flight pricing model should not be CPS.	Yes	No	No	Yes	No

Listener Targeting

Scheme: https://platformservices.streamtheworld.com/content-targeting/schemes/p.xml

Player/Device

Dimension	Possible Value(s)	Supported Type(s)	Validator	Flight	Ad quality	Exclusivity	Forecasting	Deal
agent	<string>	equals, in	https://refdata.tritondigital.com/device/agents	Yes	No	No	Yes	Yes
agent-family	<string>	equals, in	https://refdata.tritondigital.com/device/agent_families	Yes	No	No	Yes	Yes
agent-device	<string>	equals, in	https://refdata.tritondigital.com/device/devices	Yes	No	No	Yes	Yes
agent-device-family	<string>	equals, in	https://refdata.tritondigital.com/device/device_families	Yes	No	No	Yes	Yes
agent-os	<string>	equals, in	https://refdata.tritondigital.com/device/os	Yes	No	No	Yes	Yes
agent-platform	<string>	equals, in	https://refdata.tritondigital.com/device/platforms	Yes	No	No	Yes	Yes
addressable	<string>	in	Possible values: "True", "False"	No	No	No	No	Yes
omid-capable	<number> 1 = Supported 0 = Not supported	in	Cannot be used if the flight delivery_method is "Live" or "Podcast".	Yes	No	No	No	Yes

Demography

Dimension	Possible Value(s)	Supported Type(s)	Validator	Flight	Ad Quality	Exclusivity	Forecasting	Deal
age	0-125	equals, in, bound	<code>	Yes	No	No	Yes	Yes
gender	m, f, o	equals, in	<code>	Yes	No	No	Yes	Yes

Geography

Dimension	Possible Value(s)	Supported Type(s)	Validator / Notes	Flight	Ad Quality	Exclusivity	Forecasting	Deal
in-market	<boolean>	equals	true, false	Yes	No	No	Yes	Yes
ip	<string>	equals, in	A valid IPV4 IP	Yes	No	No	No	Yes
country	<string>	equals, in	https://refdata.tritondigital.com/docs#operation/geov2-get-countries	Yes	No	No	Yes	Yes
region-iso	<string>	equals, in	https://refdata.tritondigital.com/docs#operation/geov2-get-country-regions	Yes	No	No	Yes (second-generation Forecasting API)	Yes
city-geonames-id	<string>	equals, in	https://refdata.tritondigital.com/docs#operation/geov2-get-region-children https://refdata.tritondigital.com/docs#operation/geov2-get-subregion-cities	Yes	No	No	Yes (second-generation Forecasting API)	Yes
dma	<string>	equals, in	https://refdata.tritondigital.com/docs#operation/geov2-get-country-regions	Yes	No	No	Yes	Yes
all-msa	<string>	equals, in	https://refdata.tritondigital.com/docs#operation/geov2-get-country-regions	Yes	No	No	Yes	Yes
subregion-iso	<string>	equals, in	https://refdata.tritondigital.com/docs#operation/geov2-get-region-children	Yes	No	No	Yes (second-generation Forecasting API)	Yes
longitude, latitude, radius	-	spatial	longitude: -180 to 180 latitude: -90 to 90 radius: 1 to 20,000 KM Refer to the spatial type for details.	Yes	No	No	Yes	Yes
postalcode	<string>	equals, in	No validation.	Yes	No	No	Yes	Yes

Other

Dimension	Possible Value(s)	Supported Type(s)	Validator	Flight	Ad Quality	Exclusivity	Forecasting	Deal
dmp-segments	<id>	equals, in	Segment ID must be an id found in one of the DMP providers enabled for the Organization's Publisher. Match should allow AND statements.	Yes	No	No	Yes	Yes
ttag	<string>	equals, in	No validation Match should allow AND statements.	Yes	No	No	Yes	Yes
dist	<string>	equals, in	String size must be between 1 and 256 characters (no empty values accepted).	Yes	No	No	Yes	Yes
<custom-parameter>	<string>	equals, in	Targeting Scheme: Attribute Group = "custom-parameter" https://platformservices.streamtheworld.com/content-targeting/schemes/p.xml The Custom Parameters are arbitrary dimensions defined in the Targeting Scheme upon request. In order to Target these dimensions, the attribute "group"="custom-parameter" needs to be provided alongside the dimension. E.g.: `<attr-group name="custom-parameter"><attr name="terminalid" label="Terminal ID" type="int" minValue="1" maxValue="1000000"/></attr-group>` To target the "terminalid" dimension, the RULE will look like: `{ "type": "equals", "dimension": "terminalid", "value": "1234", "group": "custom-parameter"}`	Yes	No	No	Yes for terminalid	Yes

Time Targeting (aka dayparts)

Dimension	Possible Value(s)	Supported Type(s)	Validator	Flight	Ad Quality	Exclusivity	Forecasting	Deal
day-of-week	<number> 1 = Monday	equals, in, bound	1 to 7	Yes	No	No	Yes	No
hour	<number>	equals, in, bound	0 to 23	Yes	No	No	Yes	No

Dimension

Possible Value(s)

Supported Type(s)

Validator

Flight

Ad Quality

Exclusivity

Forecasting

Deal

day-of-week

1 = Monday

equals, in, bound

1 to 7

Yes

hour

equals, in, bound

0 to 23

Yes

Brand Safety

Dimension	Possible Value(s)	Validator	Flight	Ad Quality	Exclusivity	Forecasting	Deal
bs-adult	Related = Value 1 Likely Related = Value 2 Likely Unrelated = Value 3 Unrelated = Value 4	Basic BOUND validation.	Yes	No	No	Yes	Yes
bs-arms		Basic BOUND validation.	Yes	No	No	Yes	Yes
bs-crime		Basic BOUND validation.	Yes	No	No	Yes	Yes
bs-dealth-injury		Basic BOUND validation.	Yes	No	No	Yes	Yes
bs-drugs		Basic BOUND validation.	Yes	No	No	Yes	Yes
bs-hate-speech		Basic BOUND validation.	Yes	No	No	Yes	Yes
bs-military-conflict		Basic BOUND validation.	Yes	No	No	Yes	Yes
bs-obscenity		Basic BOUND validation.	Yes	No	No	Yes	Yes
bs-online-piracy		Basic BOUND validation.	Yes	No	No	Yes	Yes
bs-spam-hurtful-sites		Basic BOUND validation.	Yes	No	No	Yes	Yes
bs-terrorism		Basic BOUND validation.	Yes	No	No	Yes	Yes
bs-tobacco		Basic BOUND validation	Yes	No	No	Yes	Yes

When using lower and upper values, best practice is to always use 4 for upper. For example:

 "fields":[
     {
        "dimension":"bs-arms",
        "lower":2,
        "upper":4,
        "type":"bound"
     },

  "fields":[
     {
        "dimension":"bs-drugs",
        "lower":4,
        "upper":4,
        "type":"bound"
     },

Feedback

Send any comments or corrections to docs@tritondigital.com. (This is a NO REPLY email address used only for documentation feedback. For customer support, go here.)