Faceting

7min
If you haven't gone through the prerequisites and the v2 structure, please have a look at Overview﻿ 
It is important to note that retrieving filters is an expensive operation that can slow down your search experience. For this reason, you may want to fetch filters once per unique query and cache them locally.
﻿
For example, when using pagination to retrieve records from subsequent pages, there is actually no need to fetch the filters again since these will not change from page to page. The filters from Klevu are always for the entire set of records for that query.
While searching for records, you can also request aggregations of the attribute values within the search results, so you can allow your customers to filter the results further.
For example, if the search query was "tops", you may also be interested to know all of the colors, sizes, and materials that these tops are available in to display them as selectable facets or filters.
There are two separate methods of working with filters with the Klevu search API:
Retrieving filters applicable to a search result
Applying one or more of those filters to a search query
To apply a filter, you need to know the key of the relevant filter and the value of the relevant option, which should be submitted using the same format and case sensitivity as is returned by Klevu.
Retrieving Facets
The filtersToReturn object can be used for obtaining filters from the Klevu Search engine. You can request all possible filters or only those matching certain criteria.
This is an example to fetch facets. 
POST
Request
Body Parameters
enabled
optional
Boolean
Whether or not to return any filters with this query. This defaults to false so no filters are returned unless requested.
include
optional
Array
This is the list of filter keys that you would like to retrieve as filters. A filter may also not be returned if there aren't enough applicable records in the result set.
exclude
optional
Array
This is the list of filter keys that you do not want Klevu Search to include in the response. If a filter is specified in both include and exclude lists, include will take precedence.
options
optional
Object
Specify how the filters' options are included in the response.

order: A value of 'FREQ' will sort options based on the number of records each option has in the result set. 'INDEX' will sort the options alphabetically.

limit: Specify the maximum number of options to be included per filter.

minCount: If the parameter minCount is present with a positive number, only the options with an option count equal to or higher than the minCount are included.
rangeFilterSettings
optional
Object
When minMax is false, this setting allows you to retrieve range filters for use with numeric values such as price, so you can display bands of 0-99, 100-199, etc. or a price slider.

key: This is the identifier of your numerical attribute, eg. 'klevu_price'.

minMax: If set to true, the Klevu Search engine calculates the minimum and maximum values for this filter for use with a slider.

rangeInterval: If a positive value is provided, the Klevu Search engine will calculate ranges for this value. For example a value of 100 would give ranges from 0 to 99, 100 to 299, etc.

By default all attributes submitted to Klevu are indexed as STRING attributes, which means they cannot be used as range filters. The product sale price field is the only exception to this rule, which is filtered using the key klevu_price. If you have explicitly requested and Klevu has approved that certain attributes be indexed as numerical attributes, you can also retrieve those as range filters.
Request Body (JSON)
PHP
JS
Java
Node.js
var data = JSON.stringify({"recordQueries":[{"filters":{"filtersToReturn":{"enabled":true,"include":["category","brand","size"],"options":{"order":"INDEX","limit":5},"rangeFilterSettings":[{"key":"klevu_price","minMax":false,"rangeInterval":50},{"key":"CustomRangeFilter","minMax":true}]}},"id":"productSearch","typeOfRequest":"SEARCH","settings":{"searchPrefs":["showFiltersWithSmallCount"],"query":{"term":"short"},"limit":0,"typeOfRecords":["KLEVU_PRODUCT"],"fields":["id","name"]}}],"context":{"apiKeys":["klevu-156925593843210765"]}});

var xhr = new XMLHttpRequest();
xhr.withCredentials = false;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://eucs15v2.ksearchnet.com/cs/v2/search");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.send(data);
var data = JSON.stringify({"recordQueries":[{"filters":{"filtersToReturn":{"enabled":true,"include":["category","brand","size"],"options":{"order":"INDEX","limit":5},"rangeFilterSettings":[{"key":"klevu_price","minMax":false,"rangeInterval":50},{"key":"CustomRangeFilter","minMax":true}]}},"id":"productSearch","typeOfRequest":"SEARCH","settings":{"searchPrefs":["showFiltersWithSmallCount"],"query":{"term":"short"},"limit":0,"typeOfRecords":["KLEVU_PRODUCT"],"fields":["id","name"]}}],"context":{"apiKeys":["klevu-156925593843210765"]}});

