> 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-parameters/grouping.md).

# Grouping

Group results by values of a specified attribute

{% hint style="warning" %}
This feature is only available for the **Product Suggest API**
{% endhint %}

## Parameters

The **`groupBy`** parameter allows to group the results by values of any single-valued facetable attribute. Each value will return a group of items containing this value.

| **Name**      | Type           | Is Required ? |
| ------------- | -------------- | ------------- |
| **`groupBy`** | `GroupOptions` | ✅             |

### `groupBy`

Grouping options, must be a *JSON* object with the following properties:

| Property    | Type             | Description                                               |
| ----------- | ---------------- | --------------------------------------------------------- |
| `attribute` | `string`         | Name of the attribute used for grouping                   |
| `values`    | list of `string` | List of values (of the attribute) to group by             |
| `size`      | `integer`        | Size of each group. Must be between 1 and 100 (inclusive) |

#### Notes

* The maximum number of items returned is 100, no matter the `size` or number of `values`. For example, requesting 50 `values` with `size` 5 will return only 2 items per group (and 50 groups)
* `attribute` must be a single-valued facetable attribute. Lists and sets attributes can't be used for grouping

## Response

All responses from XO Search uses the same format.\
Check [API Reference](/product-discovery/resources/archived-pages/introduction/api.md) page for a more detailed description of this format.

{% content-ref url="/pages/9oz6YlEAkw7zR7txwjhG" %}
[API Reference](/product-discovery/resources/archived-pages/introduction/api.md)
{% endcontent-ref %}

## Usage example

* Group results by 2 different `kind`: `"box"` and `"product"`

{% tabs %}
{% tab title="SDK - JS" %}
**NodeJS / NPM example**

```typescript
import { search } from '@attraqt/search';

const query = 'T-shirt';

search.init({ token: SEARCH_API_TOKEN });

const response = await search.suggest(query, {
  groupBy: {
    attribute: 'kind',
    size: 5,
    values: ['product', 'box']
  }
});

console.log(response);
```

**HTML example**

```markup
<script type="text/javascript">
    xo.init({
        search: {
            token: 'SEARCH_API_TOKEN'
        }
    });

    xo.search.suggest('T-Shirt', {
        groupBy: {
            attribute: 'kind',
            size: 5,
            values: ['product', 'box']
        }
    }).then((response) => {
        console.log(response);
    });
</script>
```

{% endtab %}

{% tab title="API - POST" %}
**HTTP example**

```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": {
    "groupBy": {
      "attribute": "kind",
      "size": 5,
      "values": ["product", "box"]
    }
  }
}
```

**`curl` example**

```bash
curl -d "{\"token\":\"${SEARCH_API_TOKEN}\", \"query\":\"T-Shirt\", \"options\":{\"groupBy\":{\"attribute\":\"kind\",\"size\":5,\"values\":[\"product\",\"box\"]}}}}" \
     -H "Content-Type: application/json; charset=UTF-8"                                                                                        \
     -X POST "https://api-eu.attraqt.io/search/suggest"
```

**JavaScript example**

```javascript
const response = await fetch('https://api-eu.attraqt.io/search/suggest', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json; charset=UTF-8'
  },
  body: JSON.stringify({
    token: SEARCH_API_TOKEN,
    query: 'T-Shirt',
    options: {
      groupBy: {
        attribute: 'kind',
        size: 5,
        values: ['product', 'box']
      }
    }
  })
});

if (response.ok) {
  console.log(await response.json());
}
```

{% endtab %}
{% endtabs %}