/api/segment_subsegment_explore

Header

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

Request Body Schema

customers: array<object>  
  id: string  
  frequency: int  
  amount_spent: float  
  product_types: array<string>  
labels: object<customer_id: parent_cluster_id>  
target_cluster: int (optional)  
k_range: array<int> (optional, default = [2,3]) 

Example Request Body

{
  "customers":[
    { "id":"C001","frequency":28,"amount_spent":4120.75,"product_types":["laptop","mouse","keyboard","monitor"] },
    { "id":"C002","frequency":5, "amount_spent":190.40,  "product_types":["tea","coffee"] },
    …
  ],
  "labels":{
    "C001":2,"C002":0,"C003":0,"C004":0,"C005":0,"C006":0,"C007":1,…
  },
  "target_cluster":1,
  "k_range":[2,3]
}

Example Response Body

{
  "subsegment_results":{
    "1":{
      "benchmark":[
        {"k":2,"silhouette":0.4935,"davies_bouldin":0.5209},
        {"k":3,"silhouette":0.4140,"davies_bouldin":0.4869}
      ],
      "best_k":2,
      "selection_description":"Inside parent-cluster 1, k = 2 yielded the highest silhouette (0.493) and lowest Davies-Bouldin (0.521).",
      "nested_centroids":{
        "columns":["frequency","amount_spent","n_categories"],
        "values":[[21.5,2223.5,1.75],[25.33,3049.2,3.0]]
      },
      "nested_labels":{
        "C014":0,"C026":0,"C030":0,"C007":1,"C012":1,"C033":1
      },
      "nested_cluster_legend":[
        {"cluster_id":0,"n_customers":4,"avg_spend":2223.5,"avg_frequency":21.5,"top_categories":"fitness-watch, fridge"},
        {"cluster_id":1,"n_customers":3,"avg_spend":3049.2,"avg_frequency":25.33,"top_categories":"smart-tv, soundbar"}
      ],
      "nested_interpretations_en":{
        "0":"4 customers, avg spend 2 224, 21.5 purchases/mo. Top: fitness-watch, fridge.",
        "1":"3 customers, avg spend 3 049, 25.3 purchases/mo. Top: smart-tv, soundbar."
      }
    }
  }
}

Description

Performs a secondary K-Means sweep inside each parent cluster (or specified target_cluster), auto-selecting k by silhouette/Davies-Bouldin, and returns subcluster benchmarks, centroids, labels, legends, and English interpretations.

Business Usage

• Tiered loyalty perks • Hyper-personalized recommendations • “Segment-of-one” exploratory analysis

← Back to all routes