Skip to main content

Complement Item Ranking

Several ranking use-cases involve finding the complement of a set of items. For example, an E-Commerce site may want to return products that would complement the current products within a user's cart. Or a music streaming service may want to return songs that would complement the current playlist the user is listening too.

To help with these use-cases, Shaped provides a complement items endpoint. This endpoint, accepts one or many item ids and returns items that complement the input items. Complement is fairly loosly defined to accomodate several use-cases, but you can think of complements as items that are typically interacted (e.g. purchases, listened) with together.

Using the CLI​

Here's an example using the CLI to make a complement items request to a product recommendation model:

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

async function retrieveComplementItems() {
  const client = shapedai.Client('your_api_key');
  const model_name = 'for_you_feed_v1';
  const item_ids = ['item1', 'item2'];
  const limit = 5;
  const results = await client.complement_items({model_name, item_ids, limit});
  console.log(results);
}

Example response:

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

The response contains the ids of the 5 most complementary items to the given item ids (item8 and item901).

Using the REST API​

Here's an example showing how to make the same request using the REST API:

curl https://api.shaped.ai/v1/models/video_recommendations/complement_items \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json"
  -d '{
    "item_ids": ["item8", "item901"],
    "limit": 5,
  }'

Next steps​

Now that you've seen how to use the Rank API to retrieve complementary items, you can use it to build your own "Complete-the-bag" and "Complete-the-playlist" use-cases.