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:

shaped complement_items --model-name product_recommendations --item-ids '["item8", "item901"]'

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.