Scavio Google Shopping

Search Google Shopping for products, fetch a full product page, and page through every store selling a product — as structured JSON. Price, seller, rating, and price/sale filters. v2 engine, 1 credit per request.

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 https://scavio.dev (50 free credits to get started, no card required):

bash

export SCAVIO_API_KEY=sk_live_your_key

Endpoints

Endpoint	Credits	Description
POST https://api.scavio.dev/api/v2/google/shopping	1	Search products, returns shopping_results[]
POST https://api.scavio.dev/api/v2/google/shopping/product	1	Full product detail page
POST https://api.scavio.dev/api/v2/google/shopping/product/stores	1	Page through all stores selling a product

text

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

Parameter	Type	Default	Description
query	string	required	Search query (1-500 chars)
device	string	--	desktop or mobile
start	number	--	Result offset (follow pagination.next)
min_price	number	--	Minimum price filter
max_price	number	--	Maximum price filter
sort_by	number	0	0 relevance, 1 price ascending, 2 price descending
free_shipping	boolean	--	Only free-shipping offers
on_sale	boolean	--	Only on-sale offers
shoprs	string	--	Opaque filter token from filters[] / carousel_filters[]
hl	string	--	UI language
gl	string	--	Geo country
google_domain	string	google.com	Regional Google domain
location	string	--	Canonical location name (auto-UULE)
uule	string	--	Pre-encoded UULE

Product Parameters

Parameter	Type	Default	Description
catalog_id	string	--	Durable catalog id (pass with query)
query	string	--	Required when catalog_id is set
product_id	string	--	Product id alternative
immersive_product_page_token	string	--	Page token from a listing
page_token	string	--	Alias for immersive_product_page_token
device	string	--	desktop, mobile, or tablet
sort_by	string	--	Seller sort: base_price, total_price, promotion, seller_rating
load_all_stores	boolean	--	Load all stores inline
more_stores	boolean	--	Include additional stores
hl	string	--	UI language
gl	string	--	Geo country
google_domain	string	google.com	Regional Google domain
location	string	--	Canonical location name
uule	string	--	Pre-encoded UULE

Product Stores Parameters

Parameter	Type	Default	Description
catalog_id	string	required	Same catalog_id used on the product call
next_page_token	string	required	Continuation cursor from a prior response

Example

python

import os, requests

BASE = "https://api.scavio.dev"
HEADERS = {"Authorization": f"Bearer {os.environ['SCAVIO_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.

json

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