💡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

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:

Algorithm Modes	How this Mode functions	How to enable this Mode
Text Match Precision (Default)	This mode works on basic term match. Suppose your customer searches for the query “black shoes”. This mode recalls all the products that match on the term “black” and the term “shoes” in the product details.	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: query.precision=text_match_precision
Product Type Precision	This mode filters down the recall set by identifying the product type using Bloomreach’s semantic understanding. There are 3 ways to extract the product type: From the query: “shoes” product type in the query “black shoes” From synonyms: If you have defined a synonym rule for shoes -> boots, then for the query “black shoes”, the product type identified will be both shoes and boots. From user behavior data: Suppose, while searching for “black shoes”, your customers often click on heels product type. Then, the recall set will include the heels product type with the shoes product type.	To enable this pass the following in the front-end API call: query.precision=product_type_precision
Category Precision	This mode filters down the recall set by identifying the dominant category. 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. Suppose the top products in the recall of the query “black shoes” belong to the shoes and men’s boots categories. The recall set will be filtered to include products from only these two categories.	To enable this pass following in the front-end API call: query.precision=category_precision
LLM-based Precision	LLM-based precision leverages cutting-edge ML technology (Vector-based models) to truly recognize the related product types behind the entire range of head, torso, and tail queries. Suppose a shopper searches for "white shoes". Bloomreach’s semantic understanding identifies “shoes'' as the product type for this query. Then, the Large language model — fine-tuned on customer product data like type, size, color, brand, and material — recognizes related product types such as "boots," "cleats," or "pumps." User behavior data may provide related product types such as “loafers” and “trainers”. Consequently, only products belonging to these specific product types are included in the recall set.	To enable this pass following in the front-end API call: query.precision=llm_based_precision

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:

Algorithm Modes

How this Mode functions

How to enable this Mode

Product Type (Default)

To reduce null results, this mode identifies the query intent using Bloomreach’s semantic understanding.

Suppose the customer searches for “small fabulous table” 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 “table” will be used for the search. small and fabulous will be used as optional search terms. This helps reduce null results.

This is enabled by default.

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:

query.relaxation=product_type

Off

This mode disables the default Query Relaxation algorithm.

Suppose the customer searches for “small fabulous table” and there are no matches for all these terms in the product details. The search results will show zero results.

To turn off Query Relaxation, pass the following in the front-end API call:
query.relaxation=off

NOTE: This could lead to an increase in 0 results since the algorithm will not try to relax a query

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:

Algorithm Modes	How this Mode functions	How to enable this Mode
Term Frequency (Default)	It uses term frequency 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. Suppose the customer enters the query “shrts” 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 shirts, shorts, and shoes. If shorts appear more frequently in your catalog than the other two candidates, then the query “shrts” will be corrected to shorts.	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: query.spellcorrect=term_frequency
Closest Match	It uses Edit Distance within the ranking in order to find the most likely candidate for a misspelled word. Suppose the user enters the query “bode”. 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 body and blue. The edit distance for each candidate is computed to compare the candidates. Since body has a smaller edit distance than blue, the query “bode” will get corrected to body.	To enable this, pass the following in the front-end API call: query.spellcorrect=closest_match
Off	This mode disables the default Spell Correct algorithm.	To turn off Spell Correct, pass the following in the front-end API call: query.spellcorrect=off NOTE: This could lead to an increase in 0 results since the algorithm will not try to find a spell correction

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:

Algorithm Modes	How this Mode functions	How to enable this Mode
Standard (Default)	Standard mode ranks relevant facets higher than the irrelevant facets. Suppose for the query “pillows”, the facets are color, pillow cases, vase, and candles. The facets color and pillow cases will be ranked higher than vase and candles.	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: facet.precision=standard
High	This mode targets and removes facet noise in search results. It helps clean up the irrelevant facets as well as facet values coming from the products buried in the search results. Suppose for the query “pillows”, the facets are color, pillow cases, vase, and candles. It will remove the facets vase and candles as these are irrelevant.	To enable this, pass the following in the front-end API call: facet.precision=high

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 Modes	How this Mode functions	How 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`
High	This 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 Modes	How this Mode functions	How 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`
off	This 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:

Algorithm	Languages 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 Relaxation	Only supports English, French, and German
Facet Precision	- Standard Facet Precision: All languages are supported - High Facet Precision: Only supports English, French, and German
Spell Correct	All languages are supported.
Numeric Precision	All languages are supported.
SmartSort	All 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 Modes	How to enable this Mode	How this Mode functions
Disable Performance signals only	This 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 only	This 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 algorithm	This mode disables all the signals that make up ranking algorithm i.e. it disables both performance signals as well as relevance signals	You’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

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.

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

Select the Custom tab and enter the required parameter. In this case, the parameter is query.relaxation=off.
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.

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

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
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.

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
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:

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).
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.
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