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.