CartrouteSearch products: GET /api/v1/search
GET /api/v1/search finds products across all 12 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, Outdoor, Phones, TVs, Tools, Wearables. | |
brand | string | Exact brand name, e.g. Sony. | |
retailers | csv (GET) or array (POST) | all | Retailer ids: amazon, bhphoto, bestbuy, costco, lowes, microcenter, newegg, samsclub, staples, target, homedepot, walmart. 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. | |
in_stock | boolean | false | Drop out-of-stock and pre-order offers. |
include_membership | boolean | true | Include Costco and Sam's Club, which 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&in_stock=true&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": ["homedepot", "lowes", "amazon"], "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": "sandbox",
"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": "00027242928138",
"mpn": "WH1000XM6/B",
"model": "WH-1000XM6"
},
"rating": 4.6,
"review_count": 6720,
"released_on": "2026-05-15",
"summary": "The XM6 restores the folding hinge the XM5 dropped and adds a 12-microphone array. Street price settles roughly 15% below MSRP within four months of launch, and Costco bundles a hard case at the same price point.",
"url": "https://cart-route.com/p/sony-wh-1000xm6",
"price_summary": {
"best_offer_id": "off_1piefxe",
"best_retailer": "Newegg",
"best_effective_price_usd": 343.99,
"lowest_price_usd": 343.99,
"highest_price_usd": 454.99,
"spread_usd": 111,
"offers_count": 7,
"in_stock_count": 6,
"coupons_count": 4
},
"price_insight": {
"verdict": "good_time_to_buy",
"reason": "Current lowest price is at or within 1% of the 90-day low of $342.99.",
"low_90d_usd": 342.99,
"high_90d_usd": 431.99,
"avg_30d_usd": 372.72,
"trend_30d_pct": -3.4,
"is_at_90d_low": true,
"observations": 91
},
"offers": [
{
"offer_id": "off_1piefxe",
"retailer": {
"id": "newegg",
"name": "Newegg",
"domain": "newegg.com",
"membership_required": false,
"returns_window_days": 30
},
"sku": "N82E16877620928",
"condition": "new",
"seller": "Newegg",
"price_usd": 343.99,
"list_price_usd": 449.99,
"discount_from_list_pct": 23.6,
"shipping_usd": 0,
"landed_price_usd": 343.99,
"best_coupon": null,
"effective_price_usd": 343.99,
"coupons": [],
"availability": {
"in_stock": true,
"stock_level": "in_stock",
"delivery_days_min": 3,
"delivery_days_max": 6,
"store_pickup": false
},
"retailer_url": "https://www.newegg.com/p/pl?d=Sony+WH-1000XM6",
"buy_url": "https://cart-route.com/go/off_1piefxe",
"last_checked_at": "2026-09-23T12:32:01.025Z",
"freshness_seconds": 994
}
]
}
],
"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.