Agent Native Compare Matrix

Get a detailed field-by-field comparison matrix for 2-50 products.

Base URL: https://api.buywhere.ai/v2/agents/compare-matrix

Overview

The Agent Native Compare Matrix endpoint provides a detailed comparison showing which fields are identical across products and which differ, along with price rankings and a structured diff of field values.

HTTP Method

POST /v2/agents/compare-matrix

Authentication

Requires API key in the Authorization header:

Authorization: Bearer bw_live_xxxxxxxxxxxxxxxx

Request Body

{
  "product_ids": [18472931, 18472932, 18472933],
  "include_fields": ["price", "rating", "review_count", "brand", "category"],
  "target_currency": "SGD"
}

Request Example

cURL

curl -X POST "https://api.buywhere.ai/v2/agents/compare-matrix" \
  -H "Authorization: Bearer bw_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": [18472931, 18472932, 18472933],
    "include_fields": ["price", "rating", "review_count"]
  }'

Python

import httpx

API_KEY = "bw_live_xxxxxxxxxxxxxxxx"
BASE_URL = "https://api.buywhere.ai"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = httpx.post(
    f"{BASE_URL}/v2/agents/compare-matrix",
    json={
        "product_ids": [18472931, 18472932, 18472933],
        "include_fields": ["price", "rating", "review_count"]
    },
    headers=headers
)
data = response.json()

print("=== Product Comparison ===\n")
for product in data['products']:
    print(f"{product['title']}")
    print(f"  Price: {product['currency']} {product['price']} (Rank: {product.get('price_rank', 'N/A')})")
    print(f"  Rating: {product['rating']}")
    print(f"  Source: {product['source']}")
    print()

print("=== Field Comparison ===")
for diff in data.get('field_diffs', []):
    print(f"\n{diff['field']}: {diff['values']}")
    print(f"  Identical: {diff['all_identical']}")

print(f"\n=== Summary ===")
print(f"Cheapest: {data.get('cheapest_product_id')}")
print(f"Most Expensive: {data.get('most_expensive_product_id')}")
print(f"Price Spread: {data.get('price_spread')}")

JavaScript (Node.js)

const API_KEY = "bw_live_xxxxxxxxxxxxxxxx";
const BASE_URL = "https://api.buywhere.ai";

const response = await fetch(
  `${BASE_URL}/v2/agents/compare-matrix`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      product_ids: [18472931, 18472932, 18472933],
      include_fields: ["price", "rating", "review_count"]
    })
  }
);

const data = await response.json();

console.log("=== Product Comparison ===\n");
data.products.forEach(product => {
  console.log(`${product.title}`);
  console.log(`  Price: ${product.currency} ${product.price} (Rank: ${product.price_rank || 'N/A'})`);
  console.log(`  Rating: ${product.rating}`);
  console.log(`  Source: ${product.source}`);
  console.log();
});

console.log("=== Field Comparison ===");
data.field_diffs?.forEach(diff => {
  console.log(`\n${diff.field}: ${diff.values.join(", ")}`);
  console.log(`  Identical: ${diff.all_identical}`);
});

console.log(`\n=== Summary ===`);
console.log(`Cheapest: ${data.cheapest_product_id}`);
console.log(`Most Expensive: ${data.most_expensive_product_id}`);
console.log(`Price Spread: ${data.price_spread}`);

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func compareMatrix(apiKey string, productIDs []int64) error {
    url := "https://api.buywhere.ai/v2/agents/compare-matrix"

    body := map[string]interface{}{
        "product_ids": productIDs,
        "include_fields": []string{"price", "rating", "review_count"},
    }
    jsonBody, _ := json.Marshal(body)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonBody))
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)

    products := result["products"].([]interface{})
    fmt.Println("=== Product Comparison ===\n")
    for _, p := range products {
        m := p.(map[string]interface{})
        fmt.Printf("%s\n", m["title"])
        fmt.Printf("  Price: %s %s\n", m["currency"], m["price"])
        fmt.Printf("  Rating: %.1f\n", m["rating"].(float64))
        fmt.Printf("  Source: %s\n", m["source"])
        fmt.Println()
    }

    if diffs, ok := result["field_diffs"].([]interface{}); ok {
        fmt.Println("=== Field Comparison ===")
        for _, d := range diffs {
            diff := d.(map[string]interface{})
            fmt.Printf("\n%s: %v\n", diff["field"], diff["values"])
            fmt.Printf("  Identical: %v\n", diff["all_identical"])
        }
    }

    fmt.Println("\n=== Summary ===")
    fmt.Printf("Cheapest: %.0f\n", result["cheapest_product_id"].(float64))
    fmt.Printf("Price Spread: %s\n", result["price_spread"])
    return nil
}

Response

Success Response (200 OK)

{
  "products": [
    {
      "id": 18472931,
      "title": "ASUS VivoBook 15 Laptop",
      "price": "1299.00",
      "price_rank": 2,
      "currency": "SGD",
      "rating": 4.5,
      "review_count": 892,
      "source": "shopee_sg"
    },
    {
      "id": 18472932,
      "title": "Lenovo ThinkPad E14",
      "price": "1399.00",
      "price_rank": 3,
      "currency": "SGD",
      "rating": 4.6,
      "review_count": 1245,
      "source": "lazada_sg"
    },
    {
      "id": 18472933,
      "title": "HP 15s-fq5000 Laptop",
      "price": "1199.00",
      "price_rank": 1,
      "currency": "SGD",
      "rating": 4.3,
      "review_count": 567,
      "source": "amazon_sg"
    }
  ],
  "field_diffs": [
    {
      "field": "price",
      "values": ["1299.00", "1399.00", "1199.00"],
      "all_identical": false
    },
    {
      "field": "rating",
      "values": [4.5, 4.6, 4.3],
      "all_identical": false
    },
    {
      "field": "review_count",
      "values": [892, 1245, 567],
      "all_identical": false
    }
  ],
  "identical_fields": ["brand", "category"],
  "cheapest_product_id": 18472933,
  "most_expensive_product_id": 18472932,
  "price_spread": "200.00",
  "price_spread_pct": 16.68
}

Response Fields

Product Fields

Field Diff Object

Error Responses

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

422 Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "errors": [
        {
          "field": "product_ids",
          "message": "Array must have between 2 and 50 items",
          "type": "length"
        }
      ]
    }
  }
}

---

Related Endpoints

• Agent Native Bulk Compare - Bulk product comparison
• Agent Native Price Comparison - Cross-platform price comparison
• Agent Native Search - Search for products