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 Queries
• limit - Limit number of returned recommended items. Optional. Defaults to 10, must not exceed 25.

Recommendations Request Example

GET /recommendations/document/25419?recommendationQueryKey=r-abcdefghjklm&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 with my_query_key) configuration's selectFields;

• recommendFor - The original item (based on the given itemId parameter) reference with the same select fields as defined in the query's selectFields.

Possible Errors

• 400 Bad Request - When the itemId or recommendationQueryKey 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).

Requesting recommendations without specific id

Some recommendation queries do not require a specific item id to be passed. One of the examples could be recommendations in the home page that just show all most popular items. In this case, you can use a special _all wildcard value instead of a specific item id.

GET /recommendations/document/_all?recommendationQueryKey=r-abcdefghjklm&limit=20

{
  "recommended": [
    {
      "id": "84623",
      "name": "Recommended item 1"
    },
    {
      "id": "84624",
      "name": "Recommended item 2"
    }
  ]
}

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.

Recommendations Events

If you are not using LupaSearch client plugin for recommendations, you can still report user interactions with recommended items by sending recommendedItemClick and recommendedAddToCart events. See more: Recommendation Events.