/api/recommend_user_items

Header

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

Request Body Schema

{
  "user_id":      "string",       // required
  "top_k":        integer,        // optional, default=10
  "interactions": [               // ≥3 rows required
    {
      "user_id":  "string",       // required
      "item_id":  "string",       // required
      "rating":   number          // optional, 0–5
    }
  ],
  "items": [
    {
      "item_id":   "string",       // required
      "metadata":  "string"        // optional free-text
    }
  ]
}

Example Request Body

{
  "user_id":"U-42",
  "top_k":5,
  "interactions":[
    {"user_id":"U-42","item_id":"SKU-A1","rating":5},
    {"user_id":"U-42","item_id":"SKU-B9"},
    {"user_id":"U-17","item_id":"SKU-C3","rating":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"}
  ]
}

Example Response Body

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

Description

Generate a ranked list of items most likely to interest a user by combining collaborative filtering (ALS) when data is dense, or content-based TF-IDF fallback for sparse/cold-start scenarios.

Business Usage

• PDP Widgets: “You may also like” recommendations on product pages (+9% add-to-cart) • Post-purchase Emails: Top 5 unseen SKUs in follow-up mail (+18% repeat orders) • App Push: Daily single-SKU suggestion per active user (+7% DAU retention) • In-store Kiosks: Live personalized recs after loyalty card scan (+5% basket size)

← Back to all routes