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

# Faceting

Faceting is a powerful tool for E-commerce website, find below how you can configure it with XO Search

{% hint style="info" %}
This feature is only available for the **Search API**
{% endhint %}

## Parameters

The faceting parameters allows the developer to enable/disable faceting results, and to filter search results using specific facets values.

| **Name**     | Type    | Is Required ? | Default value |
| ------------ | ------- | ------------- | ------------- |
| **`facets`** | `array` | ✖             | empty array   |

### **`facets`**

If specified, perform a search using the selected facets and values.\
This parameter must be an array of *JSON* objects. Each object should have the following properties:

| Property     | Type              | Description                                                                        |
| ------------ | ----------------- | ---------------------------------------------------------------------------------- |
| **`id`**     | `string`          | ID of the facet to select                                                          |
| **`values`** | array of `string` | <p>Items should have at least one</p><p>of these values for the selected facet</p> |

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

```javascript
"facets": [
    {
        "id": "facet-name",
        "values": ["string-value", ...]
    },
    ...
]
```

{% endtab %}

{% tab title="TypeScript Format" %}

```typescript
type Facets = { id: string, values: string[] }[];
```

{% endtab %}
{% endtabs %}

#### Notes

* Unknown facets values will lead to empty responses.

{% hint style="warning" %}
Calling facets by **`attribute`** has been deprecated and will soon be no longer supported. Please use the **`id`** field in the API request.
{% endhint %}

## 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 examples

### Filter results based on facets values

* Retrieve only items with the facet `size` set to one of the `[46, 48, 50]` values

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

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

const query = 'T-shirt';

search.init({ token: SEARCH_API_TOKEN });

const response = await search.query(query, {
  facets: [
    {
      id: 'size',
      values: ['46', '48', '50']
    }
  ]
});

console.log(response);
```

**HTML example**

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

    xo.search.query('T-Shirt', {
        facets: [
            {
                id: 'size',
                values: ['46', '48', '50']
            }
        ]
    }).then((response) => {
        console.log(response);
    });
</script>
```

{% endtab %}

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

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

{
  "token": "SEARCH_API_TOKEN",
  "query": "T-Shirt",
  "options": {
    "facets": [
      {
        "id": "size",
        "values": ["46", "48", "50"] 
      }
    ]
  }
}
```

**`curl` example**

```bash
curl -d "{\"token\":\"${SEARCH_API_TOKEN}\", \"query\":\"T-Shirt\", \"options\":{\"facets\": [{\"id\":\"size\", \"values\":[\"46\", \"48\", \"50\"]}]}}" \
     -H "Content-Type: application/json; charset=UTF-8"                                                                                                  \
     -X POST "https://api-eu.attraqt.io/search"
```

**JavaScript example**

```javascript
const response = await fetch('https://api-eu.attraqt.io/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json; charset=UTF-8'
  },
  body: JSON.stringify({
    token: SEARCH_API_TOKEN,
    query: 'T-Shirt',
    options: {
      facets: [
        {
          id: 'size',
          values: ['46', '48', '50']
        }
      ]
    }
  })
});

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

{% endtab %}

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

```http
GET https://api-eu.attraqt.io/search/:token?encoded=:encodedParams HTTP/1.1
```

**`curl` example**

```bash
curl "https://api-eu.attraqt.io/search/${SEARCH_API_TOKEN}?encoded=%7B%22query%22%3A%22T-Shirt%22%2C%20%22options%22%3A%7B%22facets%22%3A%5B%7B%22id%22%3A%22size%22%2C%22values%22%3A%5B%2246%22%2C%2248%22%2C%2250%22%5D%7D%5D%7D%7D"
```

**JavaScript example**

```javascript
const token = SEARCH_API_TOKEN;
const params = encodeURIComponent(JSON.stringify({
  query: 'T-shirt',
  options: {
    facets: [
      {
        'id': 'size',
        'values': ['46', '48', '50'] 
      }
    ]
  }
}));

const response = await fetch(
  `https://api-eu.attraqt.io/search/${token}?encoded=${params}`
);

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

{% endtab %}
{% endtabs %}

* Retrieve only items with the facet `size` set to `46` **and** the facet `color` set to one of `[23, 26]` values

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

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

const query = 'T-shirt';

search.init({ token: SEARCH_API_TOKEN });

const response = await search.query(query, {
  facets: [
    {
      id: 'size',
      values: ['46'] 
    },
    {
      id: 'color',
      values: ['23', '26'] 
    }
  ]
});

console.log(response);
```

**HTML example**

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

    xo.search.query('T-Shirt', {
        facets: [
            {
                id: 'size',
                values: ['46'] 
            },
            {
                id: 'color',
                values: ['23', '26'] 
            }
        ]
    }).then((response) => {
        console.log(response);
    });
</script>
```

{% endtab %}

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

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

{
  "token": "SEARCH_API_TOKEN",
  "query": "T-Shirt",
  "options": {
    "facets": [
      {
        "id": "size",
        "values": ["46"] 
      },
      {
        "id": "color",
        "values": ["23", "26"] 
      }
    ]
  }
}
```

**`curl` example**

```bash
curl -d "{\"token\":\"${SEARCH_API_TOKEN}\", \"query\":\"T-Shirt\", \"options\":{\"facets\": [{\"id\":\"size\", \"values\":[\"46\"]}, {\"id\":\"color\", \"values\":[\"23\", \"26\"]}]}}" \
     -H "Content-Type: application/json; charset=UTF-8"                                                                                                                                   \
     -X POST "https://api-eu.attraqt.io/search"
```

**JavaScript example**

```javascript
const response = await fetch('https://api-eu.attraqt.io/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json; charset=UTF-8'
  },
  body: JSON.stringify({
    token: SEARCH_API_TOKEN,
    query: 'T-Shirt',
    options: {
      facets: [
        {
          id: 'size',
          values: ['46'] 
        },
        {
          id: 'color',
          values: ['23', '26'] 
        }
      ]
    }
  })
});

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

{% endtab %}

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

```http
GET https://api-eu.attraqt.io/search/:token?encoded=:encodedParams HTTP/1.1
```

**`curl` example**

```bash
curl "https://api-eu.attraqt.io/search/${SEARCH_API_TOKEN}?encoded=%7B%22query%22%3A%22T-Shirt%22%2C%20%22options%22%3A%7B%22facets%22%3A%5B%7B%22id%22%3A%22size%22%2C%22values%22%3A%5B%2246%22%5D%7D%2C%7B%22id%22%3A%22color%22%2C%22values%22%3A%5B%2223%22%2C%20%2226%22%5D%7D%5D%7D%7D"
```

**JavaScript example**

```javascript
const token = SEARCH_API_TOKEN;
const params = encodeURIComponent(JSON.stringify({
  query: 'T-shirt',
  options: {
    facets: [
      {
        id: 'size',
        values: ['46'] 
      },
      {
        id: 'color',
        values: ['23', '26'] 
      }
    ]
  }
}));

const response = await fetch(
  `https://api-eu.attraqt.io/search/${token}?encoded=${params}`
);

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

{% endtab %}
{% endtabs %}