--- title: "Formatting Targeting Rules in the Booking and Avails APIs" slug: "formatting-targeting-rules" tags: ["API"] status: "update" updated: 2025-11-21T20:10:56Z published: 2025-11-21T20:10:56Z canonical: "help.tritondigital.com/formatting-targeting-rules" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.tritondigital.com/llms.txt > Use this file to discover all available pages before exploring further. # Formatting Targeting Rules in the Booking and Avails APIs > [!NOTE] > 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](https://druid.apache.org/docs/latest/querying/filters.html). 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****."*) ```json Example: AND { "type":"and" "fields":[{},{}] } Example: OR { "type":"or" "fields":[{},{}] } ``` #### NOT The **not** criteria takes one criteria defined in the **field** dimension. (*Singular; no "****s****" in "****field****."*) ```json { "type":"not", "field":{} } ``` #### EQUALS Defines a criteria where the values must match. Letter case is ignored when values match. ("tomato" = "TomaTO"). > [!NOTE] > **Value** must be specified as a **String**, even if the value is numeric. ```json { "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. ```json { "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****."*) > [!NOTE] > **Values** must be specified as **Strings**, even if the values are numeric. ```json { "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. ```json # 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. ```json { "type": "spatial", "dimension": "coordinates", "bound": {    "type": "radius",    "coords": [45.5376917, -73.9279362],    "radius": 10 } } ``` **Note:** "coords" = [, ] ## 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:**** ![](https://cdn.document360.io/7124b381-0a94-401a-abbd-9df9c4ea5dff/Images/Documentation/image-1686817122495.png) ```actionscript { "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***): ```json { "_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](https://platformservices.streamtheworld.com/content-targeting/schemes/c.xml) | **Dimension** | **PossibleValue(s)** | **Supported Type(s)** | **Validator / Notes** | Flight | Ad Quality | Exclusivity | **Forecasting** | Deal | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | station | | equals, in | [https://tritonsecurity.tritondigital.com/v2/docs#operation/search-stations](https://tritonsecurity.tritondigital.com/v2/docs#operation/search-stations) (requires JWT Bearer token) | Yes | Yes | Yes | Yes | Yes | | episode-id-rss | | 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 | | bound | Basic [BOUND](/docs/formatting-targeting-rules#bound) validation. Evaluates against **pubDate** | Yes | No | No | Yes | Yes | | publish-date-age-days | | bound | Basic [BOUND](/docs/formatting-targeting-rules#bound) validation. Evaluates against **pubDate** | Yes | No | No | Yes | Yes | | content-tags | | 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**](https://tag-api.api.tritondigital.com/docs) Match should allow **AND** statements. | Yes | No | No | Yes | Yes | | contextual-tags | | 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](/user/docs/contextual-targeting). - For a list of existing tags, call this endpoint: `https://starship.api.tritondigital.com/api/tags/search` - [Endpoint documentation](https://starship.api.tritondigital.com/swagger-ui/index.html#/contextual%20tags/searchContextualTags). | Yes | No | No | Yes | No | | station-genre-shoutcast | | equals, in | Open API: [https://tritonsecurity.tritondigital.com/v2/docs#operation/get-genres](https://tritonsecurity.tritondigital.com/v2/docs#operation/get-genres) (requires JWT Bearer token) | Yes | No | No | Yes | No | | iab-v2-category | | equals, in | Open API: [https://refdata.tritondigital.com/docs#operation/iab-get-categories](https://refdata.tritondigital.com/docs#operation/iab-get-categories)(requires JWT Bearer token) | No | No | No | No | Yes | | content-language | | equals, in | Open API: [https://yield-op-api.tritondigital.com/doc/openapi#operation/getLanguages](https://yield-op-api.tritondigital.com/doc/openapi#operation/getLanguages)(requires JWT Bearer token) | No | No | No | No | Yes | | station-market | | equals, in | Open API: [https://tritonsecurity.tritondigital.com/v2/docs#operation/get-markets](https://tritonsecurity.tritondigital.com/v2/docs#operation/get-markets) (requires JWT Bearer token) | Yes | Yes | No | Yes | Yes | | station-group | | equals, in | Open API: [https://tritonsecurity.tritondigital.com/v2/docs#operation/get-groups](https://tritonsecurity.tritondigital.com/v2/docs#operation/get-groups) (requires JWT Bearer token) | Yes | Yes | No | Yes | Yes | | position-in-break | | equals, in | first, last Value "last" is only valid for podcast content type. | Yes | No | No | Yes | Yes | | delivery-method | | in | Possible values: "streaming", "progressive", "download" | No | No | No | No | Yes | | feed-type | | in | Possible values: "instream", "ondemand", "podcast" | No | No | No | No | Yes | | position | | in | Possible values: "preroll", "midroll", "postroll" | No | No | No | No | Yes | | reseller-contract | | 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](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 | | equals, in | [https://refdata.tritondigital.com/device/agents](https://refdata.tritondigital.com/device/agents) | Yes | No | No | Yes | Yes | | agent-family | | equals, in | [https://refdata.tritondigital.com/device/agent_families](https://refdata.tritondigital.com/device/agent_families) | Yes | No | No | Yes | Yes | | agent-device | | equals, in | [https://refdata.tritondigital.com/device/devices](https://refdata.tritondigital.com/device/devices) | Yes | No | No | Yes | Yes | | agent-device-family | | equals, in | [https://refdata.tritondigital.com/device/device_families](https://refdata.tritondigital.com/device/device_families) | Yes | No | No | Yes | Yes | | agent-os | | equals, in | [https://refdata.tritondigital.com/device/os](https://refdata.tritondigital.com/device/os) | Yes | No | No | Yes | Yes | | agent-platform | | equals, in | [https://refdata.tritondigital.com/device/platforms](https://refdata.tritondigital.com/device/platforms) | Yes | No | No | Yes | Yes | | addressable | | in | Possible values: "True", "False" | No | No | No | No | Yes | | omid-capable | 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 | | Yes | No | No | Yes | Yes | | gender | m, f, o | equals, in | | Yes | No | No | Yes | Yes | **Geography** | **Dimension** | **Possible Value(s)** | **Supported Type(s)** | **Validator / Notes** | Flight | Ad Quality | Exclusivity | Forecasting | Deal | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | in-market | | equals | true, false | Yes | No | No | Yes | Yes | | ip | | equals, in | A valid IPV4 IP | Yes | No | No | No | Yes | | country | | equals, in | [https://refdata.tritondigital.com/docs#operation/geov2-get-countries](https://refdata.tritondigital.com/docs#operation/geov2-get-countries) | Yes | No | No | Yes | Yes | | region-iso | | equals, in | [https://refdata.tritondigital.com/docs#operation/geov2-get-country-regions](https://refdata.tritondigital.com/docs#operation/geov2-get-country-regions) | Yes | No | No | Yes (second-generation Forecasting API) | Yes | | city-geonames-id | | equals, in | [https://refdata.tritondigital.com/docs#operation/geov2-get-region-children](https://refdata.tritondigital.com/docs#operation/geov2-get-region-children) [https://refdata.tritondigital.com/docs#operation/geov2-get-subregion-cities](https://refdata.tritondigital.com/docs#operation/geov2-get-subregion-cities) | Yes | No | No | Yes (second-generation Forecasting API) | Yes | | dma | | equals, in | [https://refdata.tritondigital.com/docs#operation/geov2-get-country-regions](https://refdata.tritondigital.com/docs#operation/geov2-get-country-regions) | Yes | No | No | Yes | Yes | | all-msa | | equals, in | [https://refdata.tritondigital.com/docs#operation/geov2-get-country-regions](https://refdata.tritondigital.com/docs#operation/geov2-get-country-regions) | Yes | No | No | Yes | Yes | | subregion-iso | | equals, in | [https://refdata.tritondigital.com/docs#operation/geov2-get-region-children](https://refdata.tritondigital.com/docs#operation/geov2-get-region-children) | Yes | No | No | Yes (second-generation Forecasting API) | Yes | | longitude, latitude, radius | - | [spatial](/docs/formatting-targeting-rules#spatial%20%20%20%20%20%20) | **longitude**: -180 to 180 **latitude:** -90 to 90 **radius**: 1 to 20,000 KM Refer to the [spatial](/docs/formatting-targeting-rules#spatial%20%20%20%20%20%20) type for details. | Yes | No | No | Yes | Yes | | postalcode | | 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 | | 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 | | equals, in | *No validation* Match should allow **AND** statements. | Yes | No | No | Yes | Yes | | dist | | equals, in | String size must be between 1 and 256 characters (no empty values accepted). | Yes | No | No | Yes | Yes | | | | equals, in | Targeting Scheme: Attribute Group = "custom-parameter" [https://platformservices.streamtheworld.com/content-targeting/schemes/p.xml](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 | 1 = Monday | equals, in, bound | 1 to 7 | Yes | No | No | Yes | No | | hour | | equals, in, bound | 0 to 23 | Yes | No | No | Yes | No | ### 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](https://help.tritondigital.com/user/docs/formatting-targeting-rules#bound) validation. | Yes | No | No | Yes | Yes | | bs-arms | Basic [BOUND](https://help.tritondigital.com/user/docs/formatting-targeting-rules#bound) validation. | Yes | No | No | Yes | Yes | | bs-crime | Basic [BOUND](https://help.tritondigital.com/user/docs/formatting-targeting-rules#bound) validation. | Yes | No | No | Yes | Yes | | bs-dealth-injury | Basic [BOUND](https://help.tritondigital.com/user/docs/formatting-targeting-rules#bound) validation. | Yes | No | No | Yes | Yes | | bs-drugs | Basic [BOUND](https://help.tritondigital.com/user/docs/formatting-targeting-rules#bound) validation. | Yes | No | No | Yes | Yes | | bs-hate-speech | Basic [BOUND](https://help.tritondigital.com/user/docs/formatting-targeting-rules#bound) validation. | Yes | No | No | Yes | Yes | | bs-military-conflict | Basic [BOUND](https://help.tritondigital.com/user/docs/formatting-targeting-rules#bound) validation. | Yes | No | No | Yes | Yes | | bs-obscenity | Basic [BOUND](https://help.tritondigital.com/user/docs/formatting-targeting-rules#bound) validation. | Yes | No | No | Yes | Yes | | bs-online-piracy | Basic [BOUND](https://help.tritondigital.com/user/docs/formatting-targeting-rules#bound) validation. | Yes | No | No | Yes | Yes | | bs-spam-hurtful-sites | Basic [BOUND](https://help.tritondigital.com/user/docs/formatting-targeting-rules#bound) validation. | Yes | No | No | Yes | Yes | | bs-terrorism | Basic [BOUND](https://help.tritondigital.com/user/docs/formatting-targeting-rules#bound) validation. | Yes | No | No | Yes | Yes | | bs-tobacco | Basic [BOUND](https://help.tritondigital.com/user/docs/formatting-targeting-rules#bound) validation | Yes | No | No | Yes | Yes | When using **lower** and **upper** values, best practice is to always use **4** for upper. For example: ```json "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**](mailto:docs@tritondigital.com). (*This is a* ***NO REPLY*** *email address used only for documentation feedback. For customer support, go* [*here*](/user/docs/contact-support).)