Retrieve and Apply Facets

facets are attribute categories for records that customers can use to further filter results for example, if a customer searches for shirts , the available facets might include size, color, or material type refer to the facets section of search results customizations as well as manage facets for category pages in the monetate knowledge base for more information if a customer initiates a search on your site without typing anything into the search bar, then personalized search still returns results based on the settings you've configured for personalized site search or personalized category pages , as applicable, in the monetate platform additionally, personalized search displays all the indexed facets from the mapped product catalog, excluding any that you've removed using the settings you've configured in the monetate platform within a personalized search api request, you can both retrieve applicable facets to display to customers and apply facets to filter results retrieving facets retrieving facets is a computationally expensive operation for best performance, you should minimize the number of times you retrieve them for example, if you're paginating search results, retrieve facets only on the first query to retrieve facets in a personalized search api request, add the filterstoreturn object with its enabled key set to true use the include and exclude arrays to define which filters you want and do not want returned, respectively you must contact your dedicated customer success manager (csm) if you want to use in the request a rating filter ("key" "rating") or any other filter based on a custom product catalog attribute in the mapped product catalog name retrieve facets method post url https engine monetate net api search v1 site search name instance domain search description tab examples examples languages id 52kuujlyx3oavtliwztij language json code n searchtoken monetate 156925593843210765 n recordqueries n n filters n filterstoreturn n enabled true n include n brand n size n n options n order index n limit 5 n n rangefiltersettings n n key monetate 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 query n term short n n limit 0 n typeofrecords n monetate product n n fields n id n name n n n n n customlabel example request to retrieve facets selectedlanguageid 52kuujlyx3oavtliwztij results languages id lfvx0m6ojvn5hknga p0d language 200 customlabel code 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 searchtoken monetate 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 kre n value kre n selected false n n n count 1 n name kre new n value kre 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 monetate price n label monetate price 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 selectedlanguageid lfvx0m6ojvn5hknga p0d request pathparameters name name kind required type string description the client s account for example a 1db61f7a as it appears in the value of channel used in the engine api request to obtain the search token the client s account for example a 1db61f7a as it appears in the value of channel used in the engine api request to obtain the search token name instance kind required type string description the client s account environment the value must either be p for production or d for development the client s account environment the value must either be p for production or d for development name domain kind required type string description the client s domain for example product monetate me as it appears in the value of channel used in the engine api request to obtain the search token the client s domain for example product monetate me as it appears in the value of channel used in the engine api request to obtain the search token queryparameters headerparameters name content type kind required type string description the value must be application json the value must be application json bodydataparameters name searchtoken kind required type string description a token used to authenticate the search request obtained by sending a request to the engine api see obtaining a search token in calling the personalized search api for more information a token used to authenticate the search request obtained by sending a request to the engine api see obtaining a search token in calling the personalized search api for more information name filters kind optional type object description defines the filtering options presented to the customer children name filterstoreturn kind optional type object description specifies which if any filters are returned in the response children name enabled kind optional type boolean description whether or not to return any filters with this query the default is false so that no filters are returned unless requested n nif enabled is true but both the include and exclude arrays are missing then personalized search uses what it s programmatically defined as the applicable facets for the query name include kind optional type array description the list of filter keys that you want to retrieve as filters a filter may also not be returned if the result set doesn t have enough applicable records name exclude kind optional type array description the list of filter keys that you don t want included in the response if a filter is specified in both include and exclude then include takes precedence name rangefiltersettings kind optional type object description specifies how range filters are displayed when minmax is false you can use range filters with numeric values such as price so that you can display bands of 0 99 100 199 etc or a price slider children name key kind optional type string description the numerical attribute use monetate price as the value if you want the customer to be able to filter by price use rating as the value if you want the customer to be able to filter by product ratings see the type parameter on the response tab for more information name minmax kind optional type boolean description if set to true then personalized search defines the minimum and maximum values for this filter for use with a slider that are based on the values present in the specific filter s attribute n nif set to false then personalized search uses the values present in the specific filter s attribute as selections that a customer can make when type is options or ratings the default is false name rangeinterval kind optional type number description if present with a positive value then personalized search defines ranges for this value for example a value of 100 results in ranges from 0 99 100 199 etc name options kind optional type object description specifies how the filter s options are included in the response children name order kind optional type string description a value of freq sorts options based on the number of records each option has in the result set a value of index sorts the options alphabetically name limit kind optional type number description the maximum number of options to be included per filter name mincount kind optional type string description if present with a positive number only the options with an option count equal to or higher than the value of mincount are included schema name filterstoreturn kind optional type object description specifies which if any filters are returned in the response children name enabled kind optional type boolean description whether or not to return any filters with this query the default is false so that no filters are returned unless requested n nif enabled is true but both the include and exclude arrays are missing then personalized search uses what it s programmatically defined as the applicable facets for the query name include kind optional type array description the list of filter keys that you want to retrieve as filters a filter may also not be returned if the result set doesn t have enough applicable records name exclude kind optional type array description the list of filter keys that you don t want included in the response if a filter is specified in both include and exclude then include takes precedence name rangefiltersettings kind optional type object description specifies how range filters are displayed when minmax is false you can use range filters with numeric values such as price so that you can display bands of 0 99 100 199 etc or a price slider children name key kind optional type string description the numerical attribute use monetate price as the value if you want the customer to be able to filter by price use rating as the value if you want the customer to be able to filter by product ratings see the type parameter on the response tab for more information name minmax kind optional type boolean description if set to true then personalized search defines the minimum and maximum values for this filter for use with a slider that are based on the values present in the specific filter s attribute n nif set to false then personalized search uses the values present in the specific filter s attribute as selections that a customer can make when type is options or ratings the default is false name rangeinterval kind optional type number description if present with a positive value then personalized search defines ranges for this value for example a value of 100 results in ranges from 0 99 100 199 etc name options kind optional type object description specifies how the filter s options are included in the response children name order kind optional type string description a value of freq sorts options based on the number of records each option has in the result set a value of index sorts the options alphabetically name limit kind optional type number description the maximum number of options to be included per filter name mincount kind optional type string description if present with a positive number only the options with an option count equal to or higher than the value of mincount are included formdataparameters currentnewparameter label body parameter value bodydataparameters response name filters kind optional type object description the parameters that define the filtering options presented to the customer children name key kind optional type string description the unique identifier of the attribute for which options are being provided name label kind optional type string description the filter name or caption you created for the attribute in the personalized search interface name type kind optional type string description the filter type the value of which can be options slider or rating the default is options n nan options filter provides the customer with different variant related choices a product might have for example red blue green and multicolor options for a colorway filter n na slider filter provides the customer with a predetermined start point and end point or minimum and maximum between which they must select for example a price range filter with the slider s minimum set at 24 99 and the maximum set at 199 99 n na rating filter provides the customer with defined rating ranges n n5 represents ratings ranging from 4 51 to 5 5 n4 represents ratings ranging from 3 51 to 4 5 n3 represents ratings ranging from 2 51 to 3 5 n2 represents ratings ranging from 1 51 to 2 5 n1 represents ratings from 1 51 and lower name options kind optional type object description included in the response when type is options this object can contain information about the variant related choices presented to the customer for filtering children name name kind optional type string description the label of an option choice for example red blue green and multicolor options for a colorway filter or s m l and xl options for a size filter name value kind optional type string description the unique identifier used when applying a filter to search results name count kind optional type number description the number of records within the current search results that contain the currently selected option name selected kind optional type boolean description whether or not the current option has already been applied as a filter to the search results name min kind optional type string description the minimum value found in the current result set when type is slider name max kind optional type string description the maximum value found in the current result set when type is slider name start kind optional type string description the starting value of the filtering condition already applied on the result set for this filter or null if no filter has been applied name end kind optional type string description the ending value of the filtering condition already applied on the result set for this filter or null if no filter has been applied hastryitout false the facets appear on your site as filters that the customer can apply to further narrow the search results retrieving the price facet personalized search treats the price facet differently from other facets, so displaying a price filter for customers to sort results does not involve passing price in the include array instead, you must include in the request the rangefiltersettings object with "monetate price" as the value for key see the definition of the rangefiltersettings object in the retrieve and apply facets docid\ epxtjiessh4 dsis 3wa1 reference for more information the example request and response in the retrieve and apply facets docid\ epxtjiessh4 dsis 3wa1 contain the key value pairs for the default price facet format, which presents customers with a selectable list of price ranges the following example request and response contain the key value pairs for the alternative format, a slider with minimum and maximum values that personalized search automatically sets based on the values of the relevant attribute in the mapped product catalog example request to retrieve price facet in slider format { "searchtoken" "monetate 156925593843210765", "recordqueries" \[ { "filters" { "filterstoreturn" { "enabled" true, "include" \[ "brand", "size" ] "options" { "order" "index", "limit" 5 }, "rangefiltersettings" \[ { "key" "monetate price", "minmax" true } ] } }, "id" "productsearch", "typeofrequest" "search", "settings" { "query" { "term" "short" }, "limit" 0, "typeofrecords" \[ "monetate product" ], "fields" \[ "id", "name" ] } } ] } response { "queryresults" \[ { "id" "productsearch", "meta" { "qtime" 17, "noofresults" 0, "totalresultsfound" 104, "typeofsearch" "wildcard and", "offset" 0, "debugginginformation" {}, "notificationcode" 1, "searchedterm" "short", "searchtoken" "monetate 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" "kre", "value" "kre", "selected" false }, { "count" 1, "name" "kre new", "value" "kre new", "selected" false }, { "count" 45, "name" "ksd", "value" "ksd", "selected" false }, { "count" 30, "name" "mnh", "value" "mnh", "selected" false } ] }, { "key" "monetate price", "label" "monetate price", "type" "slider", "min" "20", "max" "57", "start" null, "end" null } ] } ] } furthermore, because of the way personalized search returns a price based facet, you must include in your site's code some method to change the returned facet label, monetate price , into the label you want your customers to see in the following javascript example, the const keyword declares the constant value for heading with a means of removing monetate from the returned facet label monetate price example code to revise the monetate price label const heading = facet label replace(monetate /i, ""); the label that you want displayed for a price based facet is entirely up to you and must be part of your site's code applying facets applying facets to a query filters the results based on the selected facets and values run this query after a customer selects the facets they want to filter by apply facets in a query by using the applyfilters object if the customer selects only one value of only one facet, then personalized search ensures that all the returned records contain the facet attribute with the customer selected value however, if the customer selects multiple values for one facet, then the boolean key singleselect of the applyfilters object determines how personalized search applies them when singleselect is true , then a record must contain all the selected values to be included in the response when singleselect is false , then a record needs only to contain one of the selected values to be included in the response if constraints are added for multiple facets and singleselect is false , then a record must have at least one value from each of the filter conditions provided name apply facets method post url https engine monetate net api search v1 site search name instance domain search description tab examples examples languages id bwbnsix3 mthxkzbnf48k language json code n searchtoken monetate 156925593843210765 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 n n id productsearch n typeofrequest search n settings n query n term short n n limit 5 n typeofrecords n monetate product n n n n n customlabel example request to apply facets selectedlanguageid bwbnsix3 mthxkzbnf48k results languages id kzhyam75vn48ldvgmyzed language 200 customlabel code 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 searchtoken monetate 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 selectedlanguageid kzhyam75vn48ldvgmyzed request pathparameters name name kind required type string description the client s account for example a 1db61f7a as it appears in the value of channel used in the engine api request to obtain the search token the client s account for example a 1db61f7a as it appears in the value of channel used in the engine api request to obtain the search token name instance kind required type string description the client s account environment the value must either be p for production or d for development the client s account environment the value must either be p for production or d for development name domain kind required type string description the client s domain for example product monetate me as it appears in the value of channel used in the engine api request to obtain the search token the client s domain for example product monetate me as it appears in the value of channel used in the engine api request to obtain the search token queryparameters headerparameters name content type kind required type string description the value must be application json the value must be application json bodydataparameters name applyfilters kind required type object description defines the selected facets and values the customer selected children name filters kind required type object description defines the filtering options the customer selected children name key kind required type string description the id of the attribute to filter by for example size name values kind required type array description an array of values to filter by for example red blue n nwhen using range filters specify the first value as the minimum value for example 60 and the second as the maximum value for example 80 and use key monetate price values 60 80 n nto retrieve bands of prices for example price bands between 0 50 and 150 200 use key monetate price values 0 50 150 200 n nto retrieve exact values for example exact value of 100 or 200 use key monetate price values 100 100 200 200 name singleselect kind optional type boolean description the behavior when multiple values are specified for a facet formdataparameters currentnewparameter label path parameter value pathparameters hastryitout false advanced filtering customers may add or remove filter options as they search for example, a customer may filter initial results for a shirts query by selecting the red option from the color filter next, the customer selects m from the size filter along with a price range this example of a complex filtering operation requires you to include the groupcondition object to the request so that customers can fine tune their results based on relevant attributes name apply advanced filtering method post url https engine monetate net api search v1 site search name instance domain search description tab examples examples languages id jvutnjbsrvmniiht0geko language json code n searchtoken 6 18 ejxdjsskgzaurp lrkpxkxy7zywktujth2 wdqgu9ypyop n recordqueries n n id productsearch n typeofrequest search n settings n typeofrecords n monetate product n n groupcondition n groupoperator any of n conditions n n key monetate price n valueoperator include n singleselect true n excludevaluesinresult true n values n 20 25 n n n n key itemgroupid n valueoperator exclude n singleselect false n values n 4384028262462 n n n n key size n valueoperator exclude n singleselect false n values n small n large n n n n key brand n valueoperator exists n n n key discount n valueoperator not exists n n n n query n term tee n n limit 2 n n n n suggestions n customlabel example request to apply advanced filtering selectedlanguageid jvutnjbsrvmniiht0geko results languages id zqlozdo1ih3kxb8t3aw8 language 200 customlabel code n queryresults n n id productsearch n meta n qtime 7 n noofresults 2 n totalresultsfound 6 n typeofsearch wildcard and n offset 0 n debugginginformation n notificationcode 1 n searchedterm tee n searchtoken 6 18 ejxdjsskgzaurp lrkpxkxy7zywktujth2 wdqgu9ypyop n ispersonalised false n n records n n discount n hidegroupprices n type tees n itemgroupid 4384027344958 n storebasecurrency usd n price 24 00 n toprice n imageurl https www example com files products 4384027344958 yellow main medium jpg n currency usd n instock yes n id 31366447 n imagehover n sku ws05 xs yellow n brand mybrand n baseprice 24 0 n startprice n image https www example com files products 4384027344958 yellow main medium jpg n saleprice 24 0 n monetate category monetate product;products;;tees n url https www example com products mybrand fitness tee yellow n size medium n name mybrand fitness tee n shortdesc when you re too far to turn back you ll be glad you re wearing the mybrand fitness tee its lightweight fabric wicks sweat helping you to keep cool as you go the distance n category tees n typeofrecord monetate product n n n discount n hidegroupprices n type tees n itemgroupid 4384047759422 n storebasecurrency usd n price 24 00 n toprice n imageurl https www example com files products 4384047759422 yellow main medium jpg n currency usd n instock yes n id 31366478 n imagehover n sku ms01 xs yellow n brand mybrand n baseprice 24 0 n startprice n image https www example com files products 4384047759422 yellow main medium jpg n saleprice 24 0 n monetate category monetate product;products;;tees n url https www example com products mybrand everyday tee yellow n size medium n name mybrand every day tee n shortdesc need an everyday action tee that helps keep you dry? the mybrand every day fitness tee is made from a wicking knit that funnels moisture away from your skin its classic style hides premium performance technology n category tees n typeofrecord monetate product n n n filters n n n id gtiw9jc7umpr5lmdyk1mz language 404 customlabel code n message ain t no cake like that n selectedlanguageid zqlozdo1ih3kxb8t3aw8 request pathparameters name name kind required type string description the client s account for example a 1db61f7a as it appears in the value of channel used in the engine api request to obtain the search token the client s account for example a 1db61f7a as it appears in the value of channel used in the engine api request to obtain the search token name instance kind required type string description the client s account environment the value must either be p for production or d for development the client s account environment the value must either be p for production or d for development name domain kind required type string description the client s domain for example product monetate me as it appears in the value of channel used in the engine api request to obtain the search token the client s domain for example product monetate me as it appears in the value of channel used in the engine api request to obtain the search token queryparameters headerparameters name content type kind required type string description the value must be application json the value must be application json bodydataparameters name searchtoken kind required type string description a token used to authenticate the search request obtained by sending a request to the engine api see obtaining a search token in calling the personalized search api for more information a token used to authenticate the search request obtained by sending a request to the engine api see obtaining a search token in calling the personalized search api for more information name recordqueries kind required type object description the set of parameters that define a request to the personalized search api the set of parameters that define a request to the personalized search api children name id kind required type string description the unique identifier associated with the request name typeofrequest kind required type string description the type of query request use search for personalized site search queries or use catnav for personalized category page queries name settings kind required type object description the set of parameters that define the settings used for search results children name typeofrecords kind required type array description the type of results to return use monetate product for the value when you want personalized search to return products name groupcondition kind optional type object description the set of parameters that define the advanced filtering operation children name groupoperator kind optional type string description the condition for how personalized search applies each filter refer to the first table in filtering conditions for the value options name conditions kind optional type object description the set of parameters that defines each filtering option that the customer selected children name key kind optional type string description the id of the attribute to filter by for example size name valueoperator kind optional type string description the condition for how personalized search applies the attribute defined in key refer to the second table in filtering conditions for the value options name singleselect kind optional type boolean description the behavior when multiple filters or values are specified n nif set to true then the records returned must contain all of the specified filters or values n nif set to false then the records returned must contain at least one of the specified filters or values name excludevaluesinresult kind optional type boolean description use with numeric filters such as price to exclude records with the starting or ending values for example if a price range is defined as 120 135 in the values key and excludevaluesinresult is set to true then personalized search filters on the range of 121 134 n ncan also use to apply a greater than or less than condition to numeric filters for example to filter out records that cost more than 200 set the values key to 200 and set excludevaluesinresult to true name values kind optional type array description an array of values to filter by for example red blue n nwhen using range filters specify the first value as the minimum value for example 60 and the second as the maximum value for example 80 and use key monetate price values 60 80 n nto retrieve bands of prices for example price bands between 0 50 and 150 200 use key monetate price values 0 50 150 200 n nto retrieve exact values for example exact value of 100 or 200 use key monetate price values 100 100 200 200 schema name id kind required type string description the unique identifier associated with the request name typeofrequest kind required type string description the type of query request use search for personalized site search queries or use catnav for personalized category page queries name settings kind required type object description the set of parameters that define the settings used for search results children name typeofrecords kind required type array description the type of results to return use monetate product for the value when you want personalized search to return products name groupcondition kind optional type object description the set of parameters that define the advanced filtering operation children name groupoperator kind optional type string description the condition for how personalized search applies each filter refer to the first table in filtering conditions for the value options name conditions kind optional type object description the set of parameters that defines each filtering option that the customer selected children name key kind optional type string description the id of the attribute to filter by for example size name valueoperator kind optional type string description the condition for how personalized search applies the attribute defined in key refer to the second table in filtering conditions for the value options name singleselect kind optional type boolean description the behavior when multiple filters or values are specified n nif set to true then the records returned must contain all of the specified filters or values n nif set to false then the records returned must contain at least one of the specified filters or values name excludevaluesinresult kind optional type boolean description use with numeric filters such as price to exclude records with the starting or ending values for example if a price range is defined as 120 135 in the values key and excludevaluesinresult is set to true then personalized search filters on the range of 121 134 n ncan also use to apply a greater than or less than condition to numeric filters for example to filter out records that cost more than 200 set the values key to 200 and set excludevaluesinresult to true name values kind optional type array description an array of values to filter by for example red blue n nwhen using range filters specify the first value as the minimum value for example 60 and the second as the maximum value for example 80 and use key monetate price values 60 80 n nto retrieve bands of prices for example price bands between 0 50 and 150 200 use key monetate price values 0 50 150 200 n nto retrieve exact values for example exact value of 100 or 200 use key monetate price values 100 100 200 200 formdataparameters currentnewparameter label body parameter value bodydataparameters hastryitout false response name id kind optional type string description the id of the record query for which the results are being returned name meta kind optional type object description the query related parameters children name qtime kind optional type number description the time personalized search took to fetch the response name noofresults kind optional type number description the number of results requested to be returned for the query name totalresultsfound kind optional type number description the total results found for the query name typeofsearch kind optional type string description the search method s that personalized search used to retrieve the results refer to specifying a search method in personalized site search queries for more information name offset kind optional type string description the index of the first result returned in the response name debugginginformation kind optional type string description information that can be useful for debugging the query for example the actual query that personalized search fired including any synonyms or de compounded words taken into consideration name notificationcode kind optional type number description a code indicating if any actions were taken on the record possible values are as follows n n1 nothing to report n2 the price of the record is using the base currency name searchedterm kind optional type string description the customer s search term submitted for the query name searchtoken kind optional type string description the token returned by the decision request to the engine api sent on page load that contains the relevant information for the experience name ispersonalised kind optional type boolean description whether or not customer context was applied to the results name records kind optional type object description the records matching the query each record object is a map of key value pairs where the key is the name of an attribute for example id name price and its value in the mapped product catalog children name itemgroupid kind optional type string description the identifier for a group of products that come in different versions as set in the value of the item group id attribute in the mapped product catalog name price kind optional type number description the original price of the product before any discounts as set in the value of the price attribute in the mapped product catalog name toprice kind optional type number description the value of saleprice for the variant with the highest price among all variants with the same item group id you can use this key value pair for a from x to y price range name currency kind optional type string description the currency code applicable to the price values being displayed name instock kind optional type string description whether or not the product is in stock the value is either yes or no name id kind optional type string description the unique identifier of the record within personalized search name imagehover kind optional type string description the url for an additional image for the record that appears on mouse hover name sku kind optional type string description a product s unique identifier as set in the value of the id attribute in the mapped product catalog name brand kind optional type string description the product s brand as set in the value of the brand attribute in the mapped product catalog name startprice kind optional type number description the value of saleprice for the variant with the lowest price among all variants with the same item group id you can use this key value pair for an as low as price name image kind optional type string description the fully qualified url for the record s main image name saleprice kind optional type number description the actual selling price of ther product or the now price when used with price when using filters the sale price is represented by monetate price name monetate category kind optional type string description the record s categorization within personalized search with the product name separated from its category hierarchy with double semicolons ;; and then the category hierarchy itself separated by single semicolons for example mybrand tent;;sporting goods;outdoor recreation;camping;tents name url kind optional type string description the fully qualified url the customer used to access the record on your site name name kind optional type string description the name of the record for example the product name or category title name shortdesc kind optional type string description the short description of the record as set in the value of the description attribute in the mapped product catalog name category kind optional type string description a list of a record s most specific categories that excludes the full path with double semicolons ;; used to separate them for example a record in both mens shoes and mens tees has a value of shoes;;tees name filters kind optional type object description the parameters that define the filtering options presented to the customer children filtering conditions use one of the following values with the groupoperator key to determine the operator logic for how the filters are applied value description all of filter records using and logic so that the results match with all the selected filter attributes any of filter records using or logic so that the search results match with at least one of the selected filter attributes none of filter records using negation of and logic so that the search results do not match with any of the selected filter attributes use one of the following values with the valueoperator key value description include personalized search includes the attribute identified in key when it filters the records exclude personalized search excludes the attribute identified in key when it filters the records exists personalized search determines if the attribute identified in key has a valid value for the record not exists personalized search determines if the attribute identified in key doesn't have a valid value for the record to better understand how the exists and not exists value options work, consider these two examples a retailer's mapped product catalog includes a batteriesincluded attribute that is a boolean data type some records have true for this attribute's value, some have false , and other records don't have any value in place when an advanced filtering request pairs "valueoperator" "exists" with "key" "batteriesincluded" , then personalized search returns all records that have true or false for the value of batteriesincluded , but it won't return records lacking a value for this attribute a request that pairs "valueoperator" "not exists" with "key" "batteriesincluded" would return those records lacking a value for this attribute