How BuyWhere behaves when your agent needs product answers
BuyWhere turns shopping intent into ranked products, current prices, trusted merchants, availability, and purchase-ready options. This page documents when agents should call BuyWhere, how results are ranked, and what performance signals to expect.
Query to purchase
The flow your agent can rely on
BuyWhere is designed for product-resolution tasks, not generic web search. The API is optimized for structured shopping decisions that need explanation, comparison, and a direct next step.
Step 1
Query
Your agent sends a product intent such as 'best headphones under $100' or 'where can I buy an air fryer today?'.
Step 2
Resolve
BuyWhere converts that intent into ranked products, current prices, trusted merchants, availability, and direct purchase options.
Step 3
Rank
Results are scored using price competitiveness, match quality, merchant reliability, availability, and freshness.
Step 4
Present
Your agent receives structured options with buywhere_score and confidence so it can explain or select the best fit.
Step 5
Purchase
The user completes checkout on the merchant site. BuyWhere helps close the research loop, not process payment.
Ranking logic
How `best_value` works
Each result includes `buywhere_score` and `confidence` values on a `0.0-1.0` scale. The default ranking model balances value and reliability instead of promoting paid listings.
| Factor | Weight |
|---|---|
| Price competitiveness | 35% |
| Product match quality | 25% |
| Merchant reliability | 20% |
| Availability | 15% |
| Freshness | 5% |
Supported sorts
Merchant reliability model
Merchant reliability blends fulfillment rate (40%), return rate (30%), average rating (20%), and response time (10%).
Use `best_value` when your agent needs the strongest overall recommendation. Switch to `lowest_price` or `fastest_delivery` only when the user intent is explicit.
Behavior details
What BuyWhere returns and what it does not
Price comparison
Prices are normalized to SGD for Singapore queries, shipping is included when available, and comparison output can include lowest, highest, and median price points.
Availability
Status values include in_stock, low_stock, backorder, out_of_stock, and discontinued. Availability is checked at query time and can change quickly.
Merchant selection
Merchants are selected using data quality, reliability, coverage, and affiliate status rather than paid placement.
Important limitation
Availability is checked at query time, not continuously, and BuyWhere does not process checkout. Agents should link users to the merchant page for final stock, shipping, and payment confirmation.
Intent mapping
When your agent should call BuyWhere
| User says... | Call |
|---|---|
| recommend / best / what to buy | resolve_product_query |
| cheapest / best deal | find_best_price |
| A vs B / compare | compare_products |
| where to buy / purchase | get_purchase_options |
| product details | get_product_details |
| in stock / available | resolve_product_query with filter |
Tool selection
Which call fits which job
resolve_product_query
Open-ended product discovery
find_best_price
Price-focused deal finding
compare_products
A vs B decisions
get_product_details
Deep dive on a specific item
get_purchase_options
Ready-to-buy merchant selection
Region-aware search
How region and country parameters affect results
The BuyWhere API returns products ranked and filtered by geographic region. Adding explicit region parameters improves result relevance for your target market and ensures your agent handles launch availability correctly.
Live
Available nowSingapore
Full catalog with 850K+ products, self-serve API key, and production use supported. Default currency is SGD.
Example query
region=sg&country=SG¤cy=SGD
Preview
Not yet liveUnited States
US catalog is in preview. Do not use for production queries. Use illustrative examples with explicit "Preview" labels.
Example query
region=us&country=US¤cy=USD
Preview — US catalog launching soon
| Parameter | Values | Description |
|---|---|---|
| region | sg | us | sea | Geographic scope for ranking and filtering |
| country | SG | US | VN | TH | MY | ISO 3166-1 alpha-2 country code for availability filtering |
| currency | SGD | USD | VND | THB | MYR | Prices returned in this currency |
| region_boost | local | none | only | Control whether local products are boosted in ranking |
region_boost options
Use region_boost to control geographic ranking behavior:
local (default)
Boost local merchants in results; international products shown but deprioritized
none
Rank purely by score; no geographic preference applied
only
Show only products available in the specified region/country
Preview region behavior
US, Vietnam, Thailand, and Malaysia catalogs are in preview. Agents targeting these regions should display illustrative results labeled “Preview” and link to the waitlist or design partner signup rather than presenting results as live product data.
Machine-relevant metrics
Operational targets for agent builders
These targets help agents decide whether BuyWhere is appropriate for latency-sensitive shopping, comparison, and purchase-intent workflows.
Latency targets
- P50
- < 150ms
- P95
- < 350ms
- P99
- < 600ms
- Timeout
- 5s
Accuracy targets
- Intent classification
- > 95%
- Price accuracy
- > 99%
- Availability accuracy
- > 92%
Coverage
- Singapore products
- 850K+
- Categories
- 150+
- Merchants
- 60+
Freshness
- Prices
- Every 6h
- Availability
- Every 30m
- New products
- Daily
Next action
Use BuyWhere when your agent needs a buying answer, not another search result page
Start with the quickstart for your first request, then plug BuyWhere into MCP or your own API client once the behavior model fits your shopping workflow.