---
title: Implement a search box
slug: '1377'
canonical_url: https://docs.coveo.com/en/1377/
collection: build-a-search-ui
source_format: adoc
---
# Implement a search box
A [search interface](https://docs.coveo.com/en/2741/) typically includes a text input from which users can enter and submit [queries](https://docs.coveo.com/en/231/).
This article provides guidelines for implementing a _search box_ on your own, assuming that you can't use the [Coveo JavaScript Search Framework](https://docs.coveo.com/en/187/) or the [Atomic](https://docs.coveo.com/en/lcdf0264/) or [Headless](https://docs.coveo.com/en/lcdf0493/) libraries in your custom search integration with the [Coveo Platform](https://docs.coveo.com/en/186/).

> **Note**
>
> As a reference, you may want to look at the source code of the [`Searchbox`](https://coveo.github.io/search-ui/components/searchbox.html) component to see how it's implemented in the [Coveo JavaScript Search Framework](https://docs.coveo.com/en/187/).

## Standard search box actions

The following table lists some actions that you may want to make available in a search box implementation.

Each entry indicates the specific [Coveo Analytics event](https://docs.coveo.com/en/260/) type, `actionCause`, and `[customData](https://docs.coveo.com/en/1341/)` that [must be logged](https://docs.coveo.com/en/1373/) (if applicable) when the action is performed, as well as a link to the corresponding implementation guidelines.

[%header,cols="5"]
|===
|Search box action
|Event category
|`actionCause`
|`[customData](https://docs.coveo.com/en/1341/)`
|Implementation guidelines

|Submit a [query](https://docs.coveo.com/en/231/)
|Search
|`searchboxSubmit` or `searchFromLink` (standalone search box)
|
|[Submit a query](#submit-a-query)

|Clear the search box
|Search
|`searchboxClear`
|
|[Submit a query](#submit-a-query)

|Select a [query](https://docs.coveo.com/en/231/) correction suggestion
|Search
|`didyoumeanClick`
|
|[Correct queries](#correct-queries)

|Trigger an automatically corrected [query](https://docs.coveo.com/en/231/)
|Search
|`didyoumeanAutomatic`
|
|[Correct queries](#correct-queries)

|Render [Coveo ML](https://docs.coveo.com/en/188/) suggestions
|Search
|
|
|[Provide Coveo Machine Learning query suggestions](#provide-coveo-machine-learning-query-suggestions)

|Select a [Coveo ML](https://docs.coveo.com/en/188/) suggestion
|Search
|`omniboxAnalytics` or `omniboxFromLink` (standalone search box)
|`partialQueries`, `partialQuery`, `suggestionRanking`, `suggestions`
|[Handle Coveo Machine Learning query suggestion selection](#handle-coveo-machine-learning-query-suggestion-selection)

|Render [field](https://docs.coveo.com/en/200/)-based suggestions
|Search
|
|
|[Provide field-based query completion suggestions](#provide-field-based-query-completion-suggestions)

|Select a [field](https://docs.coveo.com/en/200/)-based suggestion
|Search
|`omniboxField`
|
|[Handle field-based query completion suggestion selection](#handle-field-based-query-completion-suggestion-selection)
|===

> **Note**
>
> Using the proper event type, `actionCause`, and `[customData](https://docs.coveo.com/en/1341/)` when logging a [Coveo Analytics event](https://docs.coveo.com/en/260/) for a specific type of action in a [search interface](https://docs.coveo.com/en/2741/) is important.
> Otherwise:
> 
> * [Coveo Analytics reports](https://docs.coveo.com/en/266/) may become incoherent in the underlying [Coveo organization](https://docs.coveo.com/en/185/) (especially if that [organization](https://docs.coveo.com/en/185/) powers both [Coveo JavaScript Search Framework](https://docs.coveo.com/en/187/) interface and custom [search interfaces](https://docs.coveo.com/en/2741/)).
> 
> * The [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) service may not function properly.

## Submit a query

### Non-standalone search box

When the user submits a [query](https://docs.coveo.com/en/231/) from the search box (for example, by clicking **Submit**):

. Retrieve the current value from the search box input.

. Prepare a new [query](https://docs.coveo.com/en/231/).
Ensure that the [`q`](https://docs.coveo.com/en/178/) search request parameter is set to the value retrieved in step 1.

. Call the Search API to [execute the query](https://docs.coveo.com/en/1445/) prepared in step 2.
When the Search API returns:

.. Call the Usage Analytics Write API to [log the corresponding search event](https://docs.coveo.com/en/1502/).
In the request body:

*** Set the `actionCause` property to `searchboxSubmit`.

> **Note**
>
> If the user triggered a [query](https://docs.coveo.com/en/231/) by clearing the search box (for example, by clicking **Clear**), set the `actionCause` property to `searchboxClear` instead.

*** Set other required or optional properties as needed.

.. [Render the query results](https://docs.coveo.com/en/1372#render-query-results).

.. [Render the facets](https://docs.coveo.com/en/3199#request-and-render-facets), if any.

#### Examples of submitting a query from a non-standalone search box

. Executing the [query](https://docs.coveo.com/en/231/) after the expression `catcher rye` has been submitted from the search box:

```http
POST https://myorganizationid9sd8df7s.org.coveo.com/rest/search/v2 HTTP/1.1
​
Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************
```

**Payload (excerpt)**

```json
{
  ...
  "q": "catcher rye",
  "locale": "en-US",
  "searchHub": "BookstoreSearch",
  "tab": "All",
  ...
}
```

**200 OK response body (excerpt)**

```json
{
  ...
  "duration": 145,
  "searchUid": "9862eba6-b30b-491b-94af-33ca2fd61547",
  "results": [
    ...data to render query results...
  ],
  "groupByResults": [
    ...data to render facets...
  ],
  ...
}
```

. Logging a `searchboxSubmit` search [event](https://docs.coveo.com/en/260/) after the Search API has returned:

```http
POST https://myorganizationid9sd8df7s.analytics.org.coveo.com/rest/ua/v15/analytics/search?visitor=28s6g49d-f81s-1435-2r5x153dle72 HTTP/1.1
​
Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************
```

**Payload (excerpt)**

```json
{
  ...
  "actionCause": "searchboxSubmit",
  "queryText": "catcher rye",
  "language": "en",
  "originLevel1": "BookstoreSearch",
  "originLevel2": "All",
  "responseTime": 145,
  "searchQueryUid": "9862eba6-b30b-491b-94af-33ca2fd61547",
  ...
}
```

> **Note**
>
> As shown in this example, whenever logging a search [event](https://docs.coveo.com/en/260/):
> 
> * `queryText` corresponds to [`q`](https://docs.coveo.com/en/178/) in the [query](https://docs.coveo.com/en/231/) request body.
> 
> * `language` corresponds to the language part of `locale` in the [query](https://docs.coveo.com/en/231/) request body.
> 
> * `[originLevel1](https://docs.coveo.com/en/1337/)` corresponds to `[searchHub](https://docs.coveo.com/en/1342/)` in the [query](https://docs.coveo.com/en/231/) request body.
> 
> * `[originLevel2](https://docs.coveo.com/en/1338/)` corresponds to `[tab](https://docs.coveo.com/en/1343/)` in the [query](https://docs.coveo.com/en/231/) request body.
> 
> Moreover:
> 
> * `responseTime` corresponds to the elapsed time (in milliseconds) between the moment the [search interface](https://docs.coveo.com/en/2741/) sent the [query](https://docs.coveo.com/en/231/) to the Search API, and the moment it received the results.
> 
> * `searchQueryUid` corresponds to `searchUid` in the [query](https://docs.coveo.com/en/231/) response body.

### From a standalone search box

When the user submits a [query](https://docs.coveo.com/en/231/) from the standalone search box (for example, by clicking **Submit**):

. Retrieve the current value from the standalone search box input.

. (Optional) If you want the standalone search box to be able to handle [`redirect` query pipeline trigger rules](https://docs.coveo.com/en/3413/):

.. [Get the execution plan of the query](https://platform.cloud.coveo.com/docs?urls.primaryName=Search%20API#/Search/planSearchUsingPost) by sending a GET request to `+https://<orgId>.org.coveo.com/rest/search/v2/plan+`, where `<orgId>` is the unique identifier of your [organization](https://docs.coveo.com/en/185/).

[authenticate](https://docs.coveo.com/en/2120/) the request using an access token that grants the [privilege](https://docs.coveo.com/en/228/) to execute [queries](https://docs.coveo.com/en/231/).
Set the [`q`](https://docs.coveo.com/en/178/) [query](https://docs.coveo.com/en/231/) parameter of the request to the value retrieved in step 1.

.. In the response body, if the `triggers` object of the `preprocessingOutput` property doesn't contain an element whose `type` is `redirect`, skip directly to step 3.
Otherwise, retrieve the `content` value from that element and then:

... Call the Usage Analytics Write API to [log a custom event](https://docs.coveo.com/en/2650/).

In the request body:

**** Set `eventValue` to `redirect`

**** Set `eventType` to `queryPipelineTriggers`

**** In the `[customData](https://docs.coveo.com/en/1341/)` property, set `redirectedTo` to the `content` value retrieved in step 2.b.

**** Set other required or optional properties as needed.

... Skip to step 4, where you'll redirect using the `content` value retrieved in step 2.b.

. Call the Usage Analytics Write API to [log the corresponding search event](https://docs.coveo.com/en/1502/).
In the request body:

** Set the `actionCause` property to `searchFromLink`.

** Set other required or optional properties as needed.

. Redirect the browser.

If you're redirecting to a full [search interface](https://docs.coveo.com/en/2741/) that can display the results, you can forward the [basic query expression (`q`)](https://docs.coveo.com/en/178/) to the interface by passing it as a [query](https://docs.coveo.com/en/231/) parameter in the URL and ensuring that the target interface is able to retrieve and parse it.

## Correct queries

The _DidYouMean_ [query](https://docs.coveo.com/en/231/) feature enables the Search API to check for a possible [query](https://docs.coveo.com/en/231/) correction if a [query](https://docs.coveo.com/en/231/) returns no results.
You can configure this feature to either suggest the correction, or automatically trigger a new [query](https://docs.coveo.com/en/231/) with the suggested term.
The DidYouMean feature involves the `enableDidYouMean` (Boolean) search request parameter.

When `enableDidYouMean` is set to `true`, the Search API returns the `queryCorrections` object in the [query](https://docs.coveo.com/en/231/) response body if no results are returned (for example, `"totalCount": 0`).

To suggest the [query](https://docs.coveo.com/en/231/) correction in the [search interface](https://docs.coveo.com/en/2741/) after a user has entered a [query](https://docs.coveo.com/en/231/) that returned no results:

. Retrieve the value of the `correctedQuery` parameter from within the `queryCorrections` [query](https://docs.coveo.com/en/231/) response object.

. Use the value from Step 1 to output a message suggesting the corrected [query](https://docs.coveo.com/en/231/).
This message should include a link.
When the user clicks that link:

.. Prepare a new [query](https://docs.coveo.com/en/231/).
Ensure that the [`q`](https://docs.coveo.com/en/178/) search request parameter is set to the value retrieved in step 1 (see [Submit a query](#submit-a-query)).

.. Call the Search API to [execute the query](https://docs.coveo.com/en/1445/) prepared in step 2.
When the Search API returns:

... Call the Usage Analytics Write API to [log the corresponding search event](https://docs.coveo.com/en/1502/).
In the request body:

**** Set the `actionCause` property to `didyoumeanClick`.

**** Set other required or optional properties as needed.

> **Note**
>
> You may want to use the `wordCorrections` array from the `queryCorrections` object to output a string indicating what was wrong in the original [query](https://docs.coveo.com/en/231/).

Alternatively, you can enable your [search interface](https://docs.coveo.com/en/2741/) to automatically correct [queries](https://docs.coveo.com/en/231/) and display results without requiring the user to interact more with the [search interface](https://docs.coveo.com/en/2741/).
To do so, follow the preceding steps but make the following changes:

* Automatically trigger the [query](https://docs.coveo.com/en/231/) from Step 2.a, rather than wait for a user to select a correction link.

* Set the `actionCause` property to `didyoumeanAutomatic` when logging the corresponding search [event](https://docs.coveo.com/en/260/) from Step 2.b.i.

> **Note**
>
> You should typically output a string to the user indicating that the [query](https://docs.coveo.com/en/231/) was automatically corrected.

### Examples of correcting queries

. Executing a [query](https://docs.coveo.com/en/231/) after the expression `The Shning` has been submitted from the search box:

```http
POST https://myorganizationid9sd8df7s.org.coveo.com/rest/search/v2?organizationId=myorganizationid HTTP/1.1
​
Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************
```

**Payload (excerpt)**

```json
{
  "aq": "@source==\"MovieSource\"",
  "q": "Shning",
  "enableDidYouMean": true
  // additional parameters...
}
```

**200 OK response body (excerpt)**

```json
{
  "totalCount": 0,
  ...
  "queryCorrections": [
    {
      "correctedQuery": "shining",
      "wordCorrections": [
        {
          "offset": 0,
          "length": 7,
          "originalWord": "shning",
          "correctedWord": "shining"
        }
      ]
    }
  ],
  ...
}
```

. Using the `correctedWord` value as the [`q`](https://docs.coveo.com/en/178/) parameter for the new [query](https://docs.coveo.com/en/231/):

```http
POST https://myorganizationid9sd8df7s.org.coveo.com/rest/search/v2?organizationId=myorganizationid HTTP/1.1
​
Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************
```

**Payload (excerpt)**

```json
{
  "aq": "@source==\"MovieSource\"",
  "q": "shining",
  "enableDidYouMean": true
  // additional parameters...
}
```

**200 OK response body (excerpt)**

```json
{
"totalCount": 1,
...
"results": [
  {
    "title": "The Shining",
    ...
  }
],
...
}
```

. Logging a `didyoumeanAutomatic` custom [event](https://docs.coveo.com/en/260/) after the Search API has returned:

```http
POST https://myorganizationid9sd8df7s.analytics.org.coveo.com/rest/ua/v15/analytics/search?visitor=28s6g49d-f81s-1435-2r5x153dle72 HTTP/1.1
​
Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************
```

**Payload (excerpt)**

```json
{
  ...
  "actionCause": "didyoumeanAutomatic",
  "queryText": "The Shining",
  "language": "en",
  "originLevel1": "MoviestoreSearch",
  "originLevel2": "Classics",
  "responseTime": 118,
  "searchQueryUid": "8c2f6897-203d-4d5c-db56-5b3e39831345",
  ...
}
```

## Provide Coveo Machine Learning query suggestions

Once you've logged enough [data](https://docs.coveo.com/en/259/) in your [Coveo organization](https://docs.coveo.com/en/185/), and created a [Coveo Machine Learning](https://docs.coveo.com/en/1727/) [Query Suggestions (QS)](https://docs.coveo.com/en/1015/) [model](https://docs.coveo.com/en/1012/), you can assist users by providing them with highly relevant, [Coveo ML](https://docs.coveo.com/en/188/)-powered [query suggestions](https://docs.coveo.com/en/1015/) as they're typing in the search box.

> **Note**
>
> No [event](https://docs.coveo.com/en/260/) needs to be logged when requesting [Coveo ML](https://docs.coveo.com/en/188/)-based [query suggestions](https://docs.coveo.com/en/1015/).

To do so, on each valid keystroke in the search box:

. Retrieve the current value from the search box input.

. Resolve the current `[searchHub](https://docs.coveo.com/en/1342/)`, `[tab](https://docs.coveo.com/en/1343/)`, and `locale` (and, optionally, the `[referrer](https://docs.coveo.com/en/1344/)` and `[context](https://docs.coveo.com/en/1345/)`) search request parameters.

. Call the Search API to [get query suggestions](https://docs.coveo.com/en/1459/).
In the request body:

--
** Set the [`q`](https://docs.coveo.com/en/178/) property to the value retrieved in step 1.

** Set the `[searchHub](https://docs.coveo.com/en/1342/)`, `[tab](https://docs.coveo.com/en/1343/)`, and `locale` (and, optionally, `[referrer](https://docs.coveo.com/en/1344/)` and `[context](https://docs.coveo.com/en/1345/)` for finer granularity) parameters to the values resolved in step 2 to get contextually relevant [Coveo ML](https://docs.coveo.com/en/188/)-based [query suggestions](https://docs.coveo.com/en/1015/).

** The `enableWordCompletion` property is set to `true` by default.
When enabled, the top [query suggestion](https://docs.coveo.com/en/1015/) in the request response will be the one that best completes the last word being typed by the user in the search box.
If you set this property to `false`, the top [query](https://docs.coveo.com/en/231/) completion suggestion will instead be the one deemed most _relevant_ by the [QS](https://docs.coveo.com/en/1015/) [model](https://docs.coveo.com/en/1012/), even if this [query suggestion](https://docs.coveo.com/en/1015/) doesn't actually _complete_ the [query](https://docs.coveo.com/en/231/).
--

> **Important**
>
> When calling the Search API to get [query suggestions](https://docs.coveo.com/en/1015/), the request must be routed to a [query pipeline](https://docs.coveo.com/en/180/) in which a [Coveo ML](https://docs.coveo.com/en/188/) [QS](https://docs.coveo.com/en/1015/) [model](https://docs.coveo.com/en/1012/) is configured and ready.
> Otherwise, the request will return an empty `completions` array.

. When the Search API returns, use the `expression` and/or `highlighted` properties of each element in the ordered `completions` array of the response body to render [query suggestions](https://docs.coveo.com/en/1015/) in a dedicated list.

> **Note**
>
> 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`](https://docs.coveo.com/en/178/).
> 
> ** Characters between square brackets, such as `[cher]`, indicate completions.
> 
> ** Characters between parentheses, such as `(act)`, indicate corrections to [`q`](https://docs.coveo.com/en/178/).
> 
> * The `executableConfidence` property contains a floating-point value between `0` and `1` indicating how "convinced" [Coveo ML](https://docs.coveo.com/en/188/) is that performing a [query](https://docs.coveo.com/en/231/) with this suggestion as a [basic query expression (`q`)](https://docs.coveo.com/en/178/) will return relevant results.
> The threshold at which [Coveo ML](https://docs.coveo.com/en/188/) considers a [query suggestion](https://docs.coveo.com/en/1015/) executable is `0.8`.
>  
> You could use this property to include a reliable [search-as-you-type](https://docs.coveo.com/en/2068/) feature in your search box implementation.

### Example of providing Coveo ML query suggestions

Requesting [Coveo ML](https://docs.coveo.com/en/188/)-based [query suggestions](https://docs.coveo.com/en/1015/):

```http
POST https://myorganizationid9sd8df7s.org.coveo.com/rest/search/v2/querySuggest HTTP/1.1
​
Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************
```

**Payload**

```json
{
  "q": "cat",
  "locale": "en-US",
  "searchHub": "BookstoreSearch",
  "tab": "All",
  "referrer": "https://example.com/books/classics/authors/Salinger_J_D/",
  "context": {
    "userType": "Premium"
  },
  "enableWordCompletion": false
}
```

**Successful response - 200 OK**

```json
{
  "completions": [
    {
      "expression": "catcher in the rye",
      "score": 14.811407079917723,
      "highlighted": "{cat}[cher] [in] [the] [rye]",
      "executableConfidence": 1
    },
    {
      "expression": "dream catcher",
      "score": 14.135665512605295,
      "highlighted": "[dream] {cat}[cher]",
      "executableConfidence": 1.0
    },
    {
      "expression": "catch-22",
      "score": 13.576942132468472,
      "highlighted": "{cat}[ch-22]",
      "executableConfidence": 1
    },
    {
      "expression": "cat in the hat",
      "score": 12.879732037029243,
      "highlighted": "{cat} [in] [the] [hat]",
      "executableConfidence": 1.0
    },
    {
      "expression": "the children act",
      "score": 12.325728875625282,
      "highlighted": "[the] [children] (act)",
      "executableConfidence": 0.6666666666666666
    },
  ]
}
```

### Handle Coveo Machine Learning query suggestion selection

When the user selects a [query suggestion](https://docs.coveo.com/en/1015/), such as by clicking one of the rendered suggestions:

. Set the search box input value to the [query suggestion](https://docs.coveo.com/en/1015/) that the user has selected.

. Prepare a new [query](https://docs.coveo.com/en/231/).
Ensure that the [`q`](https://docs.coveo.com/en/178/) search request parameter is set to the expression generated in step 1.

. Call the Search API to [execute the query](https://docs.coveo.com/en/1445/) prepared in step 2.
When the Search API returns:

.. Call the Usage Analytics Write API to [log the corresponding search event](https://docs.coveo.com/en/1502/).

In the request body:

*** Set the `actionCause` property to `omniboxAnalytics` (or `omniboxFromLink` in a standalone search box).

*** Include the following key-value pairs in the `[customData](https://docs.coveo.com/en/1341/)` property:

--
**** `"partialQueries": <partialQueries>`

**** `"partialQuery": <partialQuery>`

**** `"suggestionRanking": <suggestionRanking>`

**** `"suggestions": <suggestions>`
--

where:

--
**** `<partialQueries>` (semicolon-separated ordered list of strings) contains the [`q`](https://docs.coveo.com/en/178/) value of each Search API [query suggestion](https://docs.coveo.com/en/1015/) request that returned at least one suggestion, before a suggestion was selected.

**** `<partialQuery>` (string) is the [`q`](https://docs.coveo.com/en/178/) value of the last Search API [query suggestion](https://docs.coveo.com/en/1015/) request made before a suggestion was selected.

**** `<suggestionRanking>` (unsigned integer) is the 0-based [index](https://docs.coveo.com/en/204/) position of the suggestion that was selected in the `completions` array.

**** `<suggestions>` (semicolon-separated ordered list of strings) contains the `expression` value of each [item](https://docs.coveo.com/en/210/) in the response of the last Search API [query suggestion](https://docs.coveo.com/en/1015/) request.
--

**Example**

A user types `c`, `i`, `[backspace]`, `o`, and `v` in the search box.
At this point, the following ordered list of [query suggestions](https://docs.coveo.com/en/1015/) is displayed:

* `coveo for salesforce`

* `coveo for sitecore`

* `coveo`

* `coveo for servicenow`

* `coveo for zendesk`

The user selects the third item in the list (`coveo`).

In the `[customData](https://docs.coveo.com/en/1341/)` property of the search [event](https://docs.coveo.com/en/260/) that gets logged when the triggered query returns:

* `<partialQueries>` would have to be set to `c;ci;c;co;cov`.

* `<partialQuery>` would have to be set to `cov`.

* `<suggestionRanking>` would have to be set to `2`.

* `<suggestions>` would have to be set to `coveo for salesforce;coveo for sitecore;coveo;coveo for servicenow;coveo for zendesk`.

**** Set other required or optional properties as needed.

.. [Render the query results](https://docs.coveo.com/en/1372#render-query-results).

.. [Render the facets](https://docs.coveo.com/en/3199#request-and-render-facets), if any.

#### Examples of handling Coveo ML query suggestion selection

. Executing a [query](https://docs.coveo.com/en/231/) after the `dream catcher` [query](https://docs.coveo.com/en/231/) completion suggestion has been selected:

```http
POST https://myorganizationid9sd8df7s.org.coveo.com/rest/search/v2 HTTP/1.1
​
Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************
```

**Payload (excerpt)**

```json
{
  ...
  "q": "dream catcher",
  "firstResult": 0,
  "locale": "en-US",
  "searchHub": "BookstoreSearch",
  "tab": "All",
  "referrer": "https://example.com/books/classics/authors/Salinger_J_D/",
  "context": {
    "userType": "Premium"
  },
  ...
}
```

. Logging an `omniboxAnalytics` search [event](https://docs.coveo.com/en/260/) after the Search API has returned:

```http
POST https://myorganizationid9sd8df7s.analytics.org.coveo.com/rest/ua/v15/analytics/search?visitor=28s6g49d-f81s-1435-2r5x153dle72 HTTP/1.1
​
Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************
```

**Payload (excerpt)**

```json
{
  ...
  "actionCause": "omniboxAnalytics",
  "customData": {
    ...
    "partialQueries": "c;ca;car;ca;cat",
    "partialQuery": "cat",
    "suggestionRanking": 1,
    "suggestions": "catcher in the rye;dream catcher;catch-22;cat in the hat;the children act",
    "context_userType": "Premium",
    ...
  },
  "queryText": "dream catcher",
  "language": "en",
  "originLevel1": "BookstoreSearch",
  "originLevel2": "All",
  "responseTime": 97,
  "searchQueryUid": "153fdc38-8eb9-428a-942d-19a6ddb59fe9",
  ...
}
```

> **Note**
>
> As shown in this example, when logging a search [event](https://docs.coveo.com/en/260/), `[customData](https://docs.coveo.com/en/1341/)` must contain a corresponding `context_`-prefixed key along with its value for each key-value pair in the `[context](https://docs.coveo.com/en/1345/)` object of the [query](https://docs.coveo.com/en/231/) request body.

## Provide field-based query completion suggestions

Typically, you should only use [Coveo ML](https://docs.coveo.com/en/188/) [QS](https://docs.coveo.com/en/1015/) in your search box implementation, as it's both powerful and relatively easy to implement (see [Provide Coveo Machine Learning query suggestions](#provide-coveo-machine-learning-query-suggestions)).
However, it's also possible (although not necessarily recommended) to assist users by providing them with [field](https://docs.coveo.com/en/200/)-based [query](https://docs.coveo.com/en/231/) completion suggestions as they're typing in the search box.

**Example**

In a bookstore [search interface](https://docs.coveo.com/en/2741/), you may want to suggest `@author` [field](https://docs.coveo.com/en/200/) values that match what the user is typing.

> **Note**
>
> No [event](https://docs.coveo.com/en/260/) needs to be logged when requesting [field](https://docs.coveo.com/en/200/) values.

To render [field](https://docs.coveo.com/en/200/)-based [query](https://docs.coveo.com/en/231/) completion suggestions, on each valid keystroke in the search box:

. Retrieve the current value from the search box input.

. Modify the retrieved value to a wildcard expression.
For example, if the value retrieved in step 1 was `a`, set it to `+**a**+`.

> **Note**
>
> These guidelines assume that you're using the `wildcards` `patternType` when requesting [field](https://docs.coveo.com/en/200/) values from the Search API, because this is how [field](https://docs.coveo.com/en/200/) suggestions are implemented in the [Coveo JavaScript Search Framework](https://docs.coveo.com/en/187/) (see the [`FieldsSuggestion`](https://coveo.github.io/search-ui/components/fieldsuggestions) component).
> You can use any other valid `patternType` value (`regularExpression`, `editDistance`, or `phonetic`) in your own implementation if you so desire.

. If your [search interface](https://docs.coveo.com/en/2741/) [includes tabs](https://docs.coveo.com/en/1382/), retrieve the [filter](https://docs.coveo.com/en/2736/) expression enforced by the currently selected [tab](https://docs.coveo.com/en/1406/).

. Call the Search API to [get matching field values](https://docs.coveo.com/en/13#operation/valuesGet).
In the request body:

** Set the `patternType` property to `wildcards`.

** Set the `pattern` property to the value modified in step 2 (for example, `+**a**+`).

** Set the `field` property to the `@`-prefixed name of the [field](https://docs.coveo.com/en/200/) from which to retrieve [query](https://docs.coveo.com/en/231/) completion suggestions (for example, `@author`).

> **Important**
>
> [#initial]#[field](https://docs.coveo.com/en/200/)#-based [query](https://docs.coveo.com/en/231/) completion suggestions can only be retrieved from [fields](https://docs.coveo.com/en/200/) whose [`facet`](https://docs.coveo.com/en/8#tag/Fields/operation/createField-facet) option is set to `true`.

** Set the `sortCriteria` property to `occurrences` to ensure that [field](https://docs.coveo.com/en/200/) suggestions are returned in a logical order.

** Set the `maximumNumberOfValues` property to a relatively low value (for example, `5`) to ensure that only a useful number of [field](https://docs.coveo.com/en/200/) suggestions are requested.

** When users may use accented characters, set the `ignoreAccents` property to `true` to ensure that accented characters are treated as non-accented characters when retrieving [field](https://docs.coveo.com/en/200/) values.
For example, when `ignoreAccents` is set to `true`, using `+**élo**+` or `+**elo**+` as a `pattern` value is equivalent; both may return [field](https://docs.coveo.com/en/200/) values such as `Hello` or `Éloïse`.

** If your [search interface](https://docs.coveo.com/en/2741/) [includes tabs](https://docs.coveo.com/en/1382/), set the `queryOverride` property to the value retrieved in step 3 to ensure that only [field](https://docs.coveo.com/en/200/) suggestions matching the expression enforced by the currently selected tab are returned.

. When the Search API returns, use the `value` property of each element in the ordered `values` array of the response body to render [field](https://docs.coveo.com/en/200/) suggestions in a dedicated list.

### Example of providing field-based query completion suggestions

Requesting [query](https://docs.coveo.com/en/231/) completion suggestions based on the `@author` [field](https://docs.coveo.com/en/200/):

```http
POST https://myorganizationid9sd8df7s.org.coveo.com/rest/search/v2/values HTTP/1.1
​
Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************
```

**Payload**

```json
{
  "patternType": "wildcards",
  "pattern": "*a*",
  "field": "@author",
  "sortCriteria": "occurrences",
  "maximumNumberOfValues": 5,
  "ignoreAccents": true,
  "queryOverride": "@source==\"Classics\""
}
```

**Successful response - 200 OK**

```json
{
  "values": [
    {
      "value": "Mark Twain",
      "lookupValue": "Mark Twain",
      "numberOfResults": 25
    },
    {
      "value": "Charles Dickens",
      "lookupValue": "Charles Dickens",
      "numberOfResults": 21
    },
    {
      "value": "Jane Austen",
      "lookupValue": "Jane Austen",
      "numberOfResults": 12
    },
    {
      "value": "Charlotte Brontë",
      "lookupValue": "Charlotte Brontë",
      "numberOfResults": 8
    },
    {
      "value": "Mary Shelley",
      "lookupValue": "Mary Shelly",
      "numberOfResults": 5
    }
  ]
}
```

### Handle field-based query completion suggestion selection

When the user selects a specific [field](https://docs.coveo.com/en/200/)-based [query](https://docs.coveo.com/en/231/) completion suggestion (for example, by clicking one of the rendered values):

. Generate an expression from the [field](https://docs.coveo.com/en/200/) value the user has selected (for example, `Alice Smith`).

. Set the search box input value to the [query](https://docs.coveo.com/en/231/) expression generated in step 1.

. Prepare a new [query](https://docs.coveo.com/en/231/).
Ensure that the [`q`](https://docs.coveo.com/en/178/) search request parameter is set to the expression generated in step 1.

> **Note**
>
> If the expression generated in step 1 uses advanced [query syntax](https://docs.coveo.com/en/181/) (for example, `@author=="Alice Smith"`), also ensure that the `enableQuerySyntax` search request parameter is set to `true` before the [query](https://docs.coveo.com/en/231/) is executed.

. Call the Search API to [execute the query](https://docs.coveo.com/en/1445/) prepared in step 3.
When the Search API returns:

.. Call the Usage Analytics Write API to [log the corresponding search event](https://docs.coveo.com/en/1502/).
In the request body:

*** Set the `actionCause` property to `omniboxField`.

*** Set other required or optional properties as needed.

.. [Render the query results](https://docs.coveo.com/en/1372#render-query-results).

.. [Render the facets](https://docs.coveo.com/en/3199#request-and-render-facets), if any.

#### Examples of handling field-based query completion suggestion selection

. Executing a [query](https://docs.coveo.com/en/231/) after the `Charles Dickens` [query](https://docs.coveo.com/en/231/) completion suggestion has been selected:

```http
POST https://myorganizationid9sd8df7s.org.coveo.com/rest/search/v2 HTTP/1.1
​
Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************
```

**Payload (excerpt)**

```json
{
  ...
  "q": "@author==\"Charles Dickens\"",
  "enableQuerySyntax": true,
  "firstResult": 0,
  "locale": "en-US",
  "searchHub": "BookstoreSearch",
  "tab": "Classics",
  ...
}
```

> **Note**
>
> In this example, the [basic query expression (`q`)](https://docs.coveo.com/en/178/) generated from the selected [field](https://docs.coveo.com/en/200/) value uses advanced [query syntax](https://docs.coveo.com/en/181/) (`@author=="Charles Dickens"`).
> Therefore, the `enableQuerySyntax` search request parameter is set to `true` to ensure that the Search API parses this expression correctly.

. Logging an `omniboxField` search [event](https://docs.coveo.com/en/260/) after the Search API has returned:

```http
POST https://myorganizationid9sd8df7s.analytics.org.coveo.com/rest/ua/v15/analytics/search?visitor=28s6g49d-f81s-1435-2r5x153dle72 HTTP/1.1
​
Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************
```

**Payload (excerpt)**

```json
{
  ...
  "actionCause": "omniboxField",
  "queryText": "@author==\"Charles Dickens\"",
  "language": "en",
  "originLevel1": "BookstoreSearch",
  "originLevel2": "Classics",
  "responseTime": 118,
  "searchQueryUid": "8c8f5897-233d-4b4c-bd56-5b3e39885345",
  ...
}
```

## Enable advanced search box features

Several search request parameters can have a direct and significant impact on the way the Search API and the [index](https://docs.coveo.com/en/204/) interpret the basic part of the query expression ([`q`](https://docs.coveo.com/en/178/)).
Therefore, in a typical [search interface](https://docs.coveo.com/en/2741/), those search request parameters should logically be configurable through the search box.

You may want to ensure that your search box implementation includes options to enable and take advantage of the following features.

### Partial match

The _partial match_ feature can help the [index](https://docs.coveo.com/en/204/) find [items](https://docs.coveo.com/en/210/) that match the basic part of the query expression ([`q`](https://docs.coveo.com/en/178/)), even when the expression is fairly wordy.
This feature involves the following search request parameters:

* `partialMatch` (Boolean)

* `partialMatchKeywords` (unsigned integer)

* `partialMatchThreshold` (unsigned integer or string [percentage])

When `partialMatch` is set to `true` and the [`q`](https://docs.coveo.com/en/178/) value contains at least `partialMatchKeywords` (for example, `5`), [items](https://docs.coveo.com/en/210/) only need to match `partialMatchThreshold` (for example, `50%`, rounded up) of those [keywords](https://docs.coveo.com/en/2738/) to match the [basic query expression (`q`)](https://docs.coveo.com/en/178/).

> **Note**
>
> The partial match feature:
> 
> * Applies after the [query](https://docs.coveo.com/en/231/) has been fully processed by the [query pipeline](https://docs.coveo.com/en/180/).
> 
> * Has no effect when `enableQuerySyntax` is set to `true` and [`q`](https://docs.coveo.com/en/178/) contains advanced [query syntax](https://docs.coveo.com/en/181/).

#### Partial match example

Enabling the partial match feature:

**Query payload**

```json
{
  "q": "the life and strange surprising adventures of robinson crusoe of york mariner",
  "partialMatch": true,
  "partialMatchKeywords": "3",
  "partialMatchThreshold": "35%"
}
```

In this example, since `partialMatch` is set to `true` and [`q`](https://docs.coveo.com/en/178/) contains `12` [keywords](https://docs.coveo.com/en/2738/):

* The [basic query expression (`q`)](https://docs.coveo.com/en/178/) is converted to a partial match expression (`12` is greater than the `partialMatchKeywords` value of `3`).

* Any [item](https://docs.coveo.com/en/210/) matching a minimum of `5` [keywords](https://docs.coveo.com/en/2738/) in the partial match expression (that is, the `partialMatchThreshold` value of `35%` multiplied by `12`, and then rounded up) will match the expression.

This means that, for example, an [item](https://docs.coveo.com/en/210/) which contains the [keywords](https://docs.coveo.com/en/2738/) `the adventures of robinson crusoe` will match the expression.

### Wildcards

The _wildcards_ feature allows the [index](https://docs.coveo.com/en/204/) to [recognize wildcards characters](https://docs.coveo.com/en/1580/) in the basic part of the query expression ([`q`](https://docs.coveo.com/en/178/)) and expand the expression accordingly.
This feature involves the following search request parameters:

* `wildcards` (Boolean)

* `questionMark` (Boolean)

When `wildcards` is set to `true`, `*` characters in [`q`](https://docs.coveo.com/en/178/) are interpreted as wildcards.

When `questionMark` is also set to `true`, `?` characters in [`q`](https://docs.coveo.com/en/178/) are also treated as wildcards.

> **Note**
>
> Setting `questionMark` to `true` has no effect unless `wildcards` is also set to `true`.

#### Wildcards example

Enabling and using the `*` and `?` wildcards:

**Query payload**

```json
{
  "q": "?obi*",
  "wildcards": true,
  "questionMark": true,
}
```

In this example, since `wildcards` and `questionMark` are both set to `true`, [`q`](https://docs.coveo.com/en/178/) is expanded so that [items](https://docs.coveo.com/en/210/) containing keywords such as `robin`, `robinson`, `jobim`, or `mobile`, will match the expression.

### Advanced query syntax

The _advanced query syntax_ feature allows the [index](https://docs.coveo.com/en/204/) to recognize [Coveo query syntax](https://docs.coveo.com/en/181/) in the basic part of the query expression ([`q`](https://docs.coveo.com/en/178/)) and interpret the expression accordingly.
This feature involves the following search request parameters:

* `enableQuerySyntax` (Boolean)

* `lowercaseOperators` (Boolean)

When `enableQuerySyntax` is set to `true`, [Coveo query syntax](https://docs.coveo.com/en/181/) in [`q`](https://docs.coveo.com/en/178/) is interpreted as such.

When `lowercaseOperators` is also set to `true`, Boolean operators (`NEAR`, `NOT`, `AND`, and `OR`) in [`q`](https://docs.coveo.com/en/178/) are always interpreted as such, even if they appear in lowercase (see [Query syntax](https://docs.coveo.com/en/1552/)).

> **Notes**
>
> * In most public deployments, `enableQuerySyntax` should be set to `false` by default.
>  
> Typically, users aren't going to be aware of [Coveo query syntax](https://docs.coveo.com/en/181/) and will either not use it, or use it inappropriately.
> Exact phrase match requests ([keywords](https://docs.coveo.com/en/2738/) between double quotes) are still going to work even if `enableQuerySyntax` is set to `true`, and [wildcards](#wildcards) (`*` and `?`) can also be enabled independently.
> 
> * Setting `lowercaseOperators` to `true` has no effect unless `enableQuerySyntax` is also set to `true`.

#### Advanced query syntax example

. Enabling and using advanced [query syntax](https://docs.coveo.com/en/181/):

**Query payload**

```json
{
  "q": "@title=prometheus NOT (@author=Shelley)",
  "enableQuerySyntax": true
}
```

In this example, since `enableQuerySyntax` is set to `true`, [`q`](https://docs.coveo.com/en/178/) is parsed so that [items](https://docs.coveo.com/en/210/) whose title contains the [keyword](https://docs.coveo.com/en/2738/) `prometheus` and whose author name doesn't contain the [keyword](https://docs.coveo.com/en/2738/) `Shelley` will match the expression.

This means that book [items](https://docs.coveo.com/en/210/) corresponding to _Frankenstein or the Modern Prometheus_ (by Mary Shelley) and _Prometheus Unbound_ (by Percy Bysshe Shelley) won't match the expression.
However, a book [item](https://docs.coveo.com/en/210/) such as _The Prometheus Effect_ (by David Fleming) will match the expression.

. Enabling and using lowercase operators:

**Query payload**

```json
{
  "q": "doctor strangelove or how i learned to stop worrying and love the bomb",
  "enableQuerySyntax": true,
  "lowercaseOperators": true
}
```

In this example, because `enableQuerySyntax` and `lowercaseOperators` are both set to `true`, the Search API parses the [basic query expression (`q`)](https://docs.coveo.com/en/178/) as follows: `(doctor strangelove) OR (how i learned to stop worrying) AND (love the bomb)`, which is likely not what the user wants.
Setting `lowercaseOperators` to `true` should only be done under specific circumstances and is typically not recommended.