## 💡**Prerequisite knowledge**




We recommend that you review the following guide to understand the algorithms discussed in this guide:

  • [Algorithm controls feature guide](🔗): This guide introduces you to the Algorithm Controls feature.

# **What are API Controls**




API Controls are one of the routes you can use to configure the Algorithm Controls feature. And these API Algorithm controls have configurable modes. To make changes to any of the algorithms, you’re required to **pass the specified parameter directly to the front-end API call**.

# **How to configure API Controls**




The following section discusses the available controls and the process to modify the mode settings:

  • [Search Recall Precision](🔗)

  • [Query Relaxation](🔗)

  • [Spell Correct ](🔗)

  • [Facet Precision](🔗)

  • [Numeric Precision](🔗)

  • [SmartSort](🔗)

## Search Recall Precision




[Search Recall Precision](🔗) targets and removes the recall noise to only show relevant products for a query.

This table summarizes the working and enablement of Search Recall Precision Algorithm modes:

<table> <tr> <td><strong>Algorithm Modes</strong> </td> <td><strong>How this Mode functions</strong> </td> <td><strong>How to enable this Mode</strong> </td> </tr> <tr> <td>Text Match Precision (Default) </td> <td>This mode works on <strong>basic term match</strong>. <p> Suppose your customer searches for the query “<em>black shoes”.</em> This mode recalls all the products that match on the term “black” and the term “shoes” in the product details. </td> <td>This is enabled by default, but if you have enabled another precision mode and want to go back to text match, you’ll need to pass the following in the front-end API call: <p> <strong>query.precision=text_match_precision</strong> </td> </tr> <tr> <td>Product Type Precision </td> <td>This mode filters down the recall set by identifying the <strong>product type</strong> using Bloomreach’s semantic understanding. <p> There are 3 ways to extract the product type: <ol>

<li><strong>From the query</strong>: “shoes” product type in the query “<em>black shoes</em>”

<li><strong>From synonyms</strong>: If you have defined a synonym rule for <em>shoes -> boots</em>, then for the query “<em>black shoes</em>”, the product type identified will be both shoes and boots.

<li><strong>From user behavior data:</strong> Suppose, while searching for “<em>black shoes</em>”, your customers often click on <em>heels</em> product type. Then, the recall set will include the heels product type with the shoes product type. </li> </ol> </td> <td>To enable this pass the following in the front-end API call: <p> <strong>query.precision=product_type_precision</strong> </td> </tr> <tr> <td>Category Precision </td> <td>This mode filters down the recall set by identifying the <strong>dominant category</strong>. When a query comes in, it checks the top products in the recall and determines which categories they fall into. Only products from these top categories appear in the result set. <p> Suppose the top products in the recall of the query “<em>black shoes</em>” belong to the <em>shoes</em> and <em>men’s boots</em> categories. The recall set will be filtered to include products from only these two categories. </td> <td>To enable this pass following in the front-end API call: <p> <strong>query.precision=category_precision</strong> </td> </tr> </table>

## Query Relaxation




**[Query Relaxation ](🔗)**aims at reducing zero results by identifying the core product type in a query if an exact match isn’t found.

This table summarizes the working and enablement of Query Relaxation Algorithm modes:

<table> <tr> <td><strong>Algorithm Modes</strong> </td> <td><strong>How this Mode functions</strong> </td> <td><strong>How to enable this Mode</strong> </td> </tr> <tr> <td>Product Type (Default) </td> <td>To reduce null results, this mode <strong>identifies the query intent</strong> using Bloomreach’s semantic understanding. <p> Suppose the customer searches for <em>“small fabulous table”</em> and there are no matches for these terms in the product details. Our semantic engine understands that the user’s intent is to search for a table. The query will be relaxed and only “<em>table”</em> will be used for the search. <em>small</em> and <em>fabulous</em> will be used as optional search terms. This helps reduce null results. </td> <td>This is enabled by default. <p> If you have turned off query relaxation and want to go back to Product Type, you’ll need to pass the following in the front-end API call: <p>

<strong>query.relaxation=product_type</strong>

</td> </tr> <tr> <td>Off

</td> <td>This mode disables the default Query Relaxation algorithm. <p> Suppose the customer searches for “<em>small fabulous table</em>” and there are no matches for all these terms in the product details. The search results will show zero results. </td> <td>To turn off Query Relaxation, pass the following in the front-end API call: <br> <strong>query.relaxation=off</strong><br><br> <p> <strong>NOTE</strong>: This could lead to an increase in 0 results since the algorithm will not try to relax a query</p> </td> </tr> </table>

## Spell Correct




**[Spell Correct ](🔗)**aims at reducing zero results by autocorrecting misspelled queries.

This table summarizes the working and enablement of Spell Correct Algorithm modes:

