Recommendations
Overview
The Recommendations API is designed to suggest similar items to a given item, based on user engagement behavior and item similarity. It can be used to provide similar or complementary product recommendations for your users. To get recommendations for a specific item, you need to use the /recommendations/document/{itemId}
endpoint.
Get Recommendations for a Specific Item
API Reference: Recommendations
To get recommendations for a specific item, send an HTTP GET request to /recommendations/document/{itemId}?recommendationQueryKey={queryKey}&limit=10
endpoint with the following parameters:
itemId
- The ID of the item for which you want to get recommendations;recommendationQueryKey
- The key of recommendation query key to load configurations from. See more: Recommendation Querieslimit
- Limit number of returned recommended items. Optional. Defaults to 10, must not exceed 25.
Recommendations Request Example
GET /recommendations/document/25419?recommendationQueryKey=my_query_key&limit=20
{
"recommended": [
{
"id": "84623",
"name": "Recommended item 1"
},
{
"id": "84624",
"name": "Recommended item 2"
}
],
"recommendFor": {
"id": "25419",
"name": "Original Item"
}
}
Response Description
recommended
- An array of recommended items. Each item has properties defined in the given query's (one referenced withmy_query_key
) configuration'sselectFields
;recommendFor
- The original item (based on the givenitemId
parameter) reference with the same select fields as defined in the query's selectFields
.
Possible Errors
400 Bad Request
- When theitemId
orrecommendationQueryKey
is invalid or missing. Check the error response for more information about the issue.
Note: The Recommendations API relies on analyzing user engagement behavior through the Events API. To ensure even more accurate product recommendations, make sure to report user engagement events appropriately, although this is not strictly required and without it, recommendations api will fallback to using static product data instead (if you configured Similar attributes
source in recommendation query configuration).
Limiting returned fields
You can use select fields parameter to limit returned document fields in response. Fields must be configured as selectableFields
in the original query with given query key.
GET /recommendations/document/25419?recommendationQueryKey=my_query_key&selectFields=id&selectFields=tag
{
"recommended": [
{
"id": "84623",
"tag": "Tag 1"
},
{
"id": "84624",
"tag": "Tag 2"
}
],
"recommendFor": {
"id": "25419",
"tag": "Tag 0"
}
}
Filtering recommendation results
It is possible to use filters
to filter . Fields must be configured as filterableFields
in the original query with given query key. You can use all of the filter types that available for Query Filters, but they need to be converted into GET query parameters.
GET /recommendations/document/25419?queryKey=my_query_key&filters[brand][0]=Samsung&filters[brand][1]=LG
Product recommendations in dashboard
To preview product recommendations in your dashboard, go to Test Your Search page, type in any desired query and simply click on a product you want to get recommendations for.
The blue badges in front of recommended product ids indicate the relative relevance of a recommendation, that can fall in a range from 0 to 100.
Recommender by multiple products
There might be use cases where you want to get recommendations for a user based on multiple products. For example, you might want to get recommendations for a user based on all products that they have added to their cart.
This use case is covered by a separate endpoint: /recommendations/documentsByMultipleIds
. It accepts a list of product ids and returns recommendations for a user based on all of them.
GET /recommendations/documentsByMultipleIds?itemId[]=1&itemId[]=2&itemId[]=3&recommendationQueryKey=my_query_key
The response is the same as for the /recommendations/document/{itemId}
endpoint, except that the recommendFor
field is not present.
{
"recommended": [
{
"id": "84623",
"name": "Recommended item 1"
},
{
"id": "84624",
"name": "Recommended item 2"
}
]
}
Important: number of requested itemIds should not exceed 20.