User to Categories API

The User to Categories API returns the product categories that will drive the conversion for the current user, along with the recommended products for each returned category.

Application scenarios

This API is usually used in homepage recommendations, or category recommendations where recommendations are organized by categories, such as Netflix's "Action / Sci-Fi / Drama movies for you" or Amazon's "Recommendations for you in Grocery & Gourmet Food". The goal of such recommendations is to help users discover attractive products under the categories they have a high chance to be interested in.

Basic usage

For basic usage of this API, you just need to let Miso knows the user_id or anonymous_id of the current users. Miso will return a list of top categories along with the recommended Products under each of the categories.

POST https://api.askmiso.com/v1/recommendation/user_to_categories
{
    "user_id": "user-123",
    "rows": 2,
    "products_per_category": 3,
    "fl": ["title"]
}

• rows: the number of categories to return
• products_per_category: the number of Products to return per each category
• fl: like in other Miso API, you can use fl to control which fields to return for each Product

The response of this request will be like:

{
  "message": "success",
  "data": {
    "took": 85,
    "miso_id": "7cd6059c-dd54-11eb-8050-a62d401473b5",
    "categories": [
      {
        "category": [
          "Drama"
        ],
        "total": 61510,
        "recommended_products": [
          {
            "product_id": "tmdb-286217",
            "title": "The Martian (2015)"
          },
          {
            "product_id": "tmdb-281957",
            "title": "The Revenant (2015)"
          },
          {
            "product_id": "tmdb-68718",
            "title": "Django Unchained (2012)"
          }
        ]
      },
      {
        "category": [
          "Thriller"
        ],
        "total": 21870,
        "recommended_products": [
          {
            "product_id": "tmdb-11324",
            "title": "Shutter Island (2010)"
          },
          {
            "product_id": "tmdb-1949",
            "title": "Zodiac (2007)"
          },
          {
            "product_id": "tmdb-1422",
            "title": "The Departed (2006)"
          }
        ]
      }
    ]
  }
}

• categories: a list of categories recommended to the users.
• categories[].category: the recommended category in the format of category hierarchy. ["Sci-Fi"] is a top level category, ["Sci-Fi", "Space Travel"] is a second-level category under Sci-Fi (a.k.a subcategory).
• categories[].total: the total number of Products belonging to the category
• categories[].recommended_products: a list of Products (in that category) recommended to the users

Root Category

By default, User To Categories API recommends top level categories, but you can change this behavior via root_category parameter. Miso will recommend the immediate sub-categories of the given root_category For example, the following request will recommend sub-categories under Science Fiction, for example ["Science Fiction", "Space Travel"] or ["Science Fiction", "Steampunk"]:

POST https://api.askmiso.com/v1/recommendation/user_to_categories
{
    "user_id": "test",
    "root_category": ["Science Fiction"]
}

In some cases you can get recommendations from any subcategory, whatever its parent category. In such case, you can use wildcard * to achieve such results. For example, the following request will recommend any sub-categories regardless their parent category:

POST https://api.askmiso.com/v1/recommendation/user_to_categories
{
    "user_id": "test",
    "root_category": ["*"]
}

Filter and boost query

Like every Miso API, User To Categories supports fq for filtering, and boost_fq for boosting. You can use these parameters to make the recommendation results meet your exact business needs. For example, the following request will recommend categories that contain sufficient number of Products that meet the fq criteria, that is, films after 2010, and each Product returned in the recommended_products list will also meet the fq criteria:

POST https://api.askmiso.com/v1/recommendation/user_to_categories
{
    "user_id": "user-123",
    "rows": 2,
    "products_per_category": 3,
    "fq": "custom_attributes.year: [2010 TO *]"
}

Similarly, you can use boost_fq to promote Products that meet your business criteria in each category. For example, the following request will prioritize Products that are promoted (indicated by custom_attributes.promoted):

POST https://api.askmiso.com/v1/recommendation/user_to_categories
{
    "user_id": "user-123",
    "rows": 2,
    "products_per_category": 3,
    "boost_fq": "custom_attributes.promoted: true"
}

Latency considerations

User To Categories API is one of more complex API because it needs to first identify categories the user will be interested in, and then find the top Products in that categories. We make this process real-time by pre-computing a large number of top Products for each category, therefore the end-to-end latency is usually under 100ms. To further reduce the latency, you can:

• Use a smaller products_per_category to reduce number of products to return, or set it to zero if you do not need any.
• Request only the necessary fields using fl parameters
• Use a smaller rows to reduce number of categories to return