var xhr = new XMLHttpRequest();
xhr.withCredentials = false;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://eucs15v2.ksearchnet.com/cs/v2/search");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.send(data);
Responses
200
{
    "meta": {
        "qTime": 19,
        "responseCode": 200
    },
    "queryResults": [
        {
            "id": "productSearch",
            "meta": {
                "qTime": 17,
                "noOfResults": 0,
                "totalResultsFound": 104,
                "typeOfSearch": "WILDCARD_AND",
                "offset": 0,
                "debuggingInformation": {},
                "notificationCode": 1,
                "searchedTerm": "short",
                "apiKey": "klevu-156925593843210765",
                "isPersonalised": false
            },
            "records": [],
            "filters": [
                {
                    "key": "category",
                    "label": "category",
                    "type": "OPTIONS",
                    "options": [
                        {
                            "count": 3,
                            "name": "Capri",
                            "value": "Capri",
                            "selected": false
                        },
                        {
                            "count": 3,
                            "name": "Hoodies",
                            "value": "Hoodies",
                            "selected": false
                        },
                        {
                            "count": 3,
                            "name": "Hoodies & Sweatshirts",
                            "value": "Hoodies & Sweatshirts",
                            "selected": false
                        },
                        {
                            "count": 3,
                            "name": "Pants",
                            "value": "Pants",
                            "selected": false
                        },
                        {
                            "count": 68,
                            "name": "Shorts",
                            "value": "Shorts",
                            "selected": false
                        }
                    ]
                },
                {
                    "key": "size",
                    "label": "Size",
                    "type": "OPTIONS",
                    "options": [
                        {
                            "count": 35,
                            "name": "Large",
                            "value": "Large",
                            "selected": false
                        },
                        {
                            "count": 35,
                            "name": "Medium",
                            "value": "Medium",
                            "selected": false
                        },
                        {
                            "count": 34,
                            "name": "Small",
                            "value": "Small",
                            "selected": false
                        }
                    ]
                },
                {
                    "key": "brand",
                    "label": "brand",
                    "type": "OPTIONS",
                    "options": [
                        {
                            "count": 28,
                            "name": "KKE",
                            "value": "KKE",
                            "selected": false
                        },
                        {
                            "count": 1,
                            "name": "KKE New",
                            "value": "KKE New",
                            "selected": false
                        },
                        {
                            "count": 45,
                            "name": "KSD",
                            "value": "KSD",
                            "selected": false
                        },
                        {
                            "count": 30,
                            "name": "MNH",
                            "value": "MNH",
                            "selected": false
                        }
                    ]
                },
                {
                    "key": "Price Range",
                    "label": "Price Range",
                    "type": "OPTIONS",
                    "options": [
                        {
                            "count": 95,
                            "name": "0 - 49",
                            "value": "0 - 49",
                            "selected": false
                        },
                        {
                            "count": 9,
                            "name": "50 - 99",
                            "value": "50 - 99",
                            "selected": false
                        }
                    ]
                }
            ]
        }
    ]
}
{
    "meta": {
        "qTime": 19,
        "responseCode": 200
    },
    "queryResults": [
        {
            "id": "productSearch",
            "meta": {
                "qTime": 17,
                "noOfResults": 0,
                "totalResultsFound": 104,
                "typeOfSearch": "WILDCARD_AND",
                "offset": 0,
                "debuggingInformation": {},
                "notificationCode": 1,
                "searchedTerm": "short",
                "apiKey": "klevu-156925593843210765",
                "isPersonalised": false
            },
            "records": [],
            "filters": [
                {
                    "key": "category",
                    "label": "category",
                    "type": "OPTIONS",
                    "options": [
                        {
                            "count": 3,
                            "name": "Capri",
                            "value": "Capri",
                            "selected": false
                        },
                        {
                            "count": 3,
                            "name": "Hoodies",
                            "value": "Hoodies",
                            "selected": false
                        },
                        {
                            "count": 3,
                            "name": "Hoodies & Sweatshirts",
                            "value": "Hoodies & Sweatshirts",
                            "selected": false
                        },
                        {
                            "count": 3,
                            "name": "Pants",
                            "value": "Pants",
                            "selected": false
                        },
                        {
                            "count": 68,
                            "name": "Shorts",
                            "value": "Shorts",
                            "selected": false
                        }
                    ]
                },
                {
                    "key": "size",
                    "label": "Size",
                    "type": "OPTIONS",
                    "options": [
                        {
                            "count": 35,
                            "name": "Large",
                            "value": "Large",
                            "selected": false
                        },
                        {
                            "count": 35,
                            "name": "Medium",
                            "value": "Medium",
                            "selected": false
                        },
                        {
                            "count": 34,
                            "name": "Small",
                            "value": "Small",
                            "selected": false
                        }
                    ]
                },
                {
                    "key": "brand",
                    "label": "brand",
                    "type": "OPTIONS",
                    "options": [
                        {
                            "count": 28,
                            "name": "KKE",
                            "value": "KKE",
                            "selected": false
                        },
                        {
                            "count": 1,
                            "name": "KKE New",
                            "value": "KKE New",
                            "selected": false
                        },
                        {
                            "count": 45,
                            "name": "KSD",
                            "value": "KSD",
                            "selected": false
                        },
                        {
                            "count": 30,
                            "name": "MNH",
                            "value": "MNH",
                            "selected": false
                        }
                    ]
                },
                {
                    "key": "Price Range",
                    "label": "Price Range",
                    "type": "OPTIONS",
                    "options": [
                        {
                            "count": 95,
                            "name": "0 - 49",
                            "value": "0 - 49",
                            "selected": false
                        },
                        {
                            "count": 9,
                            "name": "50 - 99",
                            "value": "50 - 99",
                            "selected": false
                        }
                    ]
                }
            ]
        }
    ]
}
﻿
Understanding response format
Params
Description
﻿
key
This is the unique identifier of the attribute for which options are being provided.
﻿
label
This is the label or caption which you have associated with the attribute in the Klevu Merchant Centre.
﻿
type
The type of the filter will be either OPTIONS, SLIDER or RATING. For an OPTIONS filter, its different options, eg. red, blue, black, are provided. 
For a SLIDER filter, values such as minimum, maximum, start and end are provided in the response. 
For a RATING filter, its rating ranges from 1 to 5, where Range is defined as below:
The rating range of 4.51 - 5.5 is considered the 5 rating
The rating range of 3.51 - 4.5 is considered the 4 rating
The rating range of 2.51 - 3.5 is considered the 3 rating
The rating range of 1.51 - 2.5 is considered the 2 rating
The rating less than 1.50 is considered 1 Rating
﻿
options
For type OPTIONS this will contain an array of different options available.
name: The label or caption of the option, eg. Red, Blue, Black, etc.
value: This is the unique identifier which should be used when applying a filter to search results.
count: The number of records found with the current option in the current search results.
selected: Whether ot not the current option is already applied as a filtering condition on the search results.
﻿
min, max, start, end
These values are provided only for the SLIDER or range filters.
min, max: These values are the minimum and maximum values found in the current result set. This can be used to set the upper and lower limits of your slider.
start, end: The start and end values are the filtering conditions already applied on the result set for this filter, or NULL if no filter has been applied.
﻿
Applying Facets
The applyFilters object can be used for applying filter conditions so your customers can fine-tune their results based on relevant attributes.
This is an example to apply facets. 
POST
Request
Body Parameters
key
required
String
The ID of the attribute to filter by, eg. color
values
required
Array
An array of values to filter by, eg. Red, Blue.

