CartrouteSearch products: GET /api/v1/search
GET /api/v1/search finds products across all 3 retailers and returns, for each, every offer with landed price, best coupon, effective price, stock and a 90-day price verdict. Plain-language budgets in q ("under $400", "between 200 and 500", "over 1k") become price filters. Costs 1 credit.
GET https://cart-route.com/api/v1/search
POST https://cart-route.com/api/v1/search (same parameters as a JSON body)
Which parameters does search accept?
| Name | Type | Default | Description |
|---|---|---|---|
q | string, ≤ 200 | What to find, in plain words. Required unless category or brand is set. | |
category | string | Exact category name: Appliances, Audio, Computing, Fitness, Gaming, Home, Kitchen, Laptops, Office, Other, Outdoor, Phones, TVs, Tools, Wearables. | |
brand | string | Exact brand name, e.g. Sony. | |
retailers | csv (GET) or array (POST) | all | Retailer ids: amazon, bestbuy, ebay. Slugs are also accepted. |
min_price | number ≥ 0 | Minimum effective price in USD. Overrides a budget parsed from q. | |
max_price | number ≥ 0 | Maximum effective price in USD. Overrides a budget parsed from q. | |
condition | string | any | any, new, or used (renewed, refurbished, open box and used). Out-of-stock offers are never returned. |
include_membership | boolean | true | Include offers from retailers that require a paid membership to buy. |
sort | enum | relevance | relevance, price_asc, price_desc, savings (widest retailer spread), rating. |
limit | integer 1–25 | 10 | Products per page. |
cursor | string | next_cursor from the previous page, unchanged. See pagination. |
Headers: Authorization (required) and Idempotency-Key (optional, see retries).
How is the query matched?
Keywords are matched against identifiers (GTIN, MPN, model), brand, title, category and product keywords, with plurals and common synonyms handled ("tv" matches TVs, "ps5" matches PlayStation). A one- or two-word query must match every word; longer queries must match at least 60% of their words. Filler words such as "best", "cheap" and "deal" are ignored. The interpreted object in the response shows exactly how the query was understood.
What does a GET request look like?
curl "https://cart-route.com/api/v1/search?q=65+inch+oled+tv&condition=new&include_membership=false&sort=price_asc&limit=5" \ -H "Authorization: Bearer $CARTROUTE_API_KEY"
What does a POST request look like?
curl -X POST "https://cart-route.com/api/v1/search" \
-H "Authorization: Bearer $CARTROUTE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6c1f0e2a-quote-42" \
-d '{"q": "cordless drill kit", "retailers": ["amazon", "bestbuy"], "max_price": 350}'
What does the response contain?
| Field | Description |
|---|---|
object | Always search_result. |
query, interpreted | The input and how it was understood: keywords, parsed price bounds, filters. |
total_results, returned | Matching products overall, and in this page. |
next_cursor | Pass as cursor for the next page; null on the last page. |
results[] | Products; see the product object. Specs are omitted in search; fetch them with get product. |
notes | Present when nothing matched, with suggestions. |
credits | charged and remaining. |
{
"object": "search_result",
"api_version": "2026-09-01",
"data_source": "live",
"request_id": "req_2m9x1q0a4b8c7f3k",
"query": "sony wh-1000xm6",
"interpreted": {
"keywords": [
"sony",
"wh-1000xm6"
],
"min_price_usd": null,
"max_price_usd": null,
"retailers": "all",
"in_stock_only": false,
"include_membership_retailers": true,
"sort": "relevance"
},
"total_results": 1,
"returned": 1,
"next_cursor": null,
"results": [
{
"object": "product",
"id": "prd_0dophw3",
"slug": "sony-wh-1000xm6",
"title": "Sony WH-1000XM6 Wireless Noise Cancelling Headphones",
"brand": "Sony",
"category": "Audio",
"subcategory": "Headphones",
"identifiers": {
"gtin": null,
"mpn": null,
"model": "WH-1000XM6"
},
"rating": 4.2,
"review_count": 3975,
"rating_source": "Amazon",
"image_url": "https://pisces.bbystatic.com/image2/BestBuy_US/images/products/5c0ff147-1f18-4f75-adbc-680f9fee5308.jpg",
"released_on": null,
"summary": "Sony WH-1000XM6 Wireless Noise Cancelling Headphones. Cartroute checks Amazon, Best Buy and eBay for listings of this product every 24 hours and records each day's prices.",
"url": "https://cart-route.com/p/sony-wh-1000xm6",
"price_summary": {
"best_offer_id": "off_0f10sq01vb",
"best_retailer": "eBay",
"best_effective_price_usd": 291.26,
"lowest_price_usd": 199.99,
"highest_price_usd": 378,
"spread_usd": 178.01,
"offers_count": 31,
"in_stock_count": 31,
"best_condition": "new",
"offers_by_condition": {
"new": 20,
"used": 8,
"renewed": 3
},
"coupons_count": 0
},
"price_insight": {
"verdict": "typical_price",
"reason": "Current lowest price is within the normal 90-day range ($180.00–$259.99).",
"low_90d_usd": 180,
"high_90d_usd": 259.99,
"avg_30d_usd": 206.72,
"trend_30d_pct": -23.1,
"is_at_90d_low": false,
"observations": 45
},
"offers": [
{
"offer_id": "off_0f10sq01vb",
"retailer": {
"id": "ebay",
"name": "eBay",
"domain": "ebay.com",
"membership_required": false,
"returns_window_days": null
},
"sku": "377622630831",
"listing_title": "Sony WH-1000XM6 Noise Cancelling Wireless Headphones Black",
"condition": "new",
"seller": "bc2to7 (eBay seller)",
"price_usd": 280,
"list_price_usd": null,
"discount_from_list_pct": 0,
"shipping_usd": 11.26,
"shipping_stated": true,
"landed_price_usd": 291.26,
"best_coupon": null,
"effective_price_usd": 291.26,
"coupons": [],
"availability": {
"in_stock": true,
"stock_level": "in_stock",
"delivery_days_min": null,
"delivery_days_max": null,
"store_pickup": false
},
"retailer_url": "https://www.ebay.com/itm/377622630831",
"buy_url": "https://cart-route.com/go/off_0f10sq01vb",
"last_checked_at": "2026-11-06T18:42:04.433Z",
"freshness_seconds": 120958
}
]
}
],
"credits": {
"charged": 1,
"remaining": 199
}
}
Which errors can search return?
401 unauthorized, 402 insufficient_credits, 422 validation_error (the body names the param, e.g. an unknown retailer id or limit above 25) and 429 rate_limited. See errors.