User to Products API

The engine you want to get results from. When you have more than one engine, you can use this parameter to specify the specific engine you want to get results from. If not specified, the default engine will be used.

The user who made the query and for whom Miso will personalize the results. For an anonymous visitor, use anonymous_id instead.

The anonymous visitor who made the query and for whom Miso will personalize the results. Either user_id or anonymous_id needs to be specified for personalization to work.

The hash of user_id (or anonymous_id) encrypted by your Secret API Key. user_hash is required to prevent unauthorized API access if you are making API calls with a Publishable API Key.

You should generate the user_hash via HMAC scheme: you encrypt the desired user_id (or anonymous_id) with your Secret API Key on your backend server, and then let the front-end code send the generated user_hash to Miso APIs to verify the identity of the API caller.

As long as the Secret API Key is kept secret, the user_hash prevents a malicious attacker from making unauthorized API calls or impersonating any of your users.

Miso APIs accept the case-incentive "hex digest" of user hash, a sample Python 3 code to generate it on your backend server is as follow:

import hashlib
import hmac

YOUR_MISO_SECRET_API_KEY = "039c501ac8dfcac91"
key_bytes = YOUR_MISO_SECRET_API_KEY.encode()
user_id = "USER_123" # or anonymous_id
user_id_bytes = user_id.encode()
user_hash = hmac.new(
    key_bytes,
    user_id_bytes,
    hashlib.sha256).hexdigest()
# user_hash is "7eb04da5e..."

You can find more examples for other languages in this Github Gist

Number of product recommendations to return

The type of products to return. Use this parameter to make the API return only a certain type of products (see Product APIs).

This is particularly useful for sites that have multiple types of products: For example, on a marketplace site, YOu may model merchandise and store as two types of products. You can then use type parameter to limit the recommendation or search results to return only one kind of them.

For instance, the following query will return only store products:

{"type": "store"}

For another example, on a travel website, you might have: hotel, thing to do, and restaurant, three kinds of products. You can use type parameter to limit results to one kind of them. For instance, the following query will limit the results to only hotels product:

{"type": "hotel"}

Whether to dedupe product based on product_group_id. If dedupe_product_group_id=true, Miso will prevent products with the same product_group_id from showing multiple times in the search or recommendation results.

This is particular useful when one product has multiple variants (for example, different sizes, colors, or materials), and you only want to show this product only once in the search or recommendation results. Miso will then return the variant that is most likely to be of the user's interest.

Defines a query in Solr syntax that can be used to restrict the superset of products to return, without influencing the overall ranking. fq can enable users to drill down to products with specific features based on different product attributes

For example, the query below limits the search results to only show products whose size is either M or S and brand is Nike:

{"fq": "size:(\"M\" OR \"S\") AND brand:\"Nike\""}

You can use fq to apply filters against your custom attributes as well. For example, the query below limits the search results to only products whose designer attribute is Calvin Klein

{"fq": "attributes.designer:\"Calvin Klein\""}

fq can also limit search results by numerical range. For example, the following query limits the results to products that have rating >= 4.

{"fq": "rating:[4 TO *]"}

Defines a query in Solr syntax that can be used to boost a subset of products to the top of the ranking, or to specific boost positions (See boost_positions parameter below.) For example, the query below will promote all the relevant products whose brand is Nike to the top of recommendation list:

{
    "boost_fq": "brand:\"Nike\""
}

For a slightly more complex example, the query below will promote the Nike products which have also been tagged as ON SALE to the top of the ranking:

{
   "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\""
}

It is worth mentioning that, Miso will only boost products that are relevant and have high likelihood to convert, and will not boost a low performance product only because it matches the boosting query.

Depending on your boosting rules, in certain cases, you would like to prevent recommendation results from being too monotone due to boosting. With Miso, you have two tools to do so.

First, you can specify boost_positions to place promoted products at specific positions in the ranking. For example, the query below will place boosted products only at the first and fourth places in the ranking (positions are 0-based), and place the remaining products in their original ranking, skipping these two positions.

{
   "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"",
   "boost_positions": [0, 3]
}

The second tool is diversification. diversification parameter, on a best-effort basis, will try to maintain a minimum distance between products that have the same attributes. For example, the following query will place products made by the same brand apart from each other.

{
   "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"",
   "diversification": {
       "brand": {"minimum_distance": 1}
    }
}

Name of the boosting rule. Use this to identify a boosting rule in _boosted_rules in the response

Dithering is an optional parameter (>= 1.0, and typically <= 5.0) in the recommendation APIs that introduces randomness to the order of recommended items. By adding noise to the original ranking, it shuffles the list, surfacing lower-ranked items to enhance list freshness and potentially boost user engagement. However, excessive dithering may reduce the accuracy of item ordering. See this blog post for more information.

A unique identifier to enable pagination in Recommendation APIs. By default, Recommendation APIs do not support pagination because the results from Miso, by its natural, will change in real-time with new user interactions. pagination_id allows you to implement pagination more easily by memorize what products we have returned to the current user with the same pagination_id.

To enable pagination, you generate a pagination_id and set it in the first and subsequent requests in the same browsing session where you want to enable pagination. With pagination_id set, you can access recommendations in different pages using the combination of start and rows parameters, and Miso will ensure that no duplicated recommendation will be returned in different pages.

For example, assuming you are implementing an infinite scroll with Miso Recommendation APIs. Before you make the first request, you generate a pagination_id using the current datetime or uuid like the following:

// current datetime
var my_pagination_id = Date.now().toString()
// OR uuid
const uuidv4 = require("uuid/v4")
var my_pagination_id = uuidv4()

You can then request the first page of results with my_pagination_id like the following:

{
    "pagination_id": my_pagination_id,
    "start": 0,
    "rows": 10
}

Then, you can request the next page of results with the same my_pagination_id, and Miso will ensure that no duplicated result is returned:

{
    "pagination_id": my_pagination_id,
    "start": 10,
    "rows": 10
}

Note that, a pagination_id will timeout if there is no further request associated with it for 30 minutes. Also, pagination_id is scoped by individual users: i.e. different users' results will not be affected even if they use the same pagination_id.

The start of the page you want to access. Combine this with rows to implement pagination. You can only set it when pagination_id is given.