# Integrating Search Suggest

## Overview <a href="#front-endintegrationspecification-introduction.1" id="front-endintegrationspecification-introduction.1"></a>

The Fredhopper Suggest service will return the defined search suggestions in a [JSON](http://en.wikipedia.org/wiki/JSON)-format HTTP response. Each time a user inputs a keystroke in the search bar on the website, the front-end web application should send a GET HTTP request to the Fredhopper Suggest API with the text value and then display the response that is returned. The system can be designed to give a default response when a user clicks into the search bar but has not yet made a keystroke entry. Please contact your Technical Consultant for more information on how this can be configured. You might also decide to have the front-end wait for the user to type the first 3 characters of the search term before sending the first query to Fredhopper Suggest to retrieve the suggestions to display. This is in order to give them more focused and relevant results.

{% hint style="info" %}
If the Fredhopper Suggest Query Server is not available or does not contain an index, the sample Fredhopper Ajax module will not show the suggest drop down. For custom Ajax modules, it is highly recommended to foresee this situation since it occurs, e.g. during index updates.
{% endhint %}

## Fredhopper Suggest API <a href="#front-endintegrationspecification-fredhoppersuggestapi" id="front-endintegrationspecification-fredhoppersuggestapi"></a>

#### Request <a href="#front-endintegrationspecification-request" id="front-endintegrationspecification-request"></a>

The format to retrieve suggestions for a specific term should be sent in the following query string format:

```
/suggest/json?search=KEYWORD&scope=//UNIVERSE/LOCALE
```

#### Response <a href="#front-endintegrationspecification-response" id="front-endintegrationspecification-response"></a>

The JSON-format response that you receive will contain the suggestions for each defined index in the following format:

{% code overflow="wrap" lineNumbers="true" %}

```json
{"suggestionGroups":[
  {
    "indexName":"<INDEX_NAME>",
    "indexTitle":"<INDEX_NAME>",
    "suggestions":[
      {"<FIELD_A_1>":"<VALUE_A_1>",
       "<FIELD_A_2>":"<VALUE_A_2>"},
      {"<FIELD_B_1>":"<VALUE_B_1>",
       "<FIELD_B_2>":"<VALUE_B_2>"},
      ...
    ]
  },
  ...
]}
```

{% endcode %}

### Example <a href="#front-endintegrationspecification-example" id="front-endintegrationspecification-example"></a>

#### **Request**

The following query string should be sent to get the suggestions for the keyword/keystrokes 'nic' from the universe 'catalog01' in the English (GB) locale:

```
/suggest/json?search=nic&scope=//catalog01/en_GB
```

#### **Response**

In this particular example, the response that is returned contains the following two sections:

* Two keyword suggestions for the terms *nicam* and *nicky*
* One category suggestion for *Mens / Nightwear* (where additional information about the number of results and the Fredhopper Location String have been provided)

{% code overflow="wrap" lineNumbers="true" %}

```json
{"suggestionGroups":[
  {
    "indexName":"Keywords",
    "indexTitle":"Keywords",
    "suggestions":[
      {"searchterm":"nicam"},
      {"searchterm":"nicky"}
    ]
  },
  {
    "indexName":"Categories",
    "indexTitle":"Categories",
    "suggestions":[
      {"nrResults":17,
       "fhLocation":"//catalog01/en_GB/categories<{catalog01_15003}",
       "mlValue":"Mens / Nightwear"}
    ]
  }
]}
```

{% endcode %}

{% hint style="info" %}
It is possible to use our JSCRIPT endpoint alternatively using the following format

`- /suggest/jscript?search=KEYWORD&scope=//UNIVERSE/LOCALE&callback=FUNCTIONNAME`
{% endhint %}

The different sections and the display fields within each section can be customised for your specific requirements. It is possible to make amendments to these at a later stage as requirements and business needs develop over time. You can contact your Technical Consultant for more information on this.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://crownpeak.gitbook.io/product-discovery/building-the-front-end-experience-with-fhr/suggest.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.