BuyWhere US Developer Quickstart

Query 5M+ products from US retailers in under 5 minutes.

Base URL: https://api.buywhere.ai

---

1. Get Your API Key

Sign up and get your API key instantly:

curl -X POST https://api.buywhere.ai/v1/developers/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "agent@yourcompany.com", "name": "Your Agent"}'

Response:

{
  "raw_key": "bw_live_xxxxxxxxxxxxxxxxxxxx",
  "tier": "basic",
  "message": "Store this key securely — it will not be shown again."
}

Store raw_key securely — it will not be displayed again.

---

2. Your First US Search (cURL)

curl "https://api.buywhere.ai/v1/search?q=wireless+headphones&country=US&limit=5" \
  -H "Authorization: Bearer bw_live_xxxxxxxxxxxxxxxxxxxx"

Response:

{
  "total": 2847,
  "items": [
    {
      "id": 67890,
      "name": "Sony WH-1000XM5 Wireless Noise Cancelling Headphones",
      "price": "348.00",
      "currency": "USD",
      "source": "amazon_us",
      "rating": 4.7,
      "review_count": 15234,
      "buy_url": "https://amazon.com/dp/B09XS7JWHH",
      "affiliate_url": "https://buywhere.ai/click/abc123"
    }
  ]
}

---

3. Your First US Search (Python)

pip install buywhere-sdk

from buywhere_sdk import createClient

client = createClient("bw_live_xxxxxxxxxxxxxxxxxxxx")
results = client.search.search("wireless headphones", country="US", limit=5)

for p in results["items"]:
    print(f"{p['name']}: ${p['price']} on {p['source']}")

---

4. Your First US Search (TypeScript)

npm install buywhere-sdk

import { createClient } from 'buywhere-sdk';

const client = createClient('bw_live_xxxxxxxxxxxxxxxxxxxx');

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

results.items.forEach(p => {
  console.log(`${p.name}: $${p.price} on ${p.source}`);
});

---

5. Compare US Retailers

results = client.search.search("apple airpods pro 2nd generation", country="US", limit=10)
product_ids = [p["id"] for p in results["items"][:5]]

comparison = client.compare.compareProducts(product_ids)

for c in comparison["comparisons"]:
    best = c.get("best_price")
    if best:
        print(f"{c['product_name']}: ${best['price']} on {best['source']}")

---

6. US Price Range Search

curl "https://api.buywhere.ai/v1/search?q=laptop&country=US&price_min=300&price_max=800&limit=10" \
  -H "Authorization: Bearer bw_live_xxxxxxxxxxxxxxxxxxxx"

---

7. US Retailer Filter

Filter by specific US retailers:

curl "https://api.buywhere.ai/v1/search?q=tv&country=US&platform=walmart_us&limit=5" \
  -H "Authorization: Bearer bw_live_xxxxxxxxxxxxxxxxxxxx"

Available US platforms: amazon_us, walmart_us, target_us, bestbuy_us, newegg_us

---

Next Steps

• API Reference — Full endpoint documentation
• SDK Reference — TypeScript SDK docs
• MCP Tools — MCP server docs
• Supported Countries: SG, MY, TH, PH, VN, ID, US
• Supported Regions: sea (Southeast Asia), us (United States)

---

Code Examples

Affiliate Link Generation (US)

results = client.search.search("samsung 65 inch tv", country="US", limit=3)
top = min(results["items"], key=lambda p: float(p["price"]))

recommendation = {
    "product": top["name"],
    "price": f"{top['currency']} {top['price']}",
    "buy_link": top.get("affiliate_url", top.get("buy_url")),
    "merchant": top["source"]
}

Error Handling

import { BuyWhereError } from 'buywhere-sdk';

try {
  const results = await client.search.search('laptop', { country: 'US' });
} catch (error) {
  if (error instanceof BuyWhereError) {
    console.log(`API Error: ${error.message}`);
    console.log(`Status Code: ${error.statusCode}`);
  }
}

US Category Browse

curl "https://api.buywhere.ai/v1/categories?platform=amazon_us&limit=20" \
  -H "Authorization: Bearer bw_live_xxxxxxxxxxxxxxxxxxxx"

---

Rate Limits

---

Questions? Email api@buywhere.ai