Get query suggestions

This is for:

Developer
In this article

You can request basic query expression (q) completions from a Coveo Machine Learning (Coveo ML) query suggestions model by sending a GET or POST HTTP request to https://platform.cloud.coveo.com/rest/search/v2/querySuggest.

The Search API query suggestion route supports several parameters which you can include either in the query string of a GET request, or in the JSON body of a POST request (see QS parameters).

Note

When using an OAuth2 token to authenticate a GET or POST HTTP request to the Search API query suggestion route, you must specify the unique identifier of the target organization by including the organizationId argument in the query string of your request.

Examples
  1. Requesting query suggestions using the GET method:

    GET https://platform.cloud.coveo.com/rest/search/v2/querySuggest?locale=en&q=twa&searchHub=BookstoreSearch HTTP/1.1
    
    Accept: application/json
    Authorization: Bearer **********-****-****-****-************
  2. Requesting query suggestions using the POST method:

    POST https://platform.cloud.coveo.com/rest/search/v2/querySuggest HTTP/1.1
    
    Content-Type: application/json
    Accept: application/json
    Authorization: Bearer **********-****-****-****-************

    Payload

    {
      "locale": "en",
      "q": "twa",
      "searchHub": "BookstoreSearch"
    }
Tip

200 OK response body (excerpt)

{
  "completions": [
    {
      "executableConfidence": 1,
      "expression": "mark twain",
      "highlighted": "[mark] {twa}[in]",
      "score": 14.525258530973204
    },
    {
      "executableConfidence": 0.6666666666666666,
      "expression": "[wes]{twa}[rd] [ho]",
      "highlighted": "",
      "score": 8.50548085208594
    },
    {
      "executableConfidence": 0.5,
      "expression": "hot water music",
      "highlighted": "[hot] (wat)[er] [music]",
      "score": 7.107770631785241
    },
    ...
  ]
}
Notes
  • If the query suggestion request is routed to a query pipeline with no associated Coveo ML QS model, the request will return an empty completions array.

  • In a completions array item:

    • The score property value only has relative significance within the same completions array.

      For example, a suggestion with a score of 14.811407079917723 in the completions array of response A isn’t necessarily less relevant than a suggestion with a score of 24.325728875625282 in the completions array of response B.

    • The highlighted property uses the following logic:

      • Characters between curly braces (for example, {cat}) indicate an exact match with q.

      • Characters between square braces (for example, [cher]) indicate completions.

      • Characters between parentheses (for example, (act)) indicate corrections to q.

    • The executableConfidence property contains a floating-point value between 0 and 1 indicating how “convinced” Coveo ML is that performing a query with this suggestion as a basic query expression will return relevant results. The threshold from which Coveo ML considers a query suggestion executable is 0.8.

Troubleshooting

If your QS model isn’t behaving as expected, this may be due to a mismatch between the searchHub value used in your Search API requests and the originLevel1 value used when logging events for the target search interface through the Coveo Usage Analytics (Coveo UA) Write API. It’s important that those values match in any given search interface, since the Coveo ML service uses them as filter fields.

Example

You have a search interface for books, and another one for movies.

On the usage analytics side, when logging events in those search interfaces, the originlevel1 value specified in your requests is, respectively, BookstoreSearch and MovieStoreSearch.

On the Search API side, this translates into very distinctive behavior from one searchHub to another. You make the following request:

POST https://platform.cloud.coveo.com/rest/search/v2/querySuggest HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "q": "Dost",
  "searchHub": "BookstoreSearch"
}

The Search API returns the following completions, where the Dostoevsky suggestion is executable and highly recommended:

Tip

200 OK response body (excerpt)

{
  "completions": [
    {
      "executableConfidence": 1,
      "expression": "Dostoevsky",
      "highlighted": "{Dost}[oevsky]",
      "score": 56.135864235791246
    },
    ...
  ]
}

You make the following request to the Search API:

POST https://platform.cloud.coveo.com/rest/search/v2/querySuggest HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "q": "Dost",
  "searchHub": "MovieStoreSearch"
}

The Search API returns the following completions, where Dosti (a highly successful Hindi film) is executable and highly recommended, and where Dostoevsky doesn’t figure at all:

Tip

200 OK response body (excerpt)

{
  "completions": [
    ...
    {
      "executableConfidence": 1,
      "expression": "Dosti",
      "highlighted": "{Dost}[i]",
      "score": 35.183255413846215
    },
    ...
  ]
}

Hence, when in the BookstoreSearch search interface, it’s very important to pass the "searchHub": "BookstoreSearch" for the relevant query suggestion Dostovesky to be returned, instead of Hindi films.

Note

Analogous remarks hold for the tab value used in your Search API requests and the originLevel2 value used in your Coveo UA Write requests.