Filtering

Introduction

Filtering enables you to narrow down your search results or recommendations based on predefined product criteria. In e-commerce, common uses of filtering include category pages such as “New Release Books You May Like”, or instant typeahead search such as “Search for blue blazers in Coats and Outerwear”.

Miso’s Search and Recommendation APIs provide a flexible interface for defining filters on any product attribute (including custom attributes) and the ability to combine multiple conditions using logical operators (e.g. “and”, “or”, “not”).

Do it with APIs

The fq (filter query) parameter, available in every Miso API, allows you to specify a condition, or a set of conditions, to apply filtering on.

Basic Usage

Suppose we’d like to limit our search results to only include Nike-branded products. Our API request, using Miso’s Search API would like this:

POST /v1/search/search
{
    "q": "running shoes",
    "user_id": "user-123"
    "fq": "brand:\"Nike\""
}

We can add additional conditions on the filter by using logical operators. Suppose we’d like to only show Nike-branded products that are on sale:

POST /v1/search/search
{
    "q": "running shoes",
    "user_id": "user-123"
    "fq": "brand:\"Nike\" AND tags:\"ON SALE\""
}

Case Study: Category Shelves for a Bookstore

An online bookstore is aiming to create a more personalized user-experience, based on their customer’s browsing and purchase history. They would like to recommend recently published books from specific genres that their customers enjoy and display them on the homepage. Below is an example of category shelves:

Using Miso’s User to Categories API, we can produce the necessary data with a single API call.

POST /v1/recommendation/user_to_categories
{
     "user_id": "user_123",
     "rows": 2, //return two categories, as in the above mockup
     "products_per_category": 3,
     "fl": ["title"] //include the product field "title" in the results
     "fq": "custom_attributes.publication_yr: [2020 to *]"
}

The response would look something like this:

{
  "message": "success",
  "data": {
    "took": 85,
    "miso_id": "7cd6059c-dd54-11eb-8050-a62d401473b5",
    "categories": [
      {
        "category": [
          "Non-Fiction Sports"
        ],
        "total": 2445,
        "recommended_products": [
          {
            "product_id": "0593237935",
            "title": "The Big East"
          },
          {
            "product_id": "0306824205",
            "title": "Friday Night Lights"
          },
          {
            "product_id": "1538719266",
            "title": "The Master"
          }
        ]
      },
      {
        "category": [
          "Historical Fiction"
        ],
        "total": 9388,
        "recommended_products": [
          {
            "product_id": "0735219109",
            "title": "Where the Crawdads Sing"
          },
          {
            "product_id": "0593128176",
            "title": "The Beekeeper of Aleppo"
          },
          {
            "product_id": "154203387X",
            "title": "A Train to Moscow"
          }
        ]
      }
    ]
  }
}

Tips and Tricks

• Before implementing a filter via API, you can visually preview the results with Dojo. Open the Advanced Settings pane in either the Search or Recommendation Engine Sandbox and enter criteria inside the “FQ” box to start testing filter parameters.

• To specify an open range of values, you can use an asterisk (*)as a wildcard. For example, "fq" : "size: [7 to *]" selects all sizes 7 and up. You can also use a range of values to implement a comparison operator. For example, you can limit results to products that have rating >= 4 by setting a filter, "fq" : "rating: [4 to *]". Square brackets ([ ]) indicate that the end points in the range are inclusive and curly brackets ({ }) indicate that the end points are exclusive.

• There are other ways to filter search results without using the fq parameter:

  • type: You can use this parameter to make the API return only a certain type of products. For example, a travel site might have rental cars, hotels, and activities and want to restrict the results to a certain kind of product.
  • dedupe_product_group_id: If this is set to true, Miso will prevent products with the same product_group_id from showing multiple times in the search or recommendation results. This is particularly useful when one product has multiple variants (for example, different sizes, colors, or materials), but you want to show this product only once in the results. Miso will return the variant that is most likely to interest the user.
  • exclude: An array of product_ids of products you want to exclude from search results.

Additional Resources

For more information on Miso’s Search API, check out the official API Documentation.

For additional personalization use-cases, visit the Recipes page on our Docs site.

Published Date: February 25th, 2022