# Search products by keyword

> GET /v1/products/search finds products by keyword with pagination, returning identifiers you can pass to the offers and history endpoints.

*Source: https://shopsavvy.com/data/documentation/product-search* · Part of the [ShopSavvy Data API documentation](https://shopsavvy.com/data/documentation.md)

---

**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

```bash
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

```json
{
  "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.