Search Term Relaxation

When using the Boxalino Personalization API to search, you can optionally request for a search term relaxation. This is typically used to provide search term suggestions and/or sub phrase results when the original query does not yield any or enough results.

Our plugins enable this feature by default. This is an explanation on how to implement it using our API.

The code examples are in Java, but can be applied to all the programming languages we provide API clients for.

Requesting Relaxation

To get a relaxation in the response, set the flag "withRelaxation" to true in your ChoiceInquiry:

// prepare inquiry
final ChoiceInquiry choiceInquiry = new ChoiceInquiry();

You could request it in a second API call after the first call yielded a "totalHitCount" of 0, but we recommend to add it to all search requests by default, as the performance penalty of this feature is very small.

When a relaxation is requested, the Variant objects in the ChoiceResponse will carry a SearchRelaxation object in the "searchRelaxation" property. It consists of "suggestionsResults" and "subphrasesResults".

Suggestion Results

The suggestions are based on the same terms as the autocompletion suggestions and are intended to provide "did you mean" style error correction. Our search does find results with common misspellings in each language, but if the words are not based on the requested language (i.e. french search term in german search index) or if the spelling deviates to much from the correct one, it won't autocorrect them. In such cases it is better practice to suggest similar words to the visitor to select.

If no results for the original "queryText" are found and only one SearchResult in the "suggestionsResults" is provided, we recommend to display it instead directly, but to display a message to the visitor, i.e. "results for [suggested term], no results found for [original term]".

Subphrase Results

If the original "queryText" contains multiple words the subphrase results contain a SearchResult per word. We recommend to show only the 3 to 5 first hits of these results with a subtitle including a link to the full search result page for that term and a "totalHitCount" per result, i.e. "results for [subphrase] ([totalHitCount of subphrase])".

Deciding when to show relaxation

Since we provide the relaxations as different parts, you are very flexible in how you choose to display them and when:

  • You could show them below the result already if there are very few results for the original terms or only if there are no results at all.
  • You could display just one suggested term, multiple suggestions or even a result preview for each suggested term.
  • You can choose to first display the subphrases before the suggested terms.

Example logic to display the relaxed results

Here below is an example of a logic to display both suggestions and subphrases, if there are fewer then 6 results for the original search term:

final ChoiceResponse choiceResponse = client.choose(choiceRequest);
for (Variant variant : choiceResponse.getVariants()) {
    final SearchResult originalSearchResult = variant.getSearchResult();
    if (originalSearchResult.getTotalHitCount() > 5) {
        // display originalSearchResult
    } else {
        final List<SearchResult> suggestionsResults = variant.getSearchRelaxation().getSuggestionsResults();
        if (suggestionsResults.size() > 0) {
            // display suggestionsResults
        final List<SearchResult> subphrasesResults = variant.getSearchRelaxation().getSubphrasesResults();
        if (subphrasesResults.size() > 0) {
            // display suggestionsResults

Note that since in all three cases the object is of type SearchResult, you can reuse the display logic used for the original SearchResult.

Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk