Adding suggestions

You can add a widget.items.search.suggestion object to get suggestions you can use to autocomplete user queries and display predictive search results.

Note

Before you can request suggestions, make sure that an administrator configures Suggestion Blocks in Sitecore Search.

For the data model of this object, see the Search and Recommendation API reference.

Getting suggestions when there is a keyphrase

When you request suggestions to match a keyphrase, you need to pass both the query and suggestion objects.

For example, a visitor searches for the keyword cloud and you want to:

Show five keyphrase suggestions after the visitor enters the keyword.
Use a predefined suggestion block called title_context_aware that uses content titles and the visitor's context to show relevant keyphrase suggestions.

Note

For this example, we use a suggestion type called title_context_aware. However, you can use any suggestion type that an administrator has defined.

The following is the sample request:

RequestResponse

{
    "widget": {
        "items": [
            {
                "rfk_id": "rfkid_7",
                "entity": "content",
                "search": {
                    "suggestion": [
                        {
                            "max": 5,
                            "name": "title_context_aware"
                        }
                    ],
                    "query": {
                        "keyphrase": "cloud"
                    }
                }
            }
        ]
    },
    "context": {
        "locale": {
            "country": "us",
            "language": "en"
        },
        "user": {
            "uuid": "159871551-m7-17-44-1p-c0ya4nb69t8o0iho2eia-1667926756185"
        }
    }
}

The following is the response to the request:

RequestResponse

{
    "widgets": [
        {
            "rfk_id": "rfkid_7",
            "entity": "content",
            "suggestion": {
                "title_context_aware": [
                    {
                        "text": "cloud on salesforce",
                        "freq": 4
                    },
                    {
                        "text": "cloud architecture",
                        "freq": 4
                    },
                    {
                        "text": "cloud portal",
                        "freq": 3
                    },
                    {
                        "text": "cloud portal technical",
                        "freq": 3
                    },
                    {
                        "text": "cloud resources",
                        "freq": 2
                    }
                ]
            }
        }
    ],
    "dt": 104,
    "ts": 1669689280650
}

You can see that the response suggestion object has a list of suggestions that you can show when the user enters the keyphrase cloud.

Getting suggestions when there is no keyphrase

You can request suggestions that are not based on a keyphrase, such as when the visitor clicks within the search bar but has not typed anything.

To get suggestions without a keyphrase, ensure the following:

A suggestion block that uses the contextAware or sortByAttribute algorithm exists in Search and you use this suggestion block in your request.
The visitor has clicked through your website enough for Search to gather information about their preferences.

Note

You still can request suggestions without a keyphrase even if a visitor has not interacted with your website. However, you will not get any suggestions in the response because Search will not have any data on what the visitor prefers.
Personalization, ranking, or both, are enabled. By default, Search enables personalization in the API request but you must pass a UUID for it to work. For ranking, you can have an Administrator configure it in Search and optionally override it by passing a ranking object in the API request.

Note

You can still request suggestions without a keyphrase without enabling personalization or ranking. However, you will get zero suggestions in the response because Search will not have any data on what the visitor prefers.

Here's a sample request to get six suggestions when there is no keyphrase using a suggestion block named title_context_aware :

RequestResponse

{
    "widget": {
        "items": [
            {
                "rfk_id": "rfkid_7",
                "entity": "content",
                "search": {
                    "suggestion": [
                        {
                            "max": 6,
                            "name": "title_context_aware"
                        }
                    ]
                }
            }
        ]
    },
    "context": {
        "locale": {
            "country": "us",
            "language": "en"
        },
        "user": {
            "uuid": "159871551-m7-17-44-1p-c0ya4nb69t8o0iho2eia-1667926756185"
        }
    }
}

Using suggestions as a search fallback

Sometimes, a visitor enters a search term and clicks the search button without clicking a suggestion. If the term they entered has a typo or has no matches, Search returns zero results, and the visitor sees an empty search page.

To handle this situation, you have two options:

Show an empty search page with a did you mean <term with corrected typo> line at the top of the page. Then, when the visitors click the corrected term, they see the search results for that term.

Note

To do this, create a Did you mean UI element. Create a request as shown in the Getting suggestions when there is a keyphrase section, and pass the response suggestions in Did you mean element.
Configure Search to use the first suggestion as an alternate search term. In this scenario, the user never sees an empty search page.

If you want to go with the second option:

Set the suggestion.keyphrase_fallback property to true. When you do this, if Search finds zero results for a search, it uses the first suggestion from the first suggestion block as an alternate keyword.
Add an empty response_context object to ensure that the response contains the alternative search term if used.

For example, a visitor searches for conten with a typo, and clicks the search button. If you set keyphrase_fallback:true, and Search is able to generate at least one suggestion, the following events occur:

When you first send the request, Search does a back-end search using the keyphrase conten. However, Search does not return a response because you configured an automatic fallback.
Sitecore Searchredoes the search using the first suggestion provided by this suggestion block as the alternate keyphrase. For example, assume that the suggestions returned are content cloud, content hub, and content management, in that order. Sitecore Search uses content cloud as the alternate keyphrase, and the visitor is then shown a search page with results for this key phrase.

Here's a sample request for the previous example of a visitor searching for conten that uses three suggestion blocks (title_context_aware, title, and title_spelling ):

RequestResponse

 "widget": {
    "items": [
      {
        "entity": "content",
        "rfk_id": "rfkid_7",
        "search": {
          "content": {},
          "query": {
            "keyphrase": "conten"
          },
          "suggestion": [
            {
              "name": "title_context_aware",
              "max": 3,
              "keyphrase_fallback": true
            },
            {
              "name": "title",
              "max": 3,
              "keyphrase_fallback": true
            },
            {
              "name": "title_spelling",
              "max": 3,
              "keyphrase_fallback": true
            }
          ],
          "response_context": {}
        }
      }
    ]
  }
}'

Here's a sample response to this request:

RequestResponse

{
  "widgets": [
    {
      "rfk_id": "rfkid_7",
      "entity": "content",
      "suggestion": {
        "title_context_aware": [
          {
            "text": "content cloud",
            "freq": 4
          },
          {
            "text": "content hub",
            "freq": 4
          },
          {
            "text": "content management",
            "freq": 3
          }
        ],
        "title": [
          {
            "text": "content editor vs experience editor",
            "freq": 4
          },
          {
            "text": "content management and delivery",
            "freq": 3
          },
          {
            "text": "content hub sitecore documentation",
            "freq": 3
          }
        ],
        "title_spelling": [
          {
            "text": "content",
            "freq": 2
          },
          {
            "text": "contents",
            "freq": 4
          }
          {
            "text": "contentful",
            "freq": 4
          }
        ]
      }
    }
  ],
  "dt": 104,
  "ts": 1669689280650,
  "response_context": {
    "keyphrase": "content cloud",
    "original_keyphrase": "conten"
  }
}

You see that Search used the term content cloud to search (the keyphrase) because this was the first suggestion returned by the first suggestion block.

Do you have some feedback for us?

If you have suggestions for improving this article,