The Similar Products algorithm surfaces products that share descriptive characteristics with the product a shopper is currently viewing. It compares product name, category, and textual metadata, such as material_type, tags, gender, or any custom attribute you have defined. Up to 5 additional attributes can be included, configured from the Product Attributes page.
It performs optimally on product detail and cart pages where the written description carries most of the decision weight (electronics, books, grocery, health, cosmetics, accessories).
Endpoint
GET https://recommendation.api.useinsider.com/v2/similar
Visit our Postman collection to test this request.
Query Parameters
Parameter | Sample Value | Description | Data Type | Required |
|---|---|---|---|---|
partnerName | mybrand | Partner Identifier assigned by Insider One. You can use PartnerID as well. | String | Yes |
locale | us_US | Locale of requested product catalog | String | Yes |
productId | 1068 | The reference product for which the complement is computed | String | Yes |
currency | USD | Product currency. If no value is set, the default currency in your settings is used. | String | No |
size | 10 | Response items. Valid values are 0 to 100. | Integer | No |
categoryList | [“Clothes”] | Category filter of the products | Array | No |
userId | a1b2c3d4 | User identifier; enables personalization boosts when provided | String | No |
platform | web | Requested platform (default: web) | Enum | No |
details | true | Adds details to the products of the response | Boolean | No |
excludeVariants | true | Hides color/size variants of the same base product | Boolean | No |
shuffle | false | Shuffles the products of the response | Boolean | No |
filter | [in_stock][=][true] | Restricts results by fields such as price, brand, color, gender, in_stock, or category | String | No |
hp | true | Hyper-personalization flag. Re-ranks results using the shopper's attribute preferences | Boolean | No |
getGroupProducts | true | Returns all color/size variants grouped under each recommended product | Boolean | No |
groupProductsFields | product_attributes.color,price | Comma-separated list of fields to include in the grouped variants; products missing any listed field are dropped | String | No |
getAllGroupProductsFields | true | Returns all variant fields without dropping products for missing fields; automatically enables getGroupProducts | Boolean | No |
excludeViewDay | 30 | Days before excluding previously viewed products | Integer | No |
excludeViewItem | 100 | Number of viewed products to exclude | Integer | No |
excludePurchaseDay | 30 | Days before excluding previously purchased products | Integer | No |
excludePurchaseItem | 100 | Number of purchased products to exclude | Integer | No |
Sample Request
The sample below shows a request to Similar Products, the algorithm that suggests items frequently bought or viewed alongside the anchor product.
https://recommendation.api.useinsider.com/v2/similar?partnerName={PartnerName}&locale={Locale}&productId={ABC123}&size=3Sample Response
{
"success": true,
"total": 3,
"types": { "sim": 3 },
"data": [
"649517_49890",
"568334_49053",
"639714_49677"
]
}Fallback Algorithms
When not enough products can be matched by their textual fields (additional product attributes can be activated from Product Catalog Management > Product Attributes > Similarity, by default, name and category are used), the system falls back to:
Viewed Together
Most Popular Items in Category
Most Popular Items