{
  "object": "doc",
  "title": "Search products: GET /api/v1/search",
  "description": "Cross-retailer product search with natural-language budgets, filters, sorting and pagination.",
  "section": "API reference",
  "url": "https://cart-route.com/docs/api/search",
  "updated": "2026-09-23",
  "prev": "https://cart-route.com/docs/sandbox",
  "next": "https://cart-route.com/docs/api/products",
  "text": "`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.\n\nGET https://cart-route.com/api/v1/search\n\nPOST https://cart-route.com/api/v1/search (same parameters as a JSON body)\n\n## Which parameters does search accept?\n\n| Name | Type | Default | Description |\n\n| `q` | string, ≤ 200 |  | What to find, in plain words. Required unless `category` or `brand` is set. |\n\n| `category` | string |  | Exact category name: Appliances, Audio, Computing, Fitness, Gaming, Home, Kitchen, Laptops, Office, Outdoor, Phones, TVs, Tools, Wearables. |\n\n| `brand` | string |  | Exact brand name, e.g. `Sony`. |\n\n| `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. |\n\n| `min_price` | number ≥ 0 |  | Minimum effective price in USD. Overrides a budget parsed from `q`. |\n\n| `max_price` | number ≥ 0 |  | Maximum effective price in USD. Overrides a budget parsed from `q`. |\n\n| `in_stock` | boolean | false | Drop out-of-stock and pre-order offers. |\n\n| `include_membership` | boolean | true | Include Costco and Sam's Club, which require a paid membership to buy. |\n\n| `sort` | enum | relevance | `relevance`, `price_asc`, `price_desc`, `savings` (widest retailer spread), `rating`. |\n\n| `limit` | integer 1–25 | 10 | Products per page. |\n\n| `cursor` | string |  | `next_cursor` from the previous page, unchanged. See [pagination](https://cart-route.com/docs/pagination). |\n\nHeaders: `Authorization` (required) and `Idempotency-Key` (optional, see [retries](https://cart-route.com/docs/idempotency)).\n\n## How is the query matched?\n\nKeywords 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.\n\n## What does a GET request look like?\n\n```\ncurl \"https://cart-route.com/api/v1/search?q=65+inch+oled+tv&in_stock=true&include_membership=false&sort=price_asc&limit=5\" \\\n  -H \"Authorization: Bearer $CARTROUTE_API_KEY\"\n```\n\n## What does a POST request look like?\n\n```\ncurl -X POST \"https://cart-route.com/api/v1/search\" \\\n  -H \"Authorization: Bearer $CARTROUTE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: 6c1f0e2a-quote-42\" \\\n  -d '{\"q\": \"cordless drill kit\", \"retailers\": [\"homedepot\", \"lowes\", \"amazon\"], \"max_price\": 350}'\n```\n\n## What does the response contain?\n\n| Field | Description |\n\n| `object` | Always `search_result`. |\n\n| `query`, `interpreted` | The input and how it was understood: keywords, parsed price bounds, filters. |\n\n| `total_results`, `returned` | Matching products overall, and in this page. |\n\n| `next_cursor` | Pass as `cursor` for the next page; `null` on the last page. |\n\n| `results[]` | Products; see [the product object](https://cart-route.com/docs/objects#product). Specs are omitted in search; fetch them with [get product](https://cart-route.com/docs/api/products). |\n\n| `notes` | Present when nothing matched, with suggestions. |\n\n| `credits` | `charged` and `remaining`. |\n\n```\n{\n  \"object\": \"search_result\",\n  \"api_version\": \"2026-09-01\",\n  \"data_source\": \"sandbox\",\n  \"request_id\": \"req_2m9x1q0a4b8c7f3k\",\n  \"query\": \"sony wh-1000xm6\",\n  \"interpreted\": {\n    \"keywords\": [\n      \"sony\",\n      \"wh-1000xm6\"\n    ],\n    \"min_price_usd\": null,\n    \"max_price_usd\": null,\n    \"retailers\": \"all\",\n    \"in_stock_only\": false,\n    \"include_membership_retailers\": true,\n    \"sort\": \"relevance\"\n  },\n  \"total_results\": 1,\n  \"returned\": 1,\n  \"next_cursor\": null,\n  \"results\": [\n    {\n      \"object\": \"product\",\n      \"id\": \"prd_0dophw3\",\n      \"slug\": \"sony-wh-1000xm6\",\n      \"title\": \"Sony WH-1000XM6 Wireless Noise Cancelling Headphones\",\n      \"brand\": \"Sony\",\n      \"category\": \"Audio\",\n      \"subcategory\": \"Headphones\",\n      \"identifiers\": {\n        \"gtin\": \"00027242928138\",\n        \"mpn\": \"WH1000XM6/B\",\n        \"model\": \"WH-1000XM6\"\n      },\n      \"rating\": 4.6,\n      \"review_count\": 6720,\n      \"released_on\": \"2026-05-15\",\n      \"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.\",\n      \"url\": \"https://cart-route.com/p/sony-wh-1000xm6\",\n      \"price_summary\": {\n        \"best_offer_id\": \"off_1piefxe\",\n        \"best_retailer\": \"Newegg\",\n        \"best_effective_price_usd\": 343.99,\n        \"lowest_price_usd\": 343.99,\n        \"highest_price_usd\": 454.99,\n        \"spread_usd\": 111,\n        \"offers_count\": 7,\n        \"in_stock_count\": 6,\n        \"coupons_count\": 4\n      },\n      \"price_insight\": {\n        \"verdict\": \"good_time_to_buy\",\n        \"reason\": \"Current lowest price is at or within 1% of the 90-day low of $342.99.\",\n        \"low_90d_usd\": 342.99,\n        \"high_90d_usd\": 431.99,\n        \"avg_30d_usd\": 372.72,\n        \"trend_30d_pct\": -3.4,\n        \"is_at_90d_low\": true,\n        \"observations\": 91\n      },\n      \"offers\": [\n        {\n          \"offer_id\": \"off_1piefxe\",\n          \"retailer\": {\n            \"id\": \"newegg\",\n            \"name\": \"Newegg\",\n            \"domain\": \"newegg.com\",\n            \"membership_required\": false,\n            \"returns_window_days\": 30\n          },\n          \"sku\": \"N82E16877620928\",\n          \"condition\": \"new\",\n          \"seller\": \"Newegg\",\n          \"price_usd\": 343.99,\n          \"list_price_usd\": 449.99,\n          \"discount_from_list_pct\": 23.6,\n          \"shipping_usd\": 0,\n          \"landed_price_usd\": 343.99,\n          \"best_coupon\": null,\n          \"effective_price_usd\": 343.99,\n          \"coupons\": [],\n          \"availability\": {\n            \"in_stock\": true,\n            \"stock_level\": \"in_stock\",\n            \"delivery_days_min\": 3,\n            \"delivery_days_max\": 6,\n            \"store_pickup\": false\n          },\n          \"retailer_url\": \"https://www.newegg.com/p/pl?d=Sony+WH-1000XM6\",\n          \"buy_url\": \"https://cart-route.com/go/off_1piefxe\",\n          \"last_checked_at\": \"2026-09-23T13:29:33.558Z\",\n          \"freshness_seconds\": 868\n        }\n      ]\n    }\n  ],\n  \"credits\": {\n    \"charged\": 1,\n    \"remaining\": 199\n  }\n}\n```\n\n## Which errors can search return?\n\n`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](https://cart-route.com/docs/errors)."
}