# BuyWhere — llms-full.txt

> Companion file to https://buywhere.ai/llms.txt for LLM crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, CCBot). Use this when you need the full endpoint table, category list, and quickstart code samples. The brief version is at `/llms.txt`; live catalog stats are at `/v1/catalog/stats`.

## What is BuyWhere

BuyWhere is an agent-native product catalog API for AI agents and LLM applications: more than 360M structured products from roughly 950K merchants worldwide, normalized into one schema, with location-aware ranking so agents only recommend products their user can actually receive.

- Coverage: more than 360M total products from roughly 950K merchants (live at GET /v1/catalog/stats; refreshed continuously — use the endpoint for exact counts)
- Location-aware search: `deliver_to=<ISO country>` ranks deliverable-first; each product carries an `availability` label.
- Compact mode: `compact=true` returns `structured_specs`, `comparison_attributes`, `normalized_price_usd`.
- Performance: P50 search latency <250ms; cached lookups <10ms; 99.9% uptime.
- 28,000+ stores with verified shipping policies.

## Quickstart

### 1. Register an API key

POST https://api.buywhere.ai/v1/auth/register — returns `api_key` (no auth required for registration).

### 2. Search with your user's location

```
curl -H "Authorization: Bearer $BUYWHERE_API_KEY" \
  "https://api.buywhere.ai/v1/products/search?q=coffee+maker&deliver_to=SG&limit=5"
```

Filter only deliverable products with `include_unshippable=false`.

### 3. Get a single product by id

```
curl -H "Authorization: Bearer $BUYWHERE_API_KEY" \
  "https://api.buywhere.ai/v1/products/54593494"
```

## REST API endpoint reference

### Products
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /v1/products/search | Full-text product search with filters (q, merchant, price_min, price_max, category, country, currency, availability, deliver_to, limit, offset, sort, compact, include_unshippable) |
| GET | /v1/products/{id} | Get a single product by numeric id (e.g. 54593494) |
| GET | /v1/products/compare | Compare two products side-by-side; pass `product_ids` or `url_a` + `url_b` |
| GET | /v1/products/similar | Find similar products given an id |
| GET | /v1/products/deals | Curated deals for a region/category |
| GET | /v1/products/price-history | Time-series price history for a product |
| POST | /v1/products/bulk | Bulk product lookup by id array |

### Catalog
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /v1/categories | List categories with product_count |
| GET | /v1/categories/{slug} | Single category detail |
| GET | /v1/merchants | List merchants with filters (country, source, is_active) |
| GET | /v1/merchants/{id_or_slug} | Single merchant detail |
| GET | /v1/catalog/stats | Aggregate catalog stats (product count, merchant count) |

### Auth
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /v1/auth/register | Register a new API key (no auth) |
| GET | /v1/auth/me | Inspect the calling API key (rate limit, plan) |

### Webhooks
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /v1/webhooks | Register a webhook subscription |
| GET | /v1/webhooks | List current webhooks |

## Categories (46 leaf slugs across 329 sitemap URLs)

Returned by GET /v1/categories. Each is served at `https://buywhere.ai/categories/{slug}` (where the route exists) and listed in `sitemap-categories.xml` (329 URLs include country variants US, SG, MY, TH, VN, ID, PH).

Top-level categories: home-living, fashion, food-beverages, electronics, sports-outdoors, automotive, pet-supplies, toys-games, health-wellness, beauty, grocery.

Sub-categories (electronics family): phones, appliances, computers, gaming, audio, tv-home-theater, smart-home, cameras-camcorders.

Full leaf slug list: appliances, audio, automotive, bathroom, beauty, beauty-health, beauty-personal-care, beer-wine-spirits, cameras-camcorders, car-care, cleaning, computers, dairy-chilled-eggs, drinks, electronics, fashion, food-beverages, food-cupboard, frozen, gaming, grocery, health-improvements, health-wellness, home-appliances, home-living, household, international-selections, lightings, phones, plus 16 more. Full list at GET /v1/categories and at `https://buywhere.ai/sitemap-categories.xml`.

## Supported countries

deliver_to accepts any ISO 3166-1 alpha-2 country code. Verified shipping policies and marketplace coverage include US, SG, GB, DE, FR, IT, ES, NL, AU, NZ, JP, KR, IN, ID, MY, TH, VN, PH, HK, TW, BR, MX, CA, AE, SA, IL, ZA, PL and more; use `deliver_to` for country-specific availability.

## Supported currencies

Prices return native currency + `normalized_price_usd`. Supported: USD, SGD, GBP, EUR, AUD, NZD, JPY, KRW, INR, IDR, MYR, THB, VND, PHP, HKD, TWD, BRL, MXN, CAD, AED, SAR, ILS, ZAR, PLN.

## Quickstart — Python

```python
import os, requests
API = "https://api.buywhere.ai"
key = os.environ["BUYWHERE_API_KEY"]
r = requests.get(f"{API}/v1/products/search",
    headers={"Authorization": f"Bearer {key}"},
    params={"q":"coffee maker","deliver_to":"SG","limit":5,"include_unshippable":False})
products = r.json()["data"]
for p in products:
    print(p["title"], p["price"], p["availability"])
```

## Quickstart — JavaScript

```javascript
const API = "https://api.buywhere.ai";
const key = process.env.BUYWHERE_API_KEY;
const r = await fetch(`${API}/v1/products/search?q=coffee+maker&deliver_to=SG&limit=5&include_unshippable=false`, {
  headers: { Authorization: `Bearer ${key}` }
});
const { data } = await r.json();
data.forEach(p => console.log(p.title, p.price, p.availability));
```

## MCP server

The BuyWhere MCP server is available at the canonical HTTP endpoint `https://api.buywhere.ai/mcp` and exposes the same surface as the REST API. The legacy SSE endpoint remains available at `https://api.buywhere.ai/mcp/sse` for clients that explicitly require SSE transport. Install instructions:

- Claude Desktop / Claude Code: add `buywhere` to `mcp_servers` with `command: "buywhere-mcp"` (CLI) or the transport-specific endpoint above.
- LangChain: `pip install langchain-buywhere` (community package; pending).
- LlamaIndex: `pip install llama-index-tools-buywhere` (pending).

## Agent skill (Anthropic)

A BuyWhere Claude skill is published; install via `claude skill install buywhere` once available, or copy `https://buywhere.ai/.well-known/agent.json` into your skills directory.

## Schema highlights

Every product returns:

- `id` — numeric id
- `title` — string
- `price` — `{amount, currency}`
- `normalized_price_usd` — USD-normalized price
- `merchant` — merchant slug
- `url` — original merchant URL
- `image_url` — primary image
- `region`, `country_code` — discoverability region
- `availability` — `local | ships_to_you | unavailable | unknown`
- `metadata` — `{rating, review_count, original_price, is_sponsored, keyword, ...}`
- `click_url`, `affiliate_redirect_url` — outlinks with tracking (where applicable)

## Rate limits

Free tier: 1,000 requests/day, 60/minute. Authenticated paid plans scale per the rate-limit headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`).

## Contact

Support: support@buywhere.ai · Docs: https://buywhere.ai/docs · API reference: https://buywhere.ai/api-reference · Blog: https://buywhere.ai/blog