Filtering

Narrow down search results based on any product attribute

Example for 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”).

The following steps assume you have already set up an engine for Search. If not, head over to the Quickstart guide to get started.

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:

The fq parameter uses Lucene query syntax and you must use escape characters ( \ ) for quotations.
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:

New Release Books.png

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 limit search results using comparison operators such as greater than (>) or less than or equal to (≤). For example, you can limit results to products that have rating >= 4.

  • 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 carshotels, 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

API Reference

💻

Need more info on the API? Check out our dedicated API page with all the info you could ever want.

Read API Reference
Icon/Activity Icon/Add Icon/API Icon/Arrow/Down Icon/Arrow/Left Icon/Arrow/Right Icon/Arrow/TopRight Icon/Arrow/Up Icon/Bento Icon/Billing Icon/Bin Icon/Book Icon/Bookmark/Default Icon/Bookmark/Filled Icon/Calendar Icon/Caret/Down Icon/Caret/Up Icon/Chavron/DownIcon/Chavron/LeftIcon/Chavron/RightIcon/Chavron/UpIcon/Checknox/CheckedIcon/Checknox/Unchecked Icon/Checklist Icon/Chip Icon/Clipboard / Copied Icon/Clipboard/Default Icon/Clock/Stopwatch Icon/CMD Icon/Data/Catalog Icon/Data/Engine Icon/Data/Group Icon/Data/Interact Icon/Data/Users Icon/Dive Icon/Docs/Key Icon/Dojo Icon/Email Icon/Env/Development Icon/Env/Playground Icon/Env/Prod Icon/Folder Icon/Fullscreen/Collapse Icon/Fullscreen/Expand Icon/Guides/Multiple Icon/Guides/Single Icon/Hashtag Icon/Heart/Outline Icon/Heart/Solid Icon / Cart z Icon / Click Icon / Clock Icon / Data Icon / Doc Icon / EmptyCart z Icon/Social/Facebook Icon / Genome Incognito Icon / Money Icon/Social/ProductHunt Icon / Search Icon/Social/Twitter Icon / User Icon/Info/Error Icon/Info/Info Icon/Info/Question Icon/Info/Warning Icon/Interact/Download Icon/Interact/Edit Icon/Interact/External v2 Icon/Interact/External Icon/Interact/Filter Icon/Interact/Logout Icon/Interact/Options Icon/Interact/Re-order Icon/Interact/Reload Icon/Interact/Remove Icon/Interact/Replace Icon/Interact/Search Icon/Interact/Shuffle Icon/Interact/Undo Icon/Interact/Upload Icon/Interact/Video Icon/Invoice Icon/Loading Icon/Loading Icon/Lock/Locked Icon/Lock/Unlocked Icon/Lock Icon/Mapping Menu Icon/Notification Icon/Overview Icon/Person/Team Icon/Person/User Icon/Plan/Enterprise Icon/Plan/Growth Icon/Plan/Startup Icon/Plan/Trial Icon/Recipe Icon/Rocket Icon/Settings/App Icon/Settings/User Icon/Settings Icon/Shrine Icon/Sidebar/Close Icon/Sidebar/Open Icon/Slideout Icon/Sort/Ascending Icon/Sort/Default Icon/Sort/Descending Icon/Star/Filled Icon/Star/Outlined Stopwatch Icon/Support Icon/Tag Icon/Interact/Thumb/Dislike Icon/Interact/Thumb/Like Icon/Tick Icon/Trend/New Icon/Trend/Trending Icon/Tutorial Icon/Lock/Unlocked Icon/View/Grid Icon/View/List Icon/Watchlist/Add