Faceting

if you haven't gone through the prerequisites and the v2 structure, please have a look at overview docid\ czeodl0skcuv 18ipuplr 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 tab examples url https hostname cs v2 search name retrieving facets method post request pathparameters queryparameters headerparameters bodydataparameters kind optional name enabled type boolean description whether or not to return any filters with this query this defaults to false so no filters are returned unless requested kind optional name include type array description 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 kind optional name exclude type array description 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 kind optional name options type object description specify how the filters options are included in the response n norder 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 n nlimit specify the maximum number of options to be included per filter n nmincount 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 kind optional name rangefiltersettings type object description 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 n nkey this is the identifier of your numerical attribute eg klevu price n nminmax if set to true the klevu search engine calculates the minimum and maximum values for this filter for use with a slider n nrangeinterval 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 n nby 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 formdataparameters results languages id 3xlvmt855lgkjoht0npxg code n meta n qtime 19 n responsecode 200 n n queryresults n n id productsearch n meta n qtime 17 n noofresults 0 n totalresultsfound 104 n typeofsearch wildcard and n offset 0 n debugginginformation n notificationcode 1 n searchedterm short n apikey klevu 156925593843210765 n ispersonalised false n n records n filters n n key category n label category n type options n options n n count 3 n name capri n value capri n selected false n n n count 3 n name hoodies n value hoodies n selected false n n n count 3 n name hoodies sweatshirts n value hoodies sweatshirts n selected false n n n count 3 n name pants n value pants n selected false n n n count 68 n name shorts n value shorts n selected false n n n n n key size n label size n type options n options n n count 35 n name large n value large n selected false n n n count 35 n name medium n value medium n selected false n n n count 34 n name small n value small n selected false n n n n n key brand n label brand n type options n options n n count 28 n name kke n value kke n selected false n n n count 1 n name kke new n value kke new n selected false n n n count 45 n name ksd n value ksd n selected false n n n count 30 n name mnh n value mnh n selected false n n n n n key price range n label price range n type options n options n n count 95 n name 0 49 n value 0 49 n selected false n n n count 9 n name 50 99 n value 50 99 n selected false n n n n n n n language 200 customlabel selectedlanguageid 3xlvmt855lgkjoht0npxg examples languages id jsu7dlyyj euh63ysp682 code n recordqueries n n filters n filterstoreturn n enabled true n include n category n brand n size n n options n order index n limit 5 n n rangefiltersettings n n key klevu price n minmax false n rangeinterval 50 n n n key customrangefilter n minmax true n n n n n id productsearch n typeofrequest search n settings n searchprefs n showfilterswithsmallcount n n query n term short n n limit 0 n typeofrecords n klevu product n n fields n id n name n n n n n context n apikeys n klevu 156925593843210765 n n n language json customlabel request body json id 8yg33te4jzfowp5yebmjh code ?php n n curl curl init ; n ncurl setopt array curl array n curlopt url https eucs15v2 ksearchnet com cs v2 search n curlopt returntransfer true n curlopt encoding n curlopt maxredirs 10 n curlopt timeout 0 n curlopt followlocation true n curlopt http version curl http version 1 1 n curlopt customrequest post n curlopt postfields n recordqueries n n filters n filterstoreturn n enabled true n include n category n brand n size n n options n order index n limit 5 n n rangefiltersettings n n key klevu price n minmax false n rangeinterval 50 n n n key customrangefilter n minmax true n n n n n id productsearch n typeofrequest search n settings n searchprefs n showfilterswithsmallcount n n query n term short n n limit 0 n typeofrecords n klevu product n n fields n id n name n n n n n context n apikeys n klevu 156925593843210765 n n n n curlopt httpheader array n content type application json n n ; n n response curl exec curl ; n ncurl close curl ; necho response; n language php customlabel id wcdgtssqaxfiwklk2v174 code 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 ; n nvar xhr new xmlhttprequest ; nxhr withcredentials false; n nxhr addeventlistener readystatechange function n if this readystate 4 n console log this responsetext ; n n ; n nxhr open post https eucs15v2 ksearchnet com cs v2 search ; nxhr setrequestheader content type application json ; n nxhr send data ; language javascript customlabel id npw0nije j5r9i5w4bgn0 code okhttpclient client new okhttpclient newbuilder n build ; nmediatype mediatype mediatype parse application json ; nrequestbody body requestbody create mediatype n recordqueries n n filters n filterstoreturn n enabled true n include n category n brand n size n n options n order index n limit 5 n n rangefiltersettings n n key klevu price n minmax false n rangeinterval 50 n n n key customrangefilter n minmax true n n n n n id productsearch n typeofrequest search n settings n searchprefs n showfilterswithsmallcount n n query n term short n n limit 0 n typeofrecords n klevu product n n fields n id n name n n n n n context n apikeys n klevu 156925593843210765 n n n ; nrequest request new request builder n url https eucs15v2 ksearchnet com cs v2 search n method post body n addheader content type application json n build ; nresponse response client newcall request execute ; language java customlabel id 0ih7niekhhfml7cry51j code var request require request ; nvar options n method post n url https eucs15v2 ksearchnet com cs v2 search n headers n content type application json n n body 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 n n ; nrequest options function error response n if error throw new error error ; n console log response body ; n ; n language nodejs customlabel selectedlanguageid wcdgtssqaxfiwklk2v174 description this is an example to fetch facets currentnewparameter label body parameter value bodydataparameters 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 tab examples url https hostname cs v2 search name applying facets method post request pathparameters queryparameters headerparameters bodydataparameters kind required name key type string description the id of the attribute to filter by eg color kind required name values type array description an array of values to filter by eg red blue n nwhen 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 n nto retrieve steps of prices for example those with values between 0 50 or 150 200 use key klevu price values 0 50 150 200 n nto retrieve exact values for example records with exact values 100 or 200 use key klevu price values 100 100 200 200 n nby 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 kind optional name singleselect type boolean description the behaviour when specifying multiple filters or values formdataparameters results languages id 3xlvmt855lgkjoht0npxg code n meta n qtime 23 n responsecode 200 n n queryresults n n id productsearch n meta n qtime 20 n noofresults 5 n totalresultsfound 15 n typeofsearch fuzzy and n offset 0 n debugginginformation n notificationcode 1 n searchedterm short n apikey klevu 156925593843210765 n ispersonalised false n n records n n size small n saleprice 75 0 n name stellar solar jacket n id 31366456541246 n n n size small n saleprice 74 0 n name impulse duffle n id 31366490095678 n n n size small n saleprice 69 0 n name ajax full zip sweatshirt n id 31366490554430 n n n size small n saleprice 64 0 n name grayson crewneck sweatshirt n id 31366490914878 n n n size large n saleprice 64 0 n name grayson crewneck sweatshirt n id 31366490816574 n n n filters n n n language 200 customlabel selectedlanguageid 3xlvmt855lgkjoht0npxg examples languages id jsu7dlyyj euh63ysp682 code n recordqueries n n filters n applyfilters n filters n n key size n values n small n large n n settings n singleselect false n n n n key klevu price n values n 60 n 80 n n settings n singleselect false n n n n n n id productsearch n typeofrequest search n settings n query n term short n n limit 5 n fields n id n name n size n klevu price n n typeofrecords n klevu product n n n n n context n apikeys n klevu 156925593843210765 n n n language json customlabel request body json id 8yg33te4jzfowp5yebmjh code ?php n n curl curl init ; n ncurl setopt array curl array n curlopt url https eucs15v2 ksearchnet com cs v2 search n curlopt returntransfer true n curlopt encoding n curlopt maxredirs 10 n curlopt timeout 0 n curlopt followlocation true n curlopt http version curl http version 1 1 n curlopt customrequest post n curlopt postfields n recordqueries n n filters n applyfilters n filters n n key size n values n small n large n n settings n singleselect false n n n n key klevu price n values n 60 n 80 n n settings n singleselect false n n n n n n id productsearch n typeofrequest search n settings n query n term short n n limit 5 n fields n id n name n size n klevu price n n typeofrecords n klevu product n n n n n context n apikeys n klevu 156925593843210765 n n n n curlopt httpheader array n content type application json n n ; n n response curl exec curl ; n ncurl close curl ; necho response; n language php customlabel id wcdgtssqaxfiwklk2v174 code var data json stringify 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 ; n nvar xhr new xmlhttprequest ; nxhr withcredentials false; n nxhr addeventlistener readystatechange function n if this readystate 4 n console log this responsetext ; n n ; n nxhr open post https eucs15v2 ksearchnet com cs v2 search ; nxhr setrequestheader content type application json ; n nxhr send data ; language javascript customlabel id npw0nije j5r9i5w4bgn0 code okhttpclient client new okhttpclient newbuilder n build ; nmediatype mediatype mediatype parse application json ; nrequestbody body requestbody create mediatype n recordqueries n n filters n applyfilters n filters n n key size n values n small n large n n settings n singleselect false n n n n key klevu price n values n 60 n 80 n n settings n singleselect false n n n n n n id productsearch n typeofrequest search n settings n query n term short n n limit 5 n fields n id n name n size n klevu price n n typeofrecords n klevu product n n n n n context n apikeys n klevu 156925593843210765 n n n ; nrequest request new request builder n url https eucs15v2 ksearchnet com cs v2 search n method post body n addheader content type application json n build ; nresponse response client newcall request execute ; language java customlabel id 0ih7niekhhfml7cry51j code var request require request ; nvar options n method post n url https eucs15v2 ksearchnet com cs v2 search n headers n content type application json n n body json stringify 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 n n ; nrequest options function error response n if error throw new error error ; n console log response body ; n ; n language nodejs customlabel selectedlanguageid jsu7dlyyj euh63ysp682 description this is an example to apply facets currentnewparameter label body parameter value bodydataparameters 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!