/api/recommend_similar_items

Header

X-Customer-Api-Id: <uuid>
X-Secret:          <secret>
Content-Type:      application/json

Request Body Schema

{
  "item_id":      "string",       // required: reference SKU
  "top_k":        integer,        // optional (1–100), default=10
  "items": [
    {
      "item_id":   "string",      // required: SKU candidate
      "metadata":  "string"       // optional: free-text attributes
    }
  ],
  "interactions":[               // optional: for CF; omit for content-only
    {
      "user_id":  "string",      // required
      "item_id":  "string",      // required
      "rating":   number         // optional, 0–5 (default implicit=1)
    }
  ],
  "blend_cf":     number         // optional 0–1, default=0.5
}

Example Request Body

{
  "item_id":"SKU-A1",
  "top_k":4,
  "items":[
    {"item_id":"SKU-A1","metadata":"Running shoes, Nike, men"},
    {"item_id":"SKU-B9","metadata":"Trail shoes, Adidas, women"},
    {"item_id":"SKU-C3","metadata":"Soccer ball, size 5"},
    {"item_id":"SKU-D7","metadata":"Compression socks, unisex"},
    {"item_id":"SKU-E2","metadata":"Fitness smartwatch"}
  ],
  "interactions":[
    {"user_id":"U-42","item_id":"SKU-A1"},
    {"user_id":"U-42","item_id":"SKU-B9"},
    {"user_id":"U-17","item_id":"SKU-A1"},
    {"user_id":"U-17","item_id":"SKU-D7"}
  ],
  "blend_cf":0.7
}

Example Response Body

{
  "recommendations":[
    {
      "item_id":"SKU-B9",
      "score":0.1783,
      "source":"content",
      "explanation":"Shares similar attributes/keywords with the reference item."
    },
    {
      "item_id":"SKU-C3",
      "score":0.0000,
      "source":"content",
      "explanation":"Shares similar attributes/keywords with the reference item."
    },
    {
      "item_id":"SKU-D7",
      "score":0.0000,
      "source":"content",
      "explanation":"Shares similar attributes/keywords with the reference item."
    },
    {
      "item_id":"SKU-E2",
      "score":0.0000,
      "source":"content",
      "explanation":"Shares similar attributes/keywords with the reference item."
    }
  ],
  "model_info":{
    "algorithm":"TF-IDF cosine",
    "metric":"cosine_sim",
    "value":1.0,
    "train_rows":5
  }
}

Description

Blend content-based TF-IDF similarity with collaborative-filtering co-view signals to return the top K catalogue SKUs most similar to a given reference item.

Business Usage

• PDP carousels (“You may also like”) → +6–12% add-to-cart • Out-of-stock redirects → recover 30–40% lost sessions • Bundle builders → +8–15% average order value • Category discovery → ↑ pages-per-session & SEO dwell time

← Back to all routes