> For the complete documentation index, see [llms.txt](https://fredhopper.gitbook.io/product-discovery/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fredhopper.gitbook.io/product-discovery/resources/archived-pages/introduction/api/product-suggest-api.md).

# Product Suggest API

## Product suggest

<mark style="color:green;">`POST`</mark> `https://api-eu.attraqt.io/search/suggest`

Search and group suggested products using the XO Search engine.

#### Request Body

| Name                       | Type   | Description                                                                                                                                                                                                                                                                                                                                                          |
| -------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token                      | string | XO Search token (can be found in the XO Console)                                                                                                                                                                                                                                                                                                                     |
| query                      | string | The query string used for the search                                                                                                                                                                                                                                                                                                                                 |
| options.sortBy             | array  | <p><strong>Sorting:</strong></p><p>\</p></p><p>Sort the results using the specified sort options.</p><p>\</p></p><p><em>Defaults to an empty array (no sort applied, ie. results are sorted by relevancy).</em></p><p>\</p></p><p>Check</p><p><em>Sorting</em></p><p>page for more info about the</p><p><strong><code>sortBy</code></strong></p><p>array format.</p> |
| options.filter             | string | <p><strong>Filtering:</strong></p><p>\</p></p><p>Filters the results based on the filter query (SQL-like syntax).</p><p>\</p></p><p><em>Defaults to an empty array (no filter applied).</em></p><p>\</p></p><p>Check</p><p><em>Filtering</em></p><p>page for more info about the</p><p><strong><code>filter</code></strong></p><p>string format.</p>                 |
| options.customResponseMask | string | <p><strong>Attributes to retrieve:</strong></p><p>\</p></p><p>If specified, you have the control which attributes to retrieve and which not to retrieve.</p>                                                                                                                                                                                                         |
| options.groupBy            | object | <p><strong>Grouping:</strong></p><p>\</p></p><p>Group the results by specific values.</p><p>\</p></p><p>Check</p><p><em>Grouping</em></p><p>page for more info about the format</p>                                                                                                                                                                                  |

#### Example product suggest request

The following sample request includes all possible parameters you can use

```http
POST https://api-eu.attraqt.io/search/suggest HTTP/1.1
Content-Type: application/json; charset=UTF-8

{
    "token": "SEARCH_API_TOKEN",
    "query": "t-shirt",
    "options": {
        "customResponseMask": "id, product(title, price, photo)",
        "filter": "price > 50",
        "sortBy": [
            {
                "attribute": "price",
                "order": "asc"
            }
        ],
        "groupBy": {
            "attribute": "kind",
            "size": 3,
            "values": ["product", "box"]
        }
    }
}
```

## Response

The product suggest response contains two parts:

| Property       | Type     | Description                                                                                         |
| -------------- | -------- | --------------------------------------------------------------------------------------------------- |
| **`groups`**   | `array`  | Array of groups fetched from the catalog. Depends on the **`groupBy`** options of the request.      |
| **`metadata`** | `object` | Metadata about the search request: available facets, pagination, number of items, elapsed time, ... |

### **`groups`**

The groups matching the product suggest query.

| Property    | Type     | Description                                                                                                                      |
| ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **`value`** | `string` | Value on which this group was aggregated                                                                                         |
| **`count`** | `number` | Number of items included in this group. Note that only the first **`size`** items are returned, not all items of the group.      |
| **`items`** | `array`  | List of items returned for this group. This array has the same format as the **`items`** returned for a regular search response. |

### **`metadata`**

Metadata about the search query and its results.

| Property              | Type     | Description                                              |
| --------------------- | -------- | -------------------------------------------------------- |
| **`time`**            | `number` | Time the request took to complete (in milliseconds)      |
| **`token`**           | `string` | Search API token used for the request                    |
| **`url`**             | `string` | Equivalent url that can be used to send the same request |
| **`id`**              | `string` | Unique identifier                                        |
| **`configurationId`** | `string` | Search configuration id used                             |

### Example

{% tabs %}
{% tab title="JSON Format" %}

```javascript
{
  "groups": [
    {
      "value": "product",
      "count": 150,
      "items": [
        {
          "id": "item 1",
          "score": 5.123,
          "kind": "product",
          "context": "default",
          "product": {
            ...
          }
        },
        ...
      ]
    },
  ...
  ],
  "metadata": {
    "id": "573e30b1-7d97-46a0-bbe0-110527150534",
    "configurationId": "cddda87b-c99d-45aa-bf45-cd53d2bc8ace",
    "token": "a28570e6ac94e8d86c19e820",
    "time": 15,
    "url": "",
  }
}
```

{% endtab %}
{% endtabs %}