v1

latestOpenAPI 3.0.22026-08-0426137631.3 KB

Recommendation APIs

User to Attributes API

The User to Attributes API is a generalized version of User to Categories API --- it returns the product attributes that Miso expects to drive a conversion for the current user. You specify a field in your Product catalog you want recommendations for, e.g. the brand or a custom field like custom_attributes.director, and this API will return a list of values from that fields Miso expects users will be most interested in, as well as a list of personalized product suggestions.

Applicable scenarios

This API is usually used in homepage recommendations, where users can interact with recommended attributes. For example, this API could generate suggestions for "the brands you may like" or "the creators you may like."

Basic usage

For basic usage of this API, you just need to let Miso knows the user_id or anonymous_id, and the field you want to get recommendations for. For example, the following request will return the recommended director for the given users:

POST https://api.askmiso.com/v1/recommendation/user_to_attributes
{
    "user_id": "test",
    "field": "custom_attributes.director",
    "rows": 3,
    "products_per_attribute": 2,
    "fl": ["title"]
}

field: the name of the field you want to get recommendation for
rows: the number of categories to return
products_per_attribute: the number of Products to return per each attribute
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": 296,
    "miso_id": "9d7c8d9c-dd73-11eb-b20d-9a566192e5c6",
    "attributes": [
      {
        "value": "Christopher Nolan",
        "total": 12,
        "recommended_products": [
          {
            "product_id": "tmdb-272",
            "title": "Batman Begins (2005)"
          },
          {
            "product_id": "tmdb-77",
            "title": "Memento (2000)"
          }
        ]
      },
      {
        "value": "Ridley Scott",
        "total": 26,
        "recommended_products": [
          {
            "product_id": "tmdb-286217",
            "title": "The Martian (2015)"
          },
          {
            "product_id": "tmdb-4982",
            "title": "American Gangster (2007)"
          }
        ]
      },
      {
        "value": "Quentin Tarantino",
        "total": 13,
        "recommended_products": [
          {
            "product_id": "tmdb-680",
            "title": "Pulp Fiction (1994)"
          },
          {
            "product_id": "tmdb-68718",
            "title": "Django Unchained (2012)"
          }
        ]
      }
    ]
  }
}

attributes: a list of attributes recommended to the users.
attributes[ ].value: the recommended attribute value (in this case, director name)
attributes[ ].total: the total number of Products that have this attribute
attributes[ ].recommended_products: a list of Products (with the attribute) recommended to the users

post/v1/recommendation/user_to_attributes

Request body

boosting_tagsstring[]

When boosting_tags is given, and there are pre-defined boost rules have the same tag(s), those boost rules will be matched, regardless if the criteria is met or not.

Useful when want to force trigger specific boost campaign.

fieldstring required

The attribute you want to make recommendations for. For example, the following query will recommend values from the brand field that Miso thinks the user will be interested in:

{"field": "brand"}

This API also works for custom attributes you define. For example, if you provide a designer custom attribute, then, you can make designer recommendations with the following query.

{"field": "custom_attributes.designer"}

boost_attributesstring[]

The attributes to boost to the top of the recommendations

exclude_attributesstring[]

The attributes to remove from the recommendations

rowsinteger

Number of product recommendations to return

products_per_attributeinteger

Number of personalized product recommendations to make for each recommended attribute. For example, the following query will return 5 products for each brand we recommend:

{
    "field": "brand",
    "products_per_attribute": 2
}

Note that a large number of products_per_attribute will increase latency slightly because we need to perform more computation for each of the recommended attributes. If you only need attribute recommendations, you can set products_per_attribute=0 to reduce latency.

engine_idstring

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.

user_idstring

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

anonymous_idstring

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.

user_hashstring

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

user_cohortobject

The user cohort you want to cold-start the recommendation with. For example, the following query will make recommendations based on the preferences of the users whose country="United States", and gender="Female" in the User Profile dataset.

{
    "user_cohort": {
        "country": "United States",
        "gender": "Female"
    }
}

typestring

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"}

dedupe_product_group_idboolean

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.

flstring[]

List of fields to retrieve. For example, the following request retrieves only the title field of each product along with the product_id, which is always returned.

{"fl": ["title"]}

You can also match field names by using * as a wildcard. For example, the query below retrieves the title and any custom attributes under the attributes dictionary.

{"fl": ["title", "attributes.*"]}

The following retrieves all the available fields:

{"fl": ["*"]}

For the lowest latency, use an empty array to retrieve just the product_id field (which is the default).

{"fl": []}

excludestring[]

An array of product_ids of products you want to exclude from search results.

custom_contextobject

Dictionary of custom context variables for the current browsing session. You can specify context variables specific to your websites or apps in a {"KEY":VALUE} format, where KEY must be a string, and VALUE can be:

a bool
a string or an array of string
a number or an array of numbers
an array of objects
null

In certain cases, Miso will take these variables into account when generating results.

fqstring

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 *]"}

boost_fqstring

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}
    }
}

boost_positionsinteger[]

Defines a list of 0-based positions you want to place the boosted products at.

For example, the query below will promote products whose brand is Nike as the top and second recommendations:

{
    "boost_fq": "brand:\"Nike\"",
    "boost_positions": [0, 1]
}

If boost_positions is not specified (which is the default behavior), all the boosted products will be ranked higher than the rest of the products.

boost_rule_namestring

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

Example request

{
  "boosting_tags": [
    "tag-1",
    "quetag-2"
  ],
  "additional_interactions": [
    {
      "duration": 61.5,
      "product_ids": [
        "123ABC-BLACK"
      ],
      "product_group_ids": [
        "123ABC"
      ],
      "user_id": "user_1234",
      "anonymous_id": "86D51273AD8BF84217E1567B6CBE7152D7034404",
      "miso_id": "123e4567-e89b-12d3-a456-426614174000",
      "context": {
        "campaign": {
          "name": "spring_sale",
          "source": "Google",
          "medium": "cpc",
          "term": "running+shoes",
          "content": "textlink"
        },
        "truncated_ip": "1.1.1.0",
        "locale": "en-US",
        "region": "US East",
        "page": {
          "url": "https://example.com/miso-tshirt-123ABC",
          "referrer": "https://example.com/",
          "title": "My Product Page"
        },
        "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0",
        "custom_context": {
          "session_variable_1": [
            "value_1",
            "value_2"
          ]
        }
      }
    }
  ],
  "custom_context": {
    "session_variable_1": [
      "value_1",
      "value_2"
    ]
  }
}

Response

Successful Response

messagestring

Example response

{
  "data": {
    "miso_id": "123e4567-e89b-12d3-a456-426614174000",
    "attributes": [
      {
        "value": "Miso T-Shirt Shop",
        "total": 1000,
        "recommended_products": [
          {
            "product_id": "123ABC-S-Black"
          }
        ]
      }
    ]
  }
}