User to Categories API

Authorizations

api_key

string

query

required

Your secret API key is used to access every Miso API endpoint. You should secure this key and only use it on a backend server. Never leave this key in your client-side JavaScript code. If the private key is compromised, you can revoke it in Dojo and get a new one.

Specify your secret key in the api_key query parameter. For example:

POST /v1/users?api_key=039c501ac8dfcac91c6f05601cee876e1cc07e17

Body

application/json

Attributes for recommendation boosting

engine_id

string

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_id

string

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

anonymous_id

string

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_hash

string

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_cohort

User Cohort · object

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

Show child attributes

rows

integer

default:5

Number of recommended categories to return

type

string

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_id

boolean

default:true

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.

additional_interactions

A list of additional interaction records. You can use this fields to simulate user interactions without actually writing them to the interaction dataset.

Show child attributes

string[]

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": []}

exclude

string[]

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

custom_context

Custom Context · object

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.

Example:

{
  "session_variable_1": ["value_1", "value_2"]
}

boosting_tags

string[]

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.

Example:

["tag-1", "quetag-2"]

products_per_category

integer

default:5

Number of products to return for each category. For example, the following query will return 5 products for each category we recommend:

{"products": 5}

Note that, a large number of products_per_category (say >= 20) will increase query latency (up to around 200ms) because we need to perform more computation for each of the recommended categories. If you only need category recommendations, you should set products_per_category to 0 to reduce latency.

root_category

string[]

If root_category is specified, we will only recommend categories that are direct children of each of the root category. For example, the following query will recommend the products of category that is under ["Clothes"] category:

{"root_category": ["Clothes"]}

For another example, the following query will recommend the products of category that is under ["Clothes", "Dresses"] category

{"root_category": ["Clothes", "Dresses"]}

If root_category is not specified, we will recommend the top level categories.

string

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_fq

string

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_positions

integer[]

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_name

string

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

boost_rules

BoostingFilterBase · object[]

Define a list of boosting rules that will be applied to the search or recommendation results simultaneously. boost_rules parameter is particularly useful when you want to boost more than one sets of products, and promote each of them to different positions. For example, the query below will promote products whose brand is Nike to the top and second results, and products whose brand is Adidas to the third and fourth results:

{
    "boost_rules": [
        {
            "boost_fq": "brand:\"Nike\"",
            "boost_positions": [0, 1]
        },
        {
            "boost_fq": "brand:\"Adidas\"",
            "boost_positions": [2, 3]
        }
    ]
}

Show child attributes

geo

Geo · object

When set, filter result to include only products within certain geographic range from given point will be returned, or to boost product within the same range.

Product should have a field that holds the location of the product, location is used by default, but other field can also be used.

Distance can be in miles or kilometers. If distance_unit is not set, mile will be used.

For example, to limit results to products within 100 miles of New York city:

{
    "geo": {
        "filter": [{
            "lat": 40.73061,
            "lon": -73.93524,
            "distance": 100
        }]
    }
}

To boost products within 2 kilometers around Alcatraz Island according to loc field:

{
    "geo": {
        "boost": [{
            "field": "loc",
            "lat": 37.82667,
            "lon": -122.42278,
            "distance": 2,
            "distance_unit": "km"
        }]
    }
}

Show child attributes

Response

Successful Response

data

CategoryResponseBody · object

required

Show child attributes

message

string

default:success

Overview

Authentication

DATA APIs

Engine APIs

Experiment APIs

Q&A APIs

Application scenarios

Basic usage

Root Category

Filter and boost query

Latency considerations

Authorizations

Body

Response