Skip to content

Personalized Feed

There are two recommend endpoints that can be used to personalize the user feed when they come to your website homepage or other similar pages.

  1. users/recommend: This endpoint recommends personalized items to each user.
  2. users/search/recommend: This endpoint recommends personalized items to each users based on their search history.

Below, let's understand how to implement both of this endpoints

1. users/recommend

v1/users/recommend endpoint understands user behavior such as browse history, purchase history, favorites/wishlist, time spent in your application and returns the most suitable items for them as a response.

Checkout the endpoint in our sandbox here.

Here is an example request body

{
  "user_id": "a0cc6beb-2909-459b-be55-62196af78ce4",
  "member_id": "df3456tg-2909-459b-be55-62196afedf85",
  "top_n_item": 100,
  "interval": "weekly",
  "flags": {
    "flag1": true,
    "flag2": false
  },
  "start": 0,
  "size": 10,
  "details": true
}

Let's go through each parameters:

  • user_id: Represents the id of a logged-out unique user. This is usually saved in the user's browser or app local storage.
  • member_id: This optional field represents the id of a logged-in unique user. This could be user Phone number or Email address. Something that can uniquely identify the user across devices.
  • interval: Selected enum value. Represents the time range for predicting trending and top recommended items. Available values: weekly, bi-weekly, monthly, quarterly, yearly. Should be similar to the interval parameter of ../rank/settings endpoint.
  • top_n_item: Represents the number of top ranked items in the given time interval.
  • flags: These are the flags that are set in the mapper. You can use this to include or exclude certain products, such as include items that are on sale, or exclude items that are out of stock, etc.
  • start: Index number of the first result to show.
  • size: Number of results to show.
  • details: Indicates if recommended items should include details (True) or not (False).

You can test this endpoint with the mandatory fields using the below request body, if your proejct setup including training is completed:

{
  "user_id": "a0cc6beb-2909-459b-be55-62196af78ce4",
  "top_n_item": 100,
  "interval": "weekly",
  "flags": {},
  "start": 0,
  "size": 10,
  "details": true
}

2. users/search/recommend

This endpoint analyzes user search history and, based on that, returns recommended items to the user.

User cases: It can be integrated into the user feed, the top page, personalized suggestions, or as a widget, among other applications. Additionally, the response from this endpoint can be utilized to send users emails about products recommended based on their search history.

Request path:

POST /v1/users/search/recommend

You can test the endpoint in our sandbox here.

Example request body

{
  "user_id": "a0cc6beb-2909-459b-be55-62196af78ce4",
  "member_id": "df3456tg-2909-459b-be55-62196afedf85",
  "type": "individual",
  "search_size": 1000,
  "flags": {
    "flag1": true,
    "flag2": false
  },
  "start": 0,
  "size": 10,
  "language": "en",
  "is_keyword_enabled": true,
  "top_k": 20,
  "details": true
}

Let's go through each parameters:

  • user_id: Represents the ID of a logged-out unique user. Saved in the user's browser or app local storage.
  • member_id: Represents the ID of a logged-in unique user. Can be a phone number or email address to uniquely identify the user across devices.
  • type: Can select "individual" or "group". If you have parent_item_id in your catalog, you may want to group your search results and return one variant from the group. In this case, select group. Otherwise, select individual.
  • search_size: Determines the initial cluster of items considered as result candidates. Higher values yield more candidates but slower searches; lower values yield fewer candidates but faster searches. Does not impact search quality.
  • flags: Flags set in the mapper to include or exclude certain products, such as items on sale or out of stock. above we used two flags as example.
    • flag1: true to include items matching the flag.
    • flag2: false to exclude items matching the flag.
  • start: Index number of the first result to show.
  • size: Number of results to show.
  • language: Language preference for the results (e.g., en).
  • is_keyword_enabled: Indicates if keyword search is enabled (true) or not (false).
  • top_k: Set between 1-20. Higher values consider more items, potentially less relevant; lower values are stricter, considering fewer but more relevant items.
  • details: If you want to get recommended items with the items details, this parameter would be True; otherwise, it would be False.