ai-agent-getting-started

BuyWhere API Getting Started Guide for AI Agent Developers

Learn how to integrate BuyWhere's agent-native product catalog API into your AI agents in under 5 minutes.

What is BuyWhere?

BuyWhere provides a unified product catalog API that aggregates product data from major Singapore e-commerce platforms (Shopee SG, Lazada SG, Carousell SG, Qoo10 SG, Amazon SG) into a single, queryable interface optimized for AI agent consumption.

Why BuyWhere for AI Agents?

Agent-Native Design: Responses optimized for LLM consumption with minimal token overhead
Rich Product Data: 500K+ products with pricing, availability, and metadata
Real-Time Updates: Data refreshed continuously from scraping pipelines
Structured Output: Consistent JSON schema for reliable parsing
Built for Commerce: Price comparison, affiliate links, and purchase intent signals

Quick Start: Your First API Call

1. Get Your API Key

Contact the BuyWhere team to provision an API key. You'll receive a key in the format bw_live_xxxxx.

2. Search for Products

Make your first authenticated request to search for products:

curl "https://api.buywhere.ai/v2/products?q=wireless%20headphones&limit=3" \
  -H "Authorization: Bearer bw_live_xxxxx"

3. Understanding the Response

The v2 API includes agent-native enhancements:

{
  "total": 248,
  "limit": 3,
  "offset": 0,
  "items": [
    {
      "id": 78234,
      "sku": "SHOPEE-SG-HEP-001",
      "source": "shopee_sg",
      "name": "Sony WH-1000XM5 Wireless Headphones",
      "price": "449.00",
      "currency": "SGD",
      "price_sgd": 449.00,
      "buy_url": "https://shopee.sg/product/12345",
      "affiliate_url": "https://api.buywhere.ai/v1/track/abc123",
      "image_url": "https://cdn.buywhere.ai/img/12345.jpg",
      "brand": "Sony",
      "category": "Electronics",
      "category_path": ["Electronics", "Audio", "Headphones"],
      "rating": 4.7,
      "review_count": 1284,
      "is_available": true,
      "in_stock": true,
      "stock_level": "plenty",
      // Agent-native enhancements
      "confidence_score": 0.95,
      "availability_prediction": "high",
      "competitor_count": 12,
      "price_trend": "stable"
    }
  ],
  "has_more": true
}

Key Endpoints for AI Agents

Product Search (`GET /v2/products`)

Primary endpoint for discovering products with full-text search and filtering.

Parameters:

q: Search query (required for text search)
category: Filter by category
brand: Filter by brand
min_price/max_price: Price range filters
platform: Filter by source (shopee_sg, lazada_sg, etc.)
country: Filter by country code (SG, MY, etc.)
in_stock: Filter by availability
sort_by: Sort results (relevance, price_asc, price_desc, newest)
limit/offset: Pagination
currency: Target currency for price conversion

Product Details (`GET /v2/products/{product_id}`)

Get detailed information for a specific product.

Batch Product Details (`POST /v2/products/batch-details`)

Optimized for agents needing to check multiple products simultaneously (max 100 IDs).

Agent Exploration (`GET /v2/agents/explore`)

Get randomized product selection for discovery and market analysis.

Trending Products (`GET /v2/trending`)

Get currently popular products by view count.

Agent-Native Features Explained

Confidence Score (0.0-1.0)

Indicates the reliability of the product data based on freshness and source quality.

Availability Prediction

Predicts stock availability based on historical patterns: "high", "medium", "low".

Competitor Count

Number of merchants selling the same product (based on SKU matching).

Price Trend

Recent price movement: "up", "down", or "stable" (30-day window).

Integration Examples

Python Request Example

import requests

def search_buywhere(query, limit=10):
    url = "https://api.buywhere.ai/v2/products"
    headers = {"Authorization": "Bearer bw_live_xxxxx"}
    params = {
        "q": query,
        "limit": limit,
        "currency": "SGD"
    }
    
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    return response.json()

# Usage
results = search_buywhere("gaming laptop", limit=5)
for product in results['items']:
    print(f"{product['name']} - SGD {product['price']} "
          f"(confidence: {product['confidence_score']:.2f})")

Batch Processing for Decision Making

import requests

def get_batch_product_details(product_ids):
    url = "https://api.buywhere.ai/v2/products/batch-details"
    headers = {"Authorization": "Bearer bw_live_xxxxx"}
    data = {"product_ids": product_ids}
    
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    return response.json()

# Check multiple products for price comparison
product_ids = [12345, 67890, 11111]
batch_data = get_batch_product_details(product_ids)

print(f"Cache hit rate: {batch_data['cache_hit_rate']*100:.1f}%")
for product in batch_data['products']:
    if product:  # Skip not-found products (null entries)
        print(f"{product['name']}: SGD {product['price']}")

Best Practices for AI Agents

Use Batch Endpoints: For comparing multiple products, use /batch-details to minimize API calls
Leverage Confidence Scores: Filter results by confidence_score > 0.8 for high-reliability data
Monitor Price Trends: Use price_trend to identify products with decreasing prices (good deals)
Check Availability Prediction: Prioritize items with "high" availability prediction
Currency Conversion: Use the currency parameter for automatic price conversion to user's local currency
Rate Limit Handling: Respect X-RateLimit-Remaining headers; implement exponential backoff for 429 responses

Common Use Cases

Price Comparison Agent

def find_best_price(product_query):
    # Search for the product
    search_results = search_buywhere(product_query, limit=1)
    if not search_results['items']:
        return None
    
    product_id = search_results['items'][0]['id']
    
    # Get batch details for all variants (if available)
    # In practice, you'd need to get variant IDs from search or use compare endpoint
    return search_results['items'][0]

Deal Discovery Agent

def find_deals(max_price=100, min_discount=20):
    # Search for products in price range
    results = search_buywhere("", limit=50, max_price=max_price)
    
    deals = []
    for product in results['items']:
        # Would need historical data or compare endpoint to calculate discount
        # This is a simplified example
        if product.get('price_trend') == 'down' and product['confidence_score'] > 0.8:
            deals.append(product)
    
    return deals[:10]  # Return top 10 deals

Product Recommendation Agent

def recommend_products(category=None, budget=500):
    results = search_buywhere(
        "", 
        limit=20,
        category=category,
        max_price=budget,
        sort_by="rating"  # Prioritize highly rated products
    )
    
    # Filter for high confidence and good availability
    recommended = [
        p for p in results['items'] 
        if p['confidence_score'] > 0.85 
        and p['in_stock'] == True
        and p['review_count'] >= 10
    ]
    
    return sorted(recommended, key=lambda x: x['rating'], reverse=True)[:5]

Error Handling

The API uses standard HTTP status codes:

200: Success
400: Bad Request (invalid parameters)
401: Unauthorized (missing/invalid API key)
403: Forbidden (insufficient permissions)
404: Not Found
422: Unprocessable Entity (validation errors)
429: Rate Limit Exceeded
500: Internal Server Error

Always check the response status and handle errors appropriately in your agent logic.

Next Steps

Explore the Full API: Check out the API Reference for all available endpoints
Try the SDK: Look at language-specific SDKs in the /sdk directory for easier integration
Join the Community: Connect with other AI agent developers building on BuyWhere
Provide Feedback: Help us improve the API by sharing your integration experiences

Support

Ready to build your AI-powered shopping agent? Get your API key and start integrating today!