Faceting

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

This feature is only available for the Search API

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	Items should have at least one of these values for the selected facet

JSON Format

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

TypeScript Format

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

Notes

• Unknown facets values will lead to empty responses.

Calling facets by attribute has been deprecated and will soon be no longer supported. Please use the id field in the API request.

Response

All responses from XO Search uses the same format. Check API Reference page for a more detailed description of this format.

pageAPI Reference

Usage examples

Filter results based on facets values

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

SDK - JS

NodeJS / NPM example

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

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

API - POST

HTTP example

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

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

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());
}

API - GET

HTTP example

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

curl example

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

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());
}

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

SDK - JS

NodeJS / NPM example

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

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

API - POST

HTTP example

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

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

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());
}

API - GET

HTTP example

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

curl example

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

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());
}