Search products by keyword

Cost: 1 credit per product returned.

You can search for products by keyword using the GET /products/search?q={query} endpoint.

This endpoint uses PostgreSQL full-text search to find products matching your search query. Results are ranked by a composite score that combines:

Text Relevance (70%): How well the product title, brand, and model match your search query
Offer Count (25%): Products with more current offers are ranked higher (indicates active products)
Recency (5%): Recently updated products are slightly preferred

Query Parameters

Parameter	Required	Description
`q`	Yes	Search query or keyword (e.g., "iphone 15 pro", "samsung tv", "nike shoes")
`limit`	No	Maximum number of results to return (default: 20, max: 100)
`offset`	No	Offset for pagination (default: 0)

Example Request

curl -X GET "https://api.shopsavvy.com/v1/products/search?q=iphone%2015%20pro&limit=10" \
  -H "Authorization: Bearer ss_live_your_api_key_here"

Example Response

{
  "success": true,
  "data": [
    {
      "title": "Apple iPhone 15 Pro Max 256GB - Natural Titanium",
      "category": "Cell Phones & Accessories > Cell Phones > Smartphones",
      "brand": "Apple",
      "color": "Natural Titanium",
      "model": "iPhone 15 Pro Max",
      "shopsavvy": "products/abc123xyz",
      "barcode": 195949038674,
      "amazon": "B0CHX3TZ7R",
      "mpn": "MU773LL/A",
      "images": [
        "https://images-na.ssl-images-amazon.com/images/I/41BvSLn90ML.jpg",
        "https://images-na.ssl-images-amazon.com/images/I/51ckLKbsOsL.jpg"
      ]
    },
    {
      "title": "Apple iPhone 15 Pro 128GB - Blue Titanium",
      "category": "Cell Phones & Accessories > Cell Phones > Smartphones",
      "brand": "Apple",
      "color": "Blue Titanium",
      "model": "iPhone 15 Pro",
      "shopsavvy": "products/def456uvw",
      "barcode": 195949037894,
      "amazon": "B0CHX1W1XY",
      "mpn": "MTUX3LL/A",
      "images": [
        "https://images-na.ssl-images-amazon.com/images/I/41m9Pq3ScgL.jpg"
      ]
    }
  ],
  "pagination": {
    "total": 47,
    "limit": 10,
    "offset": 0,
    "returned": 2
  },
  "meta": {
    "credits_used": 2,
    "credits_remaining": 998,
    "rate_limit_remaining": 58
  }
}

Use Cases

Autocomplete / Search Suggestions: Use with a low limit (e.g., 5-10) to show real-time search results as users type
Category Browsing: Search for broad categories like "gaming laptops" or "bluetooth speakers"
Product Discovery: Find products when you don't have a specific identifier like a barcode or ASIN
Fuzzy Matching: The full-text search handles typos and variations in product names

Note: Once you have a product from search results, you can use its shopsavvy ID, barcode, or amazon ASIN with the other endpoints like GET /products/offers to retrieve pricing data.

Was this page helpful?