Skip to main content

Similar Item & User Ranking

Shaped's models understand your user, items and the relationships between them. You can use the Rank API to query this understanding and retrieve personalized item recommendations for specific user. You can also use the Rank API to retrieve similar users and items based on the understanding that Shaped learns.

Similar user and item queries are useful for use-cases like:

  • Similar product and content carousels, e.g. showing similar products to the one the user is currently viewing.
  • Similar user carousels, e.g. showing similar users that might be relevant to connect with or follow.

In this guide we'll show you how to use the similar endpoint to power some of these use-cases.

Similar Item​

For this guide let's assume you have created a model called video_recommendations e.g. the one from the Your First Model guide. And say we're aiming to build a 'What to watch next' carousel for a video streaming service. We may want to show the user a carousel of videos that are similar to the one they are currently watching.

Here's an example of how to make the similar item query for an item with id: item1 from the CLI:

Install
npm install @shaped.ai/client
const shapedai = require('@shaped.ai/client');

async function retrieveSimilarItems() {
  const client = shapedai.Client('your_api_key');
  const model_name = 'for_you_feed_v1';
  const user_id = '1';
  const item_id = 'item1';
  const limit = 5;
  const results = await client.similar_items({model_name, user_id, limit});
}

Example response:

{
   "ids":[
      "item427010",
      "item182094",
      "item332874",
      "item827918",
      "item403528"
   ],
}

The response contains the ids of the 5 most similar items to the one we queried (in ascending order). These are the items you would show in the carousel you're building.

Similar User​

Similar users works in the same way. For example, say we're building a 'People to follow' carousel for a social network to help improve social engagement. You would use the similar users endpoint to find the users that are most similar to the current user and display them in the carousel.

Here's an example of how to make the similar user query for a user with id: user1 from the CLI:

Install
npm install @shaped.ai/client
const shapedai = require('@shaped.ai/client');

async function retrieveSimilarUsers() {
  const client = shapedai.Client('your_api_key');
  const model_name = 'for_you_feed_v1';
  const user_id = '1';
  const limit = 5;
  const results = await client.similar_users({model_name, user_id, limit});
}
{
   "ids":[
      "user427010",
      "user182094",
      "user332874",
      "user827918",
      "user403528"
   ],
}

Again, the response contains the ids of the 5 most similar users to the one we queried (in ascending order). These are the users you would show in the carousel you're building.

REST API​

The CLI is useful to view the results of your queries, but you'll likely want to integrate the similar item and user queries into your own applications. You can do this with the REST API.

Here's an example for the similar items query:

curl https://api.prod.shaped.ai/v1/models/video_recommendations/similar-items \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json"
  -d '{
    "item_id": "your_item_id",
    "limit": 5,
  }'

Next steps​

Now that you've seen how to use the Rank API to retrieve similar users and items, you can use it to build your own similar entity use-cases.