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:


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 \
-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.