Shopping Search

POST

/api/v1/shopping

The shopping search endpoint retrieves real-time product listings, merchant names, item prices, ratings, product thumbnail images, and landing page buy links.

Returned Shopping Product Properties

Each entry in the shopping response array contains structured e-commerce metadata:

title: Full product name or listing title
price: Display price string including currency symbol (e.g. "$89.99")
link: Direct web link to the merchant product page
source: Name of the online merchant or store (e.g. "Keycap Universe")
rating: Average buyer review score (e.g. 4.8)
reviews: Count of customer product reviews
imageUrl: Direct image link for the product thumbnail
position: Search rank position (1-based)

{
  "q": "mechanical keyboard",
  "gl": "us",
  "num": 10
}

Authorizations

X-API-KEYstringheaderrequired

Passed via request headers. Your secret API key for SerperMatrix (e.g. sm_live_...).

Body

application/json

qstringrequired

Product model, category, or brand query (e.g. "mechanical keyboard").

glstring

Target country for product availability.

hlstring

Target host language.

numintegerdefault: 10

Number of shopping results to retrieve (min: 1, max: 100).

use_cachebooleandefault: true

Retrieve cached product listings if available.

Request

curl -X POST https://serpermatrix.com/api/v1/shopping \
  -H "X-API-KEY: sm_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"q":"mechanical keyboard","num":2}'

{
  "searchParameters": {
    "q": "mechanical keyboard",
    "num": 2,
    "type": "shopping"
  },
  "shopping": [
    {
      "title": "Custom Mechanical Keyboard - Purple Light v2",
      "source": "KeyboardCo",
      "link": "https://example.com/keyboard",
      "price": "$129.99",
      "position": 1
    }
  ]
}