--- title: Retrieve and Apply Facets slug: personalized-search/facets description: How to make POST calls to retrieve and apply filtering facets in Monetate's Personalized Search API image: https://archbee-image-uploads.s3.amazonaws.com/ceIfEvQHzQk1IVxoRWUh7/K9eTL4jKm7UQINb6zNziJ-20250912-181225.png docTags: createdAt: 2024-12-04T18:06:58.555Z --- 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. :::hint{type="info"} 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 :::hint{type="warning"} 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. :::hint{type="info"} 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. ::: :::ApiMethodV2 ```json { "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. :::CodeblockTabs Example Request to Retrieve Price Facet in Slider Format ```json { "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 ```json { "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`: :::CodeblockTabs Example Code to Revise the monetate\_price Label ```javascript 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. :::ApiMethodV2 ```json { "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. :::ApiMethodV2 ```json { "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.