Google Shopping via Scavio (v2)

Search Google Shopping for products, open a full product detail page, and page through every store selling it — all as structured JSON. Three endpoints, each 1 credit.

When to trigger

Use this skill when the user asks to:

• Find products across retailers with price or sale filters
• Compare prices for a product across many stores
• Get specs, ratings, variants, or seller options for a product
• Build a price-comparison or shopping-research workflow

Setup

Get a free API key at scavio.dev (50 free credits to get started, no card required):

export SCAVIO_API_KEY=sk_live_your_key

Endpoints

Authorization: Bearer $SCAVIO_API_KEY

Workflow

1. Search: call /shopping with a query. Filter with min_price, max_price, on_sale, free_shipping, or sort_by. Each result carries a catalog_id (durable) or product_id.
2. Product page: call /shopping/product with a catalog_id (pass the same query) for full specs, variants, and top stores in product_results.
3. All stores: if the product lists more sellers than returned, call /shopping/product/stores with the catalog_id and the next_page_token from the previous response to page through every store.

Shopping Search Parameters

Product Parameters

Product Stores Parameters

Example

import requests

BASE = "https://api.scavio.dev"
# Your key from https://scavio.dev. Load it from your environment or secret
# store in real code - keep it out of source control.
API_KEY = "sk_your_key_here"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Search products, cheapest first, under $1500
search = requests.post(f"{BASE}/api/v2/google/shopping", headers=HEADERS,
    json={"query": "16 inch laptop", "sort_by": 1, "max_price": 1500}).json()

item = search["shopping_results"][0]
print(item["title"], item.get("price"), item.get("source"))

# 2. Full product page (catalog_id needs the query alongside it)
product = requests.post(f"{BASE}/api/v2/google/shopping/product", headers=HEADERS,
    json={"catalog_id": item["catalog_id"], "query": "16 inch laptop"}).json()

# 3. Page through every store selling it
token = product["product_results"].get("stores_pagination", {}).get("next_page_token")
if token:
    stores = requests.post(f"{BASE}/api/v2/google/shopping/product/stores", headers=HEADERS,
        json={"catalog_id": item["catalog_id"], "next_page_token": token}).json()
    for s in stores["product_results"]["stores"]:
        print(s.get("name"), s.get("total_price"))

Responses

Search returns shopping_results[] (plus filters and pagination); product returns product_results; stores returns product_results.stores[]. Each also includes response_time, credits_used, credits_remaining, and cached.

{
  "shopping_results": [
    {
      "position": 1,
      "title": "Example 16\" Laptop",
      "price": "$1,299.00",
      "extracted_price": 1299,
      "source": "Example Store",
      "rating": 4.5,
      "reviews": 210,
      "catalog_id": "1234567890"
    }
  ],
  "response_time": 1420,
  "credits_used": 1,
  "credits_remaining": 997,
  "cached": false
}

Guardrails

• Each call costs 1 credit. Inform the user before paginating through many stores.
• Never fabricate product titles, prices, sellers, or ratings. Only return API data.
• The product call needs catalog_id + query together; the stores call needs catalog_id + next_page_token — always run /shopping first to obtain the catalog_id.
• Prices are strings as displayed; use extracted_price when present for numeric comparisons.

Failure handling

• 400 means an invalid parameter (e.g. catalog_id without query) — fix and retry.
• 401 means the API key is invalid or missing. Check SCAVIO_API_KEY.
• 429 means rate or usage limit exceeded. Wait before retrying. See https://scavio.dev/docs/rate-limits.
• 502 / 503 mean upstream is temporarily unavailable. Wait a few seconds before retrying.
• If search returns no results, loosen the price filters or broaden the query.
• If SCAVIO_API_KEY is not set, prompt the user to export it before continuing.