User to Products API

Returns the products that are most likely to drive conversion for the given user. Depending on the conversion metrics you choose when training your Miso Engines in Dojo, this API returns products that are most likely to optimize those metrics (such as add_to_cart, checkout, or read).

This API considers both user's interests and the conversion probability. The user's interests are determined from their past interactions on the site and the context of their current browsing session, including recent trending products, time of the day, and recent search behavior.

Application scenarios

The User to Products API is usually used in homepage recommendations, such as "Inspired by your shopping trends" on Amazon, or "Recommended videos" on Youtube. It can also be used to run an email marketing campaign such as a newsletter from Medium with recent articles you can like. These recommendations work especially well in driving product discovery.

Basic usage

For basic usage of this API, you just need to let Miso knows the id of the current user or visitor via user_id or anonymous_id field. For example, for a currently logged-in user, your request looks like this:

POST /v1/recommendation/user_to_products
{"user_id": "user-123"}

For a un-signed visitor, your request looks like this:

POST /v1/recommendation/user_to_products
{"anonymous_id": "visitor-123"}

This API will respond with the recommended products for the specified user or visitor:

{
  "message": "success",
  "data": {
    "took": 37,
    "miso_id": "517452b0-0ccf-11eb-948d-66359cf29022",
    "products": [
      {
        "product_id": "tmdb-475557",
        "_personalization_score": 0.91
      },
      {
        "product_id": "tmdb-299534",
        "_personalization_score": 0.89
      },
      ...
    ]
  }
}

• took: the amount of time (in milliseconds) Miso took to answer the query
• miso_id: a UUID of the search request. Include miso_id in the Interaction records for every interactions that result from this search request, for example, a user clicking through to a product in the search results. Miso use miso_id to track the search performance and fine-tune the algorithm accordingly.
• products: an array of Product records recommended to this user ranked by the probability that the user will be interested in this product. By default, only the product_id of the Product is returned. You can ask Miso to return additional fields by using the fl request argument (see example below)
• products[ ]._personalization_score: the score assigned by Miso's personalization algorithm based on users' profile and their interactions on the site. This score quantifies the probability of whether users will be interested in this product or not.

You can use the fl request argument to ask Miso to return more product fields. For example, the following request asks Miso to additionally return the title and category fields of every recommended product:

POST /v1/recommendation/user_to_products
{
    "user_id": "user-123",
    "fl": ["title", "categories"]
}

The response will be like:

{
  "message": "success",
  "data": {
    "took": 37,
    "miso_id": "517452b0-0ccf-11eb-948d-66359cf29022",
    "products": [
      {
        "product_id": "tmdb-475557",
        "categories": [
          [
            "Crime"
          ],
          [
            "Thriller"
          ],
          [
            "Drama"
          ]
        ],
        "title": "Joker (2019)",
        "_personalization_score": 0.91
      },
      {
        "product_id": "tmdb-299534",
        "categories": [
          [
            "Adventure"
          ],
          [
            "Science Fiction"
          ],
          [
            "Action"
          ]
        ],
        "title": "Avengers: Endgame (2019)",
        "_personalization_score": 0.89
      },
     ...
    ]
  }
}

Filtering and Boosting

Like every other Miso API, User To Products API supports filter query (fq) and boost query (boost_fq) to generate recommendations that meet your business needs.

Filter Query

You can use filter query to filter recommendation results against arbitrary criteria, and Miso will guarantee to return sufficient number of recommendation results that meet the criteria. For example, the following requests will limit the recommendations to only Drama films:

POST /v1/recommendation/user_to_products
{
    "user_id": "user-123",
    "fl": ["title", "categories"],
    "fq": "categories:Drama"
}

For another example with custom_attributes, the following requests will limit the recommendations to only Drama films after 2010:

POST /v1/recommendation/user_to_products
{
    "user_id": "user-123",
    "fl": ["title", "categories"],
    "fq": "categories:Drama AND custom_attributes.year:[…"
}

Latency Consideration

Miso achieves instant recommendations by pre-computing a large pool of candidates (N>1,000) for each user with the products they are mostly likely to be interested in. However, when the given filter query do not match a sufficient number of candidates, Miso will fall back to Search API to find additional matches to fill in the remaining slots. While falling back to Search API will increase the latency, the latency increase is usually minimum if the same filter query is being used repeatedly due to Miso's caching mechanism.

Boost Query

You can use boost_fq to boost Products with arbitrary criteria. The relevant Products that match the boost_fq will be ranked at the top of the recommendations or at the positions specified in the boost_positions parameter. Boosting is useful for product promotions, for example sponsored products, to highlight the Products you want more impression.

For example, the following request will boost the Sci-Fi films directed by Ridley Scott:

POST /v1/recommendation/user_to_products
{
  "user_id": "user-123",
  "fl": [
    "title",
    "categories"
  ],
  "boost_fq": "categories:\"Sci-Fi\" AND custom_attribut…"
}

The response will be like:

{
  "message": "success",
  "data": {
    "took": 83,
    "miso_id": "54bf6d9a-dd32-11eb-99d6-a62d401473b5",
    "products": [
      {
        "product_id": "tmdb-286217",
        "title": "The Martian (2015)",
        "_personalization_score": 0.5364759309088403,
        "_boosted": true,
        "categories": [
          [
            "Drama"
          ],
          [
            "Adventure"
          ],
          [
            "Science Fiction"
          ]
        ]
      },
      ...
    ]
  }
}

The additional field products[ ].boosted is a boolean that indicates whether the Product matches the boost_fq.

You can also use boost_positions to specify the positions in the recommendation list you want the boosted Products to be placed. For example, the following request will place the boosted Product at the second place, and the third place (the boost_positions are 0-based):

POST /v1/recommendation/user_to_products
{
  "user_id": "user-123",
  "fl": [
    "title",
    "categories"
  ],
  "boost_fq": "categories:\"Sci-Fi\" AND custom_attribu…",
  "boost_positions": [
    1,
    2
  ]
}

Filtering "already seen" items

Typically, the User to Products API is used to let users discover new products. Therefore, it is important not to recommend products users have already interacted with recently. By default, the User to Products API filters out the most recent 50 products users have had interactions with (except for impression interactions)