<table> <tr> <td><strong>Algorithm Modes</strong> </td> <td><strong>How this Mode functions</strong> </td> <td><strong>How to enable this Mode</strong> </td> </tr> <tr> <td>Term Frequency (Default) <p> </td> <td>It uses <strong>term frequency</strong> to rank the different candidates for a correction. In other words, the algorithm will consider a term that appears more frequently in your catalog as the likely candidate for spell correction. <p> Suppose the customer enters the query “<em>shrts</em>” and there is no match available for this term. To avoid showing null results, this mode will look for corrected query candidates. The corrected spelling candidates can be <em>shirts, shorts</em>, and <em>shoes</em>. If <em>shorts</em> appear more frequently in your catalog than the other two candidates, then the query “<em>shrts”</em> will be corrected to <em>shorts</em>. </td> <td>This is enabled by default, but if you have turned off or have another Spell Correct mode and want to go back to Term Frequency, they’ll need to pass the following in the front-end API call: <p> <strong>query.spellcorrect=term_frequency </strong> </td> </tr> <tr> <td>Closest Match </td> <td>It uses <strong>Edit Distance</strong> within the ranking in order to find the most likely candidate for a misspelled word. <p> Suppose the user enters the query “<em>bode”</em>. No product has this product in the product details. Instead of showing zero results, this mode will look at the possible candidates. The candidates can be <em>body</em> and <em>blue</em>. The edit distance for each candidate is computed to compare the candidates. Since <em>body</em> has a smaller edit distance than <em>blue</em>, the query “<em>bode</em>” will get corrected to <em>body</em>. </td> <td>To enable this, pass the following in the front-end API call: <br> <strong>query.spellcorrect=closest_match </strong> </td> </tr> <tr> <td>Off </td> <td>This mode disables the default Spell Correct algorithm. </td> <td>To turn off Spell Correct, pass the following in the front-end API call: <br> <strong>query.spellcorrect=off</strong> <br><br> <strong>NOTE</strong>: This could lead to an increase in 0 results since the algorithm will not try to find a spell correction </td> </tr> </table>

## Facet Precision




**[Facet Precision](🔗) **cleans up the facet noise coming from the irrelevant products further down in the recall set without impacting the actual product recall itself. It helps remove irrelevant facets.

This table summarizes the working and enablement of Facet Precision Algorithm modes:

<table> <tr> <td><strong>Algorithm Modes</strong> </td> <td><strong>How this Mode functions</strong> </td> <td><strong>How to enable this Mode</strong> </td> </tr> <tr> <td>Standard (Default) </td> <td>Standard mode ranks relevant facets higher than the irrelevant facets. <p> Suppose for the query “pillows”, the facets are <em>color, pillow cases, vase, </em>and<em> candles.</em> The facets <em>color and pillow cases </em>will be ranked higher than <em>vase </em>and<em> candles.</em> </td> <td>This is enabled by default. If you have another facet precision ON and want to go back to Standard, you’ll need to pass the following in the front-end API call: <p> <strong>facet.precision=standard</strong> </td> </tr> <tr> <td>High </td> <td>This mode targets and removes facet noise in search results. It helps <strong>clean up the irrelevant facets as well as facet values</strong> coming from the products buried in the search results. <p> Suppose for the query “pillows”, the facets are <em>color, pillow cases, vase, </em>and<em> candles.</em> It will remove the facets <em>vase</em> and <em>candles</em> as these are irrelevant. </td> <td>To enable this, pass the following in the front-end API call: <p> <strong>facet.precision=high</strong> </td> </tr> </table>

## Numeric Precision




[Numeric Precision](🔗) makes the recall set more precise by limiting the recall to only those products that match the **numeric intent** expressed in the query.

This table summarizes the working and enablement of Numeric Precision Algorithm modes:

Algorithm ModesHow this Mode functionsHow to enable this Mode
Standard (Default)This recalls products having either the same quantitative match or direct text matches.If you have high mode enabled and want to add a query level override, this mode can be enabled on the front-end API by passing the following parameter: **`query.numeric_precision=standard`**
HighThis displays a restricted recall with precise quantitative matches.Pass the following parameter to enable High Numeric Precision. **`query.numeric_precision=high`**

## SmartSort

[SmartSort](🔗) ensures that when your shopper chooses to sort the product results, then:

  • Any noise in the recall set remains buried.

  • Only relevant products surface when the shopper applies a sort.

This table summarizes the working and enablement of SmartSort Algorithm modes:

Algorithm ModesHow this Mode functionsHow to enable this Mode
Product Type(Default)When your shopper sorts the product results, this ensures that any noise in the recall set remains buried and only relevant products are displayed.This is enabled by default, but if you have turned off SmartSort, then pass the following in the front-end API call: **`query.smartsort=top_products`**
offThis mode disables the default SmartSort algorithm.To turn off SmartSort, pass the following in the front-end API call: **`query.smartsort=off`**



**Note**: Some algorithm settings are only available to English sites and not applicable to non-English sites. The following table summarizes the languages supported for each algorithm:

