The Yield Optimization Distribution API V4 allows users to retrieve, create, and update the Distributions type of Yield Optimization rules.
Note
Yield Optimization Distribution API V4 functionality is only available for Marketplace users.
Use the Yield Optimization Distribution API V4 to:
- Create a new Yield Optimization Distribution rule
- Update an existing Yield Optimization Distribution rule, including its activation and deactivation
- Retrieve a list of Yield Optimization Distribution rules of your current network with basic attributes returned and query the list by id, name, application_scope, demand_type, and status
- Retrieve full attributes of an individual Yield Optimization Distribution rule
URIs
| Type | URI |
|---|---|
| Production Instance | https://api.freewheel.tv/services/v4/yield_optimization/distributions?{param1}={query1}&... |
| Staging Instance | https://api.stg.freewheel.tv/services/v4/yield_optimization/distributions?{param1}={query1}&... |
Basic Attributes
| Name | Type | Description | Get Only? | Notes |
|---|---|---|---|---|
| id | FW_ID | The ID of the yield optimization distribution rule. | Yes | |
| network_id | FW_ID | The id of network which the yield optimization distribution rule belongs to. | Yes | |
| name | String | The name of the yield optimization distribution rule. | The maximum length of characters is 255 | |
| description | String | The description of the yield optimization distribution rule. | The maximum length of characters is 500. | |
| start_time | Time | The start time of the yield optimization distribution rule. | The value must be later than current time. | |
| end_time | Time | The end time of the yield optimization distribution rule. | The value must be later than start time and current time It would return empty when end_time is ongoing. | |
| status | Enum | The status of yield optimization distribution. Valid values: - ACTIVE - INACTIVE -NOT_START -EXPIRED | ||
| application_scope | Enum | The demand application scope of a yield optimization distribution rule. It determines whether the rule applies to a specific demand object or the whole network. Valid values: - GLOBAL - DEMAND_TYPE_SPECIFIC | Each network can only have one GLOBAL distribution rule. | |
| demand_type | Enum | The demand type that yield optimization distribution rule takes effect on. Valid values: - PLACEMENT - PROGRAMMATIC_GUARANTEED_DEAL | PROGRAMMATIC_GUARANTEED_DEAL is only valid for Programmatic customers. | |
| supplies_and_optimization_goals | Array of the set of supplies_and_optimization_goal | The supplies and optimization goals of a yield optimization distribution rule. Allows a flexible way to configure the supply scope in expressions composed of multiple dimensions. | The maximum number of supplies_and_optimization_goal sets is 20. | |
| demands | Array of the set of demand | The demand details of selected demand_type of the yield optimization distribution rule applies to. | It will return empty if application_scope = GLOBAL | |
| risk_level | Enum | The risk level of yield optimization distribution. Valid values: - SAFE - LIGHT_RISK - MEDIUM_RISK - HEAVY_RISK - IGNORE_GOAL | ||
| nip_of_other_supplies | Object | The nested inventory prioritization for other supplies of yield optimization distribution. | Contains the same objects as nested_inventory_prioritization. |
Supplies and Optimization Goals - Child Attributes
| Name | Type | Description | Notes |
|---|---|---|---|
| expression_and_goal_id | Integer | The supply and optimization goal id of an optimization goal. | The ID will be generated the first time push a new goal; If the user would like to update an existing optimization goal attribute, please ensure to pass the corresponding expression_and_goal_id in the request. Otherwise, a new goal would be created. |
| expression | Set | The expression comprises multiple dimensions that follow the yield optimization rule. | |
| distribution_value | Decimal | The distribution percentage of the current optimization goal. | The value must be between 0 and 100. The sum of the distribution_value of all goals belonging to one single distributor rule should not be larger than 100. |
| label | String | The label of the current optimization goal. | The maximum length of this field is 255. |
| nested_inventory_prioritization | Set | The inventory prioritization rule of the current optimization goal, expressed as a nested set. |
Expression - Child Attributes
| Name | Type | Description | Notes |
|---|---|---|---|
| relation_between_statements | Enum | The operator of an expression indicates the logical relationship across all relations/statements within the current optimization goal. Valid values: AND, OR | |
| statements | Array of Statement | Each statement contains multiple sets composed of corresponding inclusive and exclusive items. |
Statements - Child Attributes
| Name | Type | Description | Notes |
|---|---|---|---|
| relation_between_sets | Enum | The operator of a relation/statement indicates the logical relationship across all sets within the current relation. Valid values: AND, OR | |
| sets | Array of Set | Each set has its own inclusive and exclusive items. |
Set - Child Attributes
| Name | Type | Description | Notes |
|---|---|---|---|
| item_inclusion_exclusion_type | Boolean | Indicates whether the items below will be inclusive or exclusive items. If the value is true, it means EXCLUDE the items.If the value is false, it means INCLUDE the items. | |
| items | Array of the set of item | Inclusive or exclusive items of each individual set of an optimization goal. |
Item - Child Attributes
| Name | Type | Description | Get Only? | Notes |
|---|---|---|---|---|
| type | Enum | The type of items to be selected into relation/statement sets. Valid values are ENDPOINT_OWNER, ENDPOINT_NAME,COUNTRY, STATE, DMA, POSTAL_CODE, STREAM_MODE, PROGRAMMER, BRAND, CHANNEL, DEVICE, ENVIRONMENT, OS, GENRE, LANGUAGE, TV_RATING, DURATION, DAYPART, INVENTORY_ORDER, INVENTORY_PACKAGE | INVENTORY_ORDER is only valid for Marketplace buyers. INVENTORY_PACKAGE Is only valid for Marketplace customers. | |
| id | FW_ID | The FreeWheel assigned ID of the included/excluded item. | ||
| name | String | The name of the included/excluded item. | Yes |
Nested Inventory Prioritization and Nested Inventory Prioritization for Other Supplies - Child Attributes
| Name | Type | Description | Get Only? | Notes |
|---|---|---|---|---|
| id | FW_ID | The ID of the nested yield optimization inventory prioritization rule. | Yes | |
| name | String | The name of the nested yield optimization prioritization rule. | The maximum length of characters is 255. | |
| description | String | The description of the nested yield optimization prioritization rule. | The maximum length of characters is 500. | |
| prioritization_tiering | Set | The prioritization tiering of each inventory source type including both parent and child tiering. | At least two supply source tiers (parent/child) of a certain prioritization rule. |
Prioritization Tiering - Child Attributes
| Name | Type | Description | Notes |
|---|---|---|---|
| parent_level_tiering | Array of sub-parent_level_tiering | The parent level tiering allows users to apply prioritization tiering to the supply source categories level. | |
| child_level_tiering | Array of set sub-child_level_tiering | The child level tiering allows users to apply prioritization tiering to the individual supply object level. |
Sub Parent Level Tiering - Child Attributes
| Name | Type | Description | Notes |
|---|---|---|---|
| supply_type | Enum | The supply source category of parent-level supply. Valid values are: OWNED_AND_OPERATED, MRM_RULE, INVENTORY_ORDER, and INVENTORY_SPLIT_ORDER. | INVENTORY_ORDER and INVENTORY_SPLIT_ORDER are only valid for Marketplace buyers. |
| priority | Integer | The priority/tier of the corresponding supply_type. | Value must be between 1 and 120. |
Sub Child Level Tiering - Child Attributes
| Name | Type | Description | Get Only? | Notes |
|---|---|---|---|---|
| supply_type | Enum | The supply source category of child-level supply items. Valid values are: INVENTORY_ORDER, INVENTORY_SPLIT_ORDER, and INVENTORY_PACKAGE. | INVENTORY_ORDER, INVENTORY_SPLIT_ORDER are only valid for Marketplace buyers. INVENTORY_PACKAGE Is only valid for Marketplace customers. | |
| supply_id | FW_ID | The FreeWheel assigned ID of the child-level supply item for tiering. | ||
| supply_name | String | The name of the child-level supply item for tiering. | Yes | |
| priority | Integer | The priority/tier of the child-level supply item for tiering. | The value must be between 1 and 120. |
Demand - Child Attributes
| Name | Type | Description | Get Only? | Notes |
|---|---|---|---|---|
| demand_id | FW_ID | The ID of the demand object that the YO rule applies to. | Yes | |
| demand_name | String | The name of the demand object that the YO rule applies to. | Yes | |
| public_id | String | The external_deal_id of the programmatic deal that the YO rule applies to. | Yes | Valid only when demand_type = PROGRAMMATIC_GUARANTEED_DEAL |