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 https //docs monetate com/docs/personalized search customizations#facets section of search results customizations https //docs monetate com/docs/personalized search customizations as well as manage facets for category pages https //docs monetate com/docs/personalized category pages facets 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 https //docs monetate com/docs/personalized site search or personalized category pages https //docs monetate com/docs/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 https //docs monetate com/docs/product catalog specification#custom fields 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 facets docid\ epxtjiessh4 dsis 3wa1 reference for more information the example request and response in the retrieve facets reference 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