AlgorithmLanguages Supported
Search Recall Precision- Text Match: [All languages](🔗) are supported - Product Type Precision: Only supports **English** - Category Precision: Only supports **English**, **French**, and **German**
Query RelaxationOnly supports **English**, **French**, and **German**
Facet Precision- Standard Facet Precision: All languages are supported - High Facet Precision: Only supports **English**, **French**, and **German**
Spell CorrectAll languages are supported.
Numeric PrecisionAll languages are supported.
SmartSortAll languages are supported.

## Influence Bloomreach's Ranking

Today, all merchandising boost rules are additive in nature i.e. they get added to the Bloomreach's ranking algorithm score. Sometimes you might want to create unique experiences on particular search or category pages by removing any influence of Bloomreach's ranking algorithm. For example, for a category page, you might want to boost all promotional products and remove any influence of Bloomreach algorithm. For use cases like this, you could now use following parameters and pass those in the front-end API:

Algorithm ModesHow to enable this ModeHow this Mode functions
Disable Performance signals onlyThis mode disables all the signals that make up the performance score.You’ll need to pass the following in the front-end API call: **br_ranking.performance = off**
Disable Relevance signals onlyThis mode disables all the signals that make up the relevance score.You’ll need to pass the following in the front-end API call: **br_ranking.relevance = off**
Disable ranking algorithmThis mode disables all the signals that make up ranking algorithm i.e. it disables both performance signals as well as relevance signalsYou’ll need to pass the following in the front-end API call: **br_ranking = off**

**Note**: While we allow this capability to turn off the influence of Bloomreach's ranking algorithm, it's important to note that passing these parameters across the site could have significant performance implications so it's highly recommended that you use these parameters only for a few search or category pages where unique ranking experience is desired.

# **View Algorithm Controls in Action with Ranking Diagnostics**




You can use Ranking Diagnostics to pass the required parameters in the front-end API call and view the results for different algorithm modes. For this, you need access to Ranking Diagnostics in Discovery Dashboard.

### **Setting up Algorithm Controls in Ranking Diagnostics **

  1. Go to **`Search & Merchandising > Operational tools > Ranking diagnostics`**. In this example, we have Query Relaxation turned ON by default. The query “_small fabulous table_” currently shows 1463 results. We’ll turn Query Relaxation OFF using Algorithm controls parameters.

1999

  1. To turn OFF Query Relaxation, click the **`Edit`** option next to the API Modifier tag.

1141

  1. Select the **`Custom`** tab and enter the required parameter. In this case, the parameter is **query.relaxation=off.**

  2. Click **`+Add`** and then Save the settings. The added parameter will appear next to the **API Modifier** tag.



### **Impact of Algorithm mode changes**




After disabling Query Relaxation, the same query will now show null results.

1999


**Note**: We have discussed Query Relaxation OFF mode controls in this example. You can follow the same steps for adding parameters to the front-end API calls for the other 3 Algorithm controls.

# **API Controls FAQs**



  1. **Can all the algo controls be turned off?** No, only Query Relaxation, Spell Correct, and SmartSort can be turned off. Refer to the table above for more details

  2. **What happens when two different values of the same algo control feature are passed in one API call?** The system will respect the order in which the parameters are sent in the API call and will pick the last one. Although, if the last value isn’t correct or cannot be applied for that query, then the system will fall back to the previous value that is passed in the API. <br><br> For example, in an API call, consider the first value for precision mode passed is **query.precision=product_type_precision** followed by **query.precision=category_precision**. In this case, the system will apply **query.precision=category_precision** given all the conditions for Category Precision are satisfied for that query. If the conditions are not satisfied, it will fall back to Product Type Precision

  3. **What happens when invalid values are passed in the API parameters?** Invalid values will throw a 400 error with the message "Incorrect value passed for X''. Here, X could be query.precision, facet.precision, query.spellcorrect, query.relaxation. For example:

824

  1. **What takes priority over what is passed through API vs what is currently enabled for a customer?** API takes precedence over backend configuration i.e. whatever is currently enabled for you. For example, if Category precision is currently enabled for you in the backend, it will continue to work as-is. However, if you want to test out Product type precision, you can pass that in the API call and then API (Product Type) will override the existing setting enabled in the backend(Category Precision).

  2. **What happens when a parameter is passed for a catalog that doesn’t support an Algorithm control or Algorithm control mode?** It will disregard the parameter i.e. the API call will not fail, but the value that is passed will not get applied. For example, Product Type Precision is not applicable to the French catalog. So, if you send a parameter in the API call as **query.precision=product_type_precision** for this French catalog, it will not be applied.

  3. **Would the dashboard automatically sync and show the same results if Algorithm control parameters are passed directly through the front-end API?** No, controlling the setting of features directly from the front-end API call doesn’t automatically synchronize with Bloomreach's dashboard. Hence, the results might look different in both places. To ensure consistency, you would need to pass the same parameter that you are controlling on the front-end API in the “API Modifier” section under **`Setup -> brSM global configurations -> API modifier`**