Quickstart: Query Singapore Products in 5 Minutes

Get your first API response in under 5 minutes. This guide gets developers with no prior BuyWhere knowledge from zero to their first successful API call.

Prerequisites

• An API key from buywhere.ai/api-keys
• curl, Python 3.8+, or any HTTP client

Step 1: Get Your API Key

1. Sign up at buywhere.ai/api-keys
2. Create a new API key from your dashboard
3. Copy your key — it starts with bw_live_:

bw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 2: Install the SDK

JavaScript/TypeScript

npm install @buywhere/sdk

Python

pip install buywhere

Step 3: Make Your First Search

Search Singapore products using the SDK or raw HTTP.

Using JavaScript/TypeScript SDK

import { createClient } from '@buywhere/sdk';

const client = createClient('bw_live_xxxxx');

const results = await client.search.search({
  query: 'wireless headphones',
  country: 'SG',
  limit: 5
});

console.log(`Found ${results.total} products`);

for (const product of results.items) {
  console.log(`${product.name} - ${product.currency} ${product.price}`);
  console.log(`  Buy: ${product.buy_url}`);
}

Using Python SDK

from buywhere_sdk import BuyWhere

client = BuyWhere(api_key="bw_live_xxxxx")

# Search Singapore products
results = client.search(
    query="wireless headphones",
    country="SG",
    limit=5
)

for product in results.items:
    print(f"{product.name}")
    print(f"  Price: {product.currency} {product.price}")
    print(f"  Source: {product.source}")
    print(f"  Buy URL: {product.buy_url}")
    print()

Using curl

curl -X GET "https://api.buywhere.ai/v1/search?q=wireless+headphones&country=SG&limit=5" \
  -H "Authorization: Bearer bw_live_xxxxx" \
  -H "Accept: application/json"

Response:

{
  "total": 248,
  "limit": 5,
  "offset": 0,
  "has_more": true,
  "items": [
    {
      "id": 78234,
      "name": "Sony WH-1000XM5 Wireless Headphones",
      "price": 449.00,
      "currency": "SGD",
      "source": "shopee_sg",
      "buy_url": "https://shopee.sg/product/12345",
      "affiliate_url": "https://...",
      "is_available": true,
      "rating": 4.7,
      "image_url": "https://...jpg"
    }
  ]
}

Key response fields:

Step 4: Use in an AI Agent

The BuyWhere SDK and MCP tools let AI agents search products, get details, and find the best prices.

MCP Setup (Recommended for AI Agents)

Add BuyWhere to your MCP client configuration (Claude Desktop, Cursor, etc.):

For HTTP-based MCP clients:

{
  "mcpServers": {
    "buywhere": {
      "url": "https://api.buywhere.ai/mcp",
      "headers": {
        "Authorization": "Bearer bw_live_xxxxx"
      }
    }
  }
}

For stdio-based clients (Node.js):

npx -y @buywhere/mcp-tools

With config:

{
  "mcpServers": {
    "buywhere": {
      "command": "npx",
      "args": ["-y", "@buywhere/mcp-tools"],
      "env": {
        "BUYWHERE_API_KEY": "bw_live_xxxxx"
      }
    }
  }
}

Available MCP tools:

Python Agent Example

from buywhere_sdk import BuyWhere

client = BuyWhere(api_key="bw_live_xxxxx")

# Agent task: find cheapest PS5 in Singapore
results = client.search.search(query="PS5 console", country="SG", limit=10)

# Find lowest price
cheapest = min(results.items, key=lambda p: p.price)
print(f"Cheapest PS5: {cheapest.name}")
print(f"Price: {cheapest.currency} {cheapest.price}")
print(f"Source: {cheapest.source}")

Step 5: Find the Best Price

# Using SDK
comparison = client.compare.compareByCategory("electronics")
for product in comparison.products[:5]:
    print(f"{product.name}: {product.lowest_price}")

# Using curl
curl -X GET "https://api.buywhere.ai/v1/products/compare?q=nintendo%20switch%20oled" \
  -H "Authorization: Bearer bw_live_xxxxx"

Step 6: Compare Prices Across Platforms

# Compare specific products
comparison = client.compare.compareProducts([12345, 67890])

for product in comparison.products:
    print(f"{product.name}")
    for price in product.prices:
        print(f"  {price.merchant}: {price.currency} {price.price}")

curl -X GET "https://api.buywhere.ai/v1/products/compare?q=iphone%2015" \
  -H "Authorization: Bearer bw_live_xxxxx"

Step 7: Browse Categories

# Get category tree
categories = client.products.browseCategories()

for cat in categories[:10]:
    print(f"{cat.name}")

curl -X GET "https://api.buywhere.ai/v1/categories/tree" \
  -H "Authorization: Bearer bw_live_xxxxx"

Common Use Cases

Filter by Price Range

const results = await client.search.search({
  query: 'laptop',
  country: 'SG',
  price_min: 500,
  price_max: 2000
});

results = client.search(
    query="laptop",
    country="SG",
    price_min=500,
    price_max=2000
)

Search by Country

// Singapore (default)
const sgResults = await client.search.search({ query: 'laptop' });

// United States
const usResults = await client.search.search({ query: 'laptop', country: 'US' });

// Southeast Asia
const seaResults = await client.search.search({ query: 'laptop', region: 'sea' });

Get Deals with Discount Filter

const deals = await client.deals.getDeals({
  country: 'SG',
  min_discount_pct: 30,
  limit: 20
});

for (const deal of deals.deals) {
  console.log(`${deal.name}: ${deal.discount_pct}% off — ${deal.currency} ${deal.price}`);
}

Next Steps

• @buywhere/sdk — JavaScript/TypeScript SDK
• buywhere — Python SDK
• API Reference — Full endpoint documentation
• MCP Integration Guide — MCP setup for AI agents