Get query suggestions

This is for:

Developer

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 QS 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 QS route, you must specify the unique identifier of the target organization by including the organizationId argument in the query string of your request.

Query suggestion 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 QS 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"
}

    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 QS 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, such as {cat}, indicate an exact match with q.

      • Characters between square braces, such as [cher], indicate completions.

      • Characters between parentheses, such as (act), indicate corrections to q.

    • The executableConfidence property contains a floating-point value between 0 and 1 which indicates how “convinced” Coveo ML is that performing a query with this suggestion as a q will return relevant results. The threshold from which Coveo ML considers a QS 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 these values match in any given search interface, since the Coveo ML service uses them as filter fields.

Note

The same relationship exists between the tab value used in your Search API requests and the originLevel2 value used in your UA Write API requests.

Troubleshooting example

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

On the usage analytics side, when logging events in these search interfaces, the originlevel1 values specified in your requests are, respectively, BookstoreSearch and MovieStoreSearch.

On the Search API side, this translates into distinctive behavior from one searchHub to another.

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

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

  2. 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 successful Hindi film) is executable and highly recommended, and where Dostoevsky doesn’t figure at all:

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

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

Query suggestion parameters

See the reference documentation for requesting query suggestions.