When using range filters, specify the first value as the minimum value and the second as the max value. For example to retrieve records with prices between 60 to 80, use: "key": "klevu_price", "values": [60, 80].

To retrieve steps of prices, for example those with values between 0-50 or 150-200, use: "key": "klevu_price", "values": ["0-50", "150-200"].

To retrieve exact values, for example records with exact values 100 or 200, use: "key": "klevu_price", "values": ["100-100", "200-200"].

By default all attributes submitted to Klevu are indexed as STRING attributes, which means they cannot be used as range filters. The product sale price field is the only exception to this rule, which is filtered using the key klevu_price. If you have explicitly requested and Klevu has approved that certain attributes be indexed as numerical attributes, you can also retrieve those as range filters.
singleSelect
optional
Boolean
The behaviour when specifying multiple filters or values. 
Request Body (JSON)
PHP
JS
Java
Node.js
{
  "recordQueries": [
    {
      "filters": {
        "applyFilters": {
          "filters": [
            {
              "key": "size",
              "values": [
                "Small",
                "Large"
              ],
              "settings": {
                "singleSelect": false
              }
            },
            {
              "key": "klevu_price",
              "values": [
                  "60",
                  "80"
              ],
              "settings": {
                  "singleSelect": false
              }
            }
          ]
        }
      },
      "id": "productSearch",
      "typeOfRequest": "SEARCH",
      "settings": {
        "query": {
          "term": "short"
        },
        "limit": 5,
        "fields": [
          "id",
          "name",
          "size",
          "klevu_price"
        ],
        "typeOfRecords": [
          "KLEVU_PRODUCT"
        ]
      }
    }
  ],
  "context": {
    "apiKeys": [
      "klevu-156925593843210765"
    ]
  }
}
{
  "recordQueries": [
    {
      "filters": {
        "applyFilters": {
          "filters": [
            {
              "key": "size",
              "values": [
                "Small",
                "Large"
              ],
              "settings": {
                "singleSelect": false
              }
            },
            {
              "key": "klevu_price",
              "values": [
                  "60",
                  "80"
              ],
              "settings": {
                  "singleSelect": false
              }
            }
          ]
        }
      },
      "id": "productSearch",
      "typeOfRequest": "SEARCH",
      "settings": {
        "query": {
          "term": "short"
        },
        "limit": 5,
        "fields": [
          "id",
          "name",
          "size",
          "klevu_price"
        ],
        "typeOfRecords": [
          "KLEVU_PRODUCT"
        ]
      }
    }
  ],
  "context": {
    "apiKeys": [
      "klevu-156925593843210765"
    ]
  }
}
Responses
200
{
    "meta": {
        "qTime": 23,
        "responseCode": 200
    },
    "queryResults": [
        {
            "id": "productSearch",
            "meta": {
                "qTime": 20,
                "noOfResults": 5,
                "totalResultsFound": 15,
                "typeOfSearch": "FUZZY_AND",
                "offset": 0,
                "debuggingInformation": {},
                "notificationCode": 1,
                "searchedTerm": "short",
                "apiKey": "klevu-156925593843210765",
                "isPersonalised": false
            },
            "records": [
                {
                    "size": "Small",
                    "salePrice": "75.0",
                    "name": "Stellar Solar Jacket",
                    "id": "31366456541246"
                },
                {
                    "size": "Small",
                    "salePrice": "74.0",
                    "name": "impulse Duffle",
                    "id": "31366490095678"
                },
                {
                    "size": "Small",
                    "salePrice": "69.0",
                    "name": "Ajax Full-Zip Sweatshirt",
                    "id": "31366490554430"
                },
                {
                    "size": "Small",
                    "salePrice": "64.0",
                    "name": "Grayson Crewneck Sweatshirt",
                    "id": "31366490914878"
                },
                {
                    "size": "Large",
                    "salePrice": "64.0",
                    "name": "Grayson Crewneck Sweatshirt",
                    "id": "31366490816574"
                }
            ],
            "filters": []
        }
    ]
}
{
    "meta": {
        "qTime": 23,
        "responseCode": 200
    },
    "queryResults": [
        {
            "id": "productSearch",
            "meta": {
                "qTime": 20,
                "noOfResults": 5,
                "totalResultsFound": 15,
                "typeOfSearch": "FUZZY_AND",
                "offset": 0,
                "debuggingInformation": {},
                "notificationCode": 1,
                "searchedTerm": "short",
                "apiKey": "klevu-156925593843210765",
                "isPersonalised": false
            },
            "records": [
                {
                    "size": "Small",
                    "salePrice": "75.0",
                    "name": "Stellar Solar Jacket",
                    "id": "31366456541246"
                },
                {
                    "size": "Small",
                    "salePrice": "74.0",
                    "name": "impulse Duffle",
                    "id": "31366490095678"
                },
                {
                    "size": "Small",
                    "salePrice": "69.0",
                    "name": "Ajax Full-Zip Sweatshirt",
                    "id": "31366490554430"
                },
                {
                    "size": "Small",
                    "salePrice": "64.0",
                    "name": "Grayson Crewneck Sweatshirt",
                    "id": "31366490914878"
                },
                {
                    "size": "Large",
                    "salePrice": "64.0",
                    "name": "Grayson Crewneck Sweatshirt",
                    "id": "31366490816574"
                }
            ],
            "filters": []
        }
    ]
}
﻿
Understanding response format
If only one filter is applied with only value, Klevu search ensures that all the records returned contain the relevant attribute with the specified value.
In the case where two or more values for the same filter are provided, the execution is dependent on the value of the singleSelect parameter.
If it is set to true, the products returned must have both the values.
If it is set to false, the products returned must have at least one of the values.
If constraints are added for multiple filters and the value of the singleSelect filter is false, the products returned must have at least one value from each of the filter conditions provided.
Try it here! 
<iframe src="https://codesandbox.io/embed/klevu-api-sendbox-4ktfrp?fontsize=14&hidenavigation=0&theme=dark&view=preview&initialpath=?payload=faceting"
     style="width:100%; height:550px; border:0; border-radius: 4px; overflow:hidden;"
     title="klevu_api sendbox"
     allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
     sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
     
   ></iframe>
<iframe src="https://codesandbox.io/embed/klevu-api-sendbox-4ktfrp?fontsize=14&hidenavigation=0&theme=dark&view=preview&initialpath=?payload=faceting"
     style="width:100%; height:550px; border:0; border-radius: 4px; overflow:hidden;"
     title="klevu_api sendbox"
     allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
     sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
     
   ></iframe>
﻿
﻿
Params	Description
key	This is the unique identifier of the attribute for which options are being provided.
label	This is the label or caption which you have associated with the attribute in the Klevu Merchant Centre.
type	The type of the filter will be either OPTIONS, SLIDER or RATING. For an OPTIONS filter, its different options, eg. red, blue, black, are provided. For a SLIDER filter, values such as minimum, maximum, start and end are provided in the response. For a RATING filter, its rating ranges from 1 to 5, where Range is defined as below: The rating range of 4.51 - 5.5 is considered the 5 rating The rating range of 3.51 - 4.5 is considered the 4 rating The rating range of 2.51 - 3.5 is considered the 3 rating The rating range of 1.51 - 2.5 is considered the 2 rating The rating less than 1.50 is considered 1 Rating
options	For type OPTIONS this will contain an array of different options available. name: The label or caption of the option, eg. Red, Blue, Black, etc. value: This is the unique identifier which should be used when applying a filter to search results. count: The number of records found with the current option in the current search results. selected: Whether ot not the current option is already applied as a filtering condition on the search results.
min, max, start, end	These values are provided only for the SLIDER or range filters. min, max: These values are the minimum and maximum values found in the current result set. This can be used to set the upper and lower limits of your slider. start, end: The start and end values are the filtering conditions already applied on the result set for this filter, or NULL if no filter has been applied.
Updated 30 Oct 2023
Did this page help you?
Record search
Advanced Filtering