bulk-compare

Agent Native Bulk Compare

Compare multiple products by ID with full cross-platform analysis and recommendations.

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

Overview

The Agent Native Bulk Compare endpoint compares multiple products (up to 50) by their BuyWhere IDs and returns a comprehensive comparison with cross-platform analysis, best price identification, and AI-generated recommendations.

HTTP Method

POST /v2/agents/bulk-compare

Authentication

Requires API key in the Authorization header:

Authorization: Bearer bw_live_xxxxxxxxxxxxxxxx

Request Body

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

Field	Type	Required	Default	Description
`product_ids`	array[integer]	Yes	-	Array of BuyWhere product IDs (max 50)
`target_currency`	string	No	SGD	Convert prices to specified currency
`include_fields`	array[string]	No	all	Fields to include in comparison

Request Example

cURL

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

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/bulk-compare",
    json={
        "product_ids": [18472931, 18472932, 18472933],
        "target_currency": "SGD"
    },
    headers=headers
)
data = response.json()

print(f"Compared {data['total_products']} products")
for result in data['results']:
    print(f"\n{result['title']}")
    print(f"  Price: {result['currency']} {result['price']}")
    print(f"  Rating: {result['rating']}")
    print(f"  Source: {result['source']}")

JavaScript (Node.js)

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

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

const data = await response.json();

console.log(`Compared ${data.total_products} products`);
data.results.forEach(result => {
  console.log(`\n${result.title}`);
  console.log(`  Price: ${result.currency} ${result.price}`);
  console.log(`  Rating: ${result.rating}`);
  console.log(`  Source: ${result.source}`);
});

Go

package main

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

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

    body := map[string]interface{}{
        "product_ids":      productIDs,
        "target_currency": "SGD",
    }
    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)

    total := int(result["total_products"].(float64))
    fmt.Printf("Compared %d products\n", total)

    results := result["results"].([]interface{})
    for _, r := range results {
        m := r.(map[string]interface{})
        fmt.Printf("\n%s\n", m["title"])
        fmt.Printf("  Price: %s %s\n", m["currency"], m["price"])
        fmt.Printf("  Rating: %.1f\n", m["rating"].(float64))
    }
    return nil
}

Response

Success Response (200 OK)

{
  "results": [
    {
      "id": 18472931,
      "sku": "ASUS-VIVOBOOK-15",
      "source": "shopee_sg",
      "title": "ASUS VivoBook 15 Laptop",
      "price": "1299.00",
      "currency": "SGD",
      "price_sgd": "1299.00",
      "url": "https://shopee.sg/product/18472931",
      "brand": "ASUS",
      "category": "Computers & Laptops",
      "image_url": "https://cf.shopee.sg/file/xxxxx.jpg",
      "rating": 4.5,
      "review_count": 892,
      "is_available": true,
      "in_stock": true,
      "stock_level": "in_stock",
      "confidence_score": 0.92,
      "availability_prediction": "in_stock",
      "competitor_count": 12,
      "buybox_price": "1249.00",
      "affiliate_url": "https://buywhere.ai/track/abc123",
      "data_freshness": "2026-04-15T10:00:00Z"
    },
    {
      "id": 18472932,
      "sku": "LENOVO-THINKPAD-E14",
      "source": "lazada_sg",
      "title": "Lenovo ThinkPad E14 Business Laptop",
      "price": "1399.00",
      "currency": "SGD",
      "price_sgd": "1399.00",
      "url": "https://www.lazada.sg/product/18472932",
      "brand": "Lenovo",
      "category": "Computers & Laptops",
      "image_url": "https://static-sg.lazada.com/xxxxx.jpg",
      "rating": 4.6,
      "review_count": 1245,
      "is_available": true,
      "in_stock": true,
      "stock_level": "in_stock",
      "confidence_score": 0.94,
      "availability_prediction": "in_stock",
      "competitor_count": 8,
      "buybox_price": "1249.00",
      "affiliate_url": "https://buywhere.ai/track/def456"
    },
    {
      "id": 18472933,
      "sku": "HP-15S-FQ5000",
      "source": "amazon_sg",
      "title": "HP 15s-fq5000 Laptop",
      "price": "1199.00",
      "currency": "SGD",
      "price_sgd": "1199.00",
      "url": "https://amazon.sg/product/18472933",
      "brand": "HP",
      "category": "Computers & Laptops",
      "image_url": "https://images-na.amazon.sg/xxxxx.jpg",
      "rating": 4.3,
      "review_count": 567,
      "is_available": true,
      "in_stock": true,
      "stock_level": "low_stock",
      "confidence_score": 0.88,
      "availability_prediction": "low_stock",
      "competitor_count": 6,
      "buybox_price": "1199.00",
      "affiliate_url": "https://buywhere.ai/track/ghi789"
    }
  ],
  "total_products": 3,
  "comparison_summary": {
    "cheapest_product": {
      "id": 18472933,
      "title": "HP 15s-fq5000 Laptop",
      "price": "1199.00",
      "source": "amazon_sg"
    },
    "best_rated_product": {
      "id": 18472932,
      "title": "Lenovo ThinkPad E14 Business Laptop",
      "rating": 4.6,
      "source": "lazada_sg"
    },
    "best_value_product": {
      "id": 18472931,
      "title": "ASUS VivoBook 15 Laptop",
      "value_score": 0.91,
      "reason": "Best price-to-specs ratio"
    }
  }
}

Response Fields

Field	Type	Description
`results`	array	Array of compared products
`total_products`	integer	Number of products compared
`comparison_summary`	object	AI-generated summary with recommendations

Comparison Summary Fields

Field	Type	Description
`cheapest_product`	object	Lowest priced product
`best_rated_product`	object	Highest rated product
`best_value_product`	object	Best value recommendation

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 not exceed 50 items",
          "type": "max_length"
        }
      ]
    }
  }
}

Related Endpoints

Agent Native Search - Search for products
Agent Native Compare Matrix - Detailed field comparison
Agent Native Price Comparison - Cross-platform price comparison