Calling the Personalized Searc...
Retrieve and Apply Facets

Facets are attribute categories for records that customers can use to further filter results. For example, if a customer searches for shirts, the available facets might include size, color, or material type. Refer to the Facets section of Search Results Customizations as well as Manage Facets for Category Pages in the Monetate Knowledge Base for more information.
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 parameter set to true.
You must contact your dedicated Customer Success Manager (CSM) if you want to use a rating filter ("key": "rating" in the request).
POST
Request
Response
Body Parameters
filters
optional
Object
Defines the filtering options presented to the customer.
Example Request for Retrieving Facets
{
  "search_token": "monetate-156925593843210765",
  "recordQueries": [
    {
      "filters": {
        "filtersToReturn": {
          "enabled": true
        }
      }
      "id": "productSearch",
      "typeOfRequest": "SEARCH",
      "settings": {
        "query": {
          "term": "short"
        },
        "limit": 5,
        "typeOfRecords": [
          "MONETATE_PRODUCT"
        ]
      }
    }
  ]
}
{
  "search_token": "monetate-156925593843210765",
  "recordQueries": [
    {
      "filters": {
        "filtersToReturn": {
          "enabled": true
        }
      }
      "id": "productSearch",
      "typeOfRequest": "SEARCH",
      "settings": {
        "query": {
          "term": "short"
        },
        "limit": 5,
        "typeOfRecords": [
          "MONETATE_PRODUCT"
        ]
      }
    }
  ]
}
Responses
200
{
  "filters": [
    {
      "key": "category",
      "label": "category",
      "type": "OPTIONS",
      "options": [
        {
          "count": 3,
          "name": "Capri",
          "value": "Capri",
          "selected": false
        },
        {
          ... Additional options ...
        }
      ]
    },
    {
      ... Additional facets ...
    }
  ]
}
{
  "filters": [
    {
      "key": "category",
      "label": "category",
      "type": "OPTIONS",
      "options": [
        {
          "count": 3,
          "name": "Capri",
          "value": "Capri",
          "selected": false
        },
        {
          ... Additional options ...
        }
      ]
    },
    {
      ... Additional facets ...
    }
  ]
}
﻿
The facets appear on your site as filters that the customer can apply to further narrow the search results.
The following example is a request with more optional parameters in the filtersToReturn object, along with the response:
Request for Retrieving Facets with Optional Parameters Example
Response
{
    "queryResults": [
        {
            "id": "productSearch",
            "meta": {
                "qTime": 17,
                "noOfResults": 0,
                "totalResultsFound": 104,
                "typeOfSearch": "WILDCARD_AND",
                "offset": 0,
                "debuggingInformation": {},
                "notificationCode": 1,
                "searchedTerm": "short",
                "apiKey": "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": "KKE",
                            "value": "KKE",
                            "selected": false
                        },
                        {
                            "count": 1,
                            "name": "KKE New",
                            "value": "KKE New",
                            "selected": false
                        },
                        {
                            "count": 45,
                            "name": "KSD",
                            "value": "KSD",
                            "selected": false
                        },
                        {
                            "count": 30,
                            "name": "MNH",
                            "value": "MNH",
                            "selected": false
                        }
                    ]
                },
                {
                    "key": "Price Range",
                    "label": "Price Range",
                    "type": "OPTIONS",
                    "options": [
                        {
                            "count": 95,
                            "name": "0 - 49",
                            "value": "0 - 49",
                            "selected": false
                        },
                        {
                            "count": 9,
                            "name": "50 - 99",
                            "value": "50 - 99",
                            "selected": false
                        }
                    ]
                }
            ]
        }
    ]
}
{
    "queryResults": [
        {
            "id": "productSearch",
            "meta": {
                "qTime": 17,
                "noOfResults": 0,
                "totalResultsFound": 104,
                "typeOfSearch": "WILDCARD_AND",
                "offset": 0,
                "debuggingInformation": {},
                "notificationCode": 1,
                "searchedTerm": "short",
                "apiKey": "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": "KKE",
                            "value": "KKE",
                            "selected": false
                        },
                        {
                            "count": 1,
                            "name": "KKE New",
                            "value": "KKE New",
                            "selected": false
                        },
                        {
                            "count": 45,
                            "name": "KSD",
                            "value": "KSD",
                            "selected": false
                        },
                        {
                            "count": 30,
                            "name": "MNH",
                            "value": "MNH",
                            "selected": false
                        }
                    ]
                },
                {
                    "key": "Price Range",
                    "label": "Price Range",
                    "type": "OPTIONS",
                    "options": [
                        {
                            "count": 95,
                            "name": "0 - 49",
                            "value": "0 - 49",
                            "selected": false
                        },
                        {
                            "count": 9,
                            "name": "50 - 99",
                            "value": "50 - 99",
                            "selected": false
                        }
                    ]
                }
            ]
        }
    ]
}
﻿
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.
Example Request with Applied Facets
{
  "search_token": "monetate-156925593843210765",
  "recordQueries": [
    {
      "filters": {
        "applyFilters": {
          "filters": [
            {
              "key": "size",
              "values": [
                "Small",
                "Medium"
              ],
              "settings": {
                "singleSelect": false
              }
            }
          ]
        }
      },
      "id": "productSearch",
      "typeOfRequest": "SEARCH",
      "settings": {
        "query": {
          "term": "short"
        },
        "limit": 5,
        "typeOfRecords": [
          "MONETATE_PRODUCT"
        ]
      }
    }
  ]
}
{
  "search_token": "monetate-156925593843210765",
  "recordQueries": [
    {
      "filters": {
        "applyFilters": {
          "filters": [
            {
              "key": "size",
              "values": [
                "Small",
                "Medium"
              ],
              "settings": {
                "singleSelect": false
              }
            }
          ]
        }
      },
      "id": "productSearch",
      "typeOfRequest": "SEARCH",
      "settings": {
        "query": {
          "term": "short"
        },
        "limit": 5,
        "typeOfRecords": [
          "MONETATE_PRODUCT"
        ]
      }
    }
  ]
}
﻿
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.
Applying facets filters out any record for which the facet attribute doesn't match the specified value. You can apply multiple facets to further filter results.
The singleSelect parameter determines the result when multiple values are specified for a facet. When it's set to true, the records returned must contain all the values. When it's set to false, the records returned must contain at least one of the values.
Updated 12 Dec 2024
Calling the Personalized Search API
Analytics