The Search API additionally offers the capability to apply merchandising operations to the returned products. This allows you to curate the search results and optimize the search recall for personalization just like merchandising via the dashboard.
Along with the Search API, these Merchandising capabilities and parameters are also available for the following APIs:
- Personalization-based Widgets API (Past Purchases)
- Bestseller API
- Thematic Pages API
You can use different API parameters to control these operations. The following sections walk you through how each supported merchandising operation can be applied using which API parameter.
Conflict resolution
Conflicting merchandising rules, coming from either the dashboard or API will be resolved by following the guidelines mentioned on the Conflict Resolution for Ranking Rules page.
PID-based product ranking
The dashboard guide for PID-based Ranking can be found here.
| Operation | Parameter | Usage | Dashboard + API: Rule merging |
|---|---|---|---|
| Hard Boost (Boost to Top) | boost | &boost=pid:<value>Example: &boost=pid:PID123 | All distinct PIDs boosted from the dashboard and via the API are combined. |
| Hard Bury (Bury to Bottom) | bury | &bury=pid:<value>Example: &bury=pid:PID123 | All distinct PIDs buried from the dashboard and via the API are combined. |
| Lock Position | lock | &lock=pid:<value>#<position>Example: &lock=pid:19018#3The number after “#” denotes the position in the product grid to lock the product at. | In case of a conflict of PIDs, the rule set from the API param will take precedence over the dashboard. Similarly, in case of same position, the API rule will take precedence, and the product in the Dashboard rule will be moved to the next available slot. |
| Add to Recall | add_to_recall | &add_to_recall=pid:<value>Example: &add_to_recall=pid:PID123 | All distinct PIDs added to recall from the dashboard and via the API are combined. |
| Block | efq | &efq=-pid:<value>Example: &efq=-pid:63167The “-” before the PID value denotes that the given PID should be excluded. Note: If you want to block multiple PIDs, we recommend that you use the Exclude operation instead. | All distinct PIDs blocked from the dashboard and via the API are combined. |
Attribute-based product ranking
The dashboard guide for Attribute-based Ranking can be found here.
| Operation | Parameter | Usage | Dashboard + API: Rule merging |
|---|---|---|---|
| Soft Boost | soft_boost | &soft_boost=<attribute>:<value>^<boost-strength>Example: &soft_boost=size:7^25Note that the value after “^” denotes the strength of the boost. | The API rule will be applied as a new boosting rule on top of the dashboard boosting rule. Suppose an attribute is boosted by 50% from the dashboard and by 25% from API. The API rule will add an additional boost of 25% on the existing dashboard rule of 50%. Rules will be applied sequentially. |
| Soft Bury (Currently not supported for numerical attributes) | soft_bury | &soft_bury=<attribute>:<value>^<bury-strength>Example: &soft_bury=brand:homeoasis^25Note that the value after “^” denotes the strength of the bury. | The API rule will be applied as a new burying rule on top of the dashboard burying rule. Suppose if an attribute is buried by 10% from the dashboard and by 20% from API. The API rule will add an additional bury strength of 20% on the existing dashboard rule of 10%. Rules will be applied sequentially. |
| Include Only | include | &include=<attribute>:<value>Example: &include=brand:"Pacific Ocean" | The API rule will be applied as a new include rule on top of the dashboard include rule. |
| Exclude | exclude | &exclude=<attribute>:<value>Example: &exclude=brand:homeoasis | The API rule will be applied as a new exclude rule on top of the dashboard exclude rule. |
Boolean operations
You can apply boolean operations to combine multiple parameter values or ranking rules logically.
| Operator | Example |
|---|---|
| OR | &soft_boost=color:Red OR Black^25 |
| AND | &soft_boost=brand:"Pacific Ocean" AND color:Black^25 |
| NOT (!) | &soft_boost=color:!Red |
Range controls for numerical attributes
| Operator | Example | Explanation |
|---|---|---|
| Range | &soft_bury=price:[10 TO 20]^33 | Apply a Bury of strength 33% on products with Price >= 10 and Price =< 20 (both values included). |
| Greater than | &soft_boost=price:[100 TO *]^33 | Apply a Boost of 33% on products with Price >= 100. |
| Less than | &soft_boost=price:[* TO 10]^33 | Apply a Boost of 33% on products with Price =< 100. |