Google Shopping Product API

The Google Shopping Product API is the companion endpoint to /plugin/google/shopping. It fetches the full product page for a single Google Shopping product — every seller offer, variants, specs, reviews, videos, and related discussions — as structured JSON.

The recommended flow is three steps: call /plugin/google/shopping to find a product, capture its catalog_id, hit this endpoint to get the product page with its first sellers, then replay the stores_next_page_token against /plugin/google/shopping/product/stores to walk the rest of the seller list.

Key Features

• Durable Catalog Input: Pass catalog_id + q to look up a product by its long-lived Google catalog identifier. Catalog IDs are stable per region, so you can save them in your own storage and replay them later.
• Rich Product Data: Title, gallery, brand, rating, ratings histogram, thumbnails, variants, specs, videos, customer review images, top insights, related discussions — all parsed into structured fields.
• Complete Seller List: Default page returns the headline ~5 sellers and a continuation token (stores_next_page_token). Replay it against /plugin/google/shopping/product/stores to walk every remaining seller. Pass load_all_stores=true to have the gateway walk the pagination for you in a single request.
• Per-seller Detail: Price, shipping, tax, total, payment methods, delivery / returns details, merchant ID, thumbnail, badge text, sale & strikethrough prices, and carrier-style monthly installment plans (installment_months, installment_down_now, total) when applicable.
• Three Response Modes: catalog_oapv (catalog mode, recommended), oapv (token mode, rich short-lived payload), and html (legacy product-id-only fallback). The chosen mode is echoed in product_results.source.
• Worldwide Coverage: Locale via gl + hl + location / uule; carrier financing and EU comma-decimal formatting handled automatically.
• Device Emulation: Desktop, mobile, or tablet layout with the device parameter.
• No Blocks or CAPTCHAs: All anti-bot measures are handled automatically by Scrape.do.

Endpoint

GET https://api.scrape.do/plugin/google/shopping/product

Request Parameters

Required

Identity (choose one)

Provide exactly one of the input combinations below. When you supply more than one, the priority is catalog_id > immersive_product_page_token > product_id.

Device

Routing

Sort

Seller list expansion

Localization

See Localization for the full list of supported hl, gl, and google_domain values.

Example Usage

By catalog_id (recommended — durable input)

# 1. Look up the product and grab its catalog_id
CID=$(curl -s "https://api.scrape.do/plugin/google/shopping?q=PodTrak+P8+ZP8&hl=en&gl=us&token=YOUR_TOKEN" \
  | jq -r '.shopping_results[0].catalog_id')

# 2. Fetch the product page + first sellers + continuation token
curl "https://api.scrape.do/plugin/google/shopping/product?catalog_id=$CID&q=PodTrak+P8+ZP8&hl=en&gl=us&token=YOUR_TOKEN"

Catalog mode in another market

# Same product, German market — re-search per region to get the region-scoped catalog_id
CID=$(curl -s "https://api.scrape.do/plugin/google/shopping?q=iPhone+17+Pro&hl=de&gl=de&token=YOUR_TOKEN" \
  | jq -r '.shopping_results[0].catalog_id')

curl "https://api.scrape.do/plugin/google/shopping/product?catalog_id=$CID&q=iPhone+17+Pro&hl=de&gl=de&token=YOUR_TOKEN"

Get every seller in one call

curl "https://api.scrape.do/plugin/google/shopping/product?catalog_id=$CID&q=PodTrak+P8+ZP8&load_all_stores=true&token=YOUR_TOKEN"

By immersive_product_page_token (rich short-lived response)

# 1. Mint a token from the search endpoint
TOKEN=$(curl -s "https://api.scrape.do/plugin/google/shopping?q=Sony+WH-1000XM5&token=YOUR_TOKEN" \
  | jq -r '.shopping_results[0].immersive_product_page_token')

# 2. Replay it against the product endpoint (variants/specs/reviews/videos returned)
curl "https://api.scrape.do/plugin/google/shopping/product?immersive_product_page_token=$TOKEN&token=YOUR_TOKEN"

By product_id (HTML fallback)

curl "https://api.scrape.do/plugin/google/shopping/product?product_id=7000474567848623813&token=YOUR_TOKEN"

Response

Top-Level Structure

{
  "search_parameters": { ... },
  "product_results":   { ... }
}

search_parameters

Echo of the request parameters sent by the client.

{
  "engine": "google_shopping_product",
  "product_id": "7000474567848623813",
  "page_token": "eyJlaSI6ImFhX1Nh...",
  "google_domain": "google.com",
  "hl": "en",
  "gl": "us",
  "device": "desktop",
  "more_stores": false,
  "next_page_token": ""
}

Optional fields appear only when sent: location, uule, sort_by.

product_results (rich path)

Returned when you pass immersive_product_page_token and do not pass sort_by. source is "oapv".

{
  "title": "Sony WH-1000XM5 Wireless Noise Canceling Headphones",
  "product_id": "7000474567848623813",
  "brand": "Sony",
  "rating": 4.6,
  "reviews": 4800,
  "reviews_label": "4,800 reviews",
  "ratings": [
    { "stars": 5, "count": 3400 },
    { "stars": 4, "count": 900 }
  ],
  "thumbnails": [ "https://encrypted-tbn0.gstatic.com/...", "..." ],
  "reviews_images": [ "https://encrypted-tbn0.gstatic.com/...", "..." ],
  "stores": [ { /* see stores[] table below */ } ],
  "stores_next_page_token": "eyJzb3JpIjo1LCJtbm8iOjEwfQ",
  "variants": [ { "type": "Color", "options": [ { "text": "Black", "selected": true } ] } ],
  "specs": [ { "section": "General", "items": [ { "label": "Wireless", "value": "Yes" } ] } ],
  "videos": [ { "title": "Sony WH-1000XM5 Review", "source": "youtube.com", "thumbnail": "...", "link": "..." } ],
  "user_reviews": [ { "rating": 5, "title": "Best headphones", "body": "...", "author": "John D." } ],
  "top_insights": [ { "section": "Sound quality", "items": [ "Crystal-clear audio", "Strong bass" ] } ],
  "about_the_product": { "description": "..." },
  "more_options": [ { "title": "Sony WH-1000XM4", "link": "...", "thumbnail": "..." } ],
  "discussions_and_forums": [ { "title": "...", "source": "reddit.com", "link": "...", "snippet": "..." } ],
  "extension_ids": { "catalog_id": "...", "gpc_id": "..." },
  "source": "oapv"
}

product_results (HTML fallback)

Returned when you pass only product_id, or when you pass sort_by alongside the token. source is "html". Lean shape — no variants, specs, videos, or reviews — but the seller list works.

{
  "title": "Sony WH-1000XM5 Wireless Noise Canceling Headphones",
  "product_id": "7000474567848623813",
  "stores": [ { /* see stores[] table below */ } ],
  "source": "html"
}

stores[] Fields

Each entry in product_results.stores[] describes a single merchant offer for the product.

Three Response Modes

The plugin picks the response mode automatically based on what you sent:

Inspect product_results.source to know which mode served the response. Catalog mode is the recommended default for any workflow that persists product identifiers.

Paginating every seller

Catalog mode returns up to ~5 sellers inline plus a stores_next_page_token when more remain. Use it in one of two ways:

Option 1 — Manual pagination via /plugin/google/shopping/product/stores

The dedicated continuation endpoint accepts the signed token and returns the next batch of sellers (up to ~10 per call). It's the most cost-efficient path because each call is a single hop when the embedded session is still fresh.

GET https://api.scrape.do/plugin/google/shopping/product/stores

# After the catalog call:
NEXT=$(echo "$RESP" | jq -r '.product_results.stores_next_page_token // empty')

while [ -n "$NEXT" ]; do
  RESP=$(curl -s "https://api.scrape.do/plugin/google/shopping/product/stores?catalog_id=$CID&next_page_token=$NEXT&token=YOUR_TOKEN")
  echo "$RESP" | jq '.product_results.stores | length'
  NEXT=$(echo "$RESP" | jq -r '.product_results.stores_next_page_token // empty')
done

Response shape is lean — only product_id, stores[], and (when more sellers remain) stores_next_page_token. Title, gallery, variants, etc. are not re-emitted; you already have them from the catalog call. source is "catalog_oapv_more".

The token is signed and bound to the supplied catalog_id. Sending a different catalog_id returns HTTP 400 ("catalog_id mismatch").

Option 2 — One-shot load_all_stores=true

For workflows that want every seller in a single response, pass load_all_stores=true on the catalog call. The gateway walks the continuation cursor for you and returns the merged seller list with no continuation token. Billed per upstream hop and capped (~10 pages by default); when the cap trips, you still get a stores_next_page_token for manual continuation plus the Scrape.do-Auto-Page-Truncated: true response header.

curl "https://api.scrape.do/plugin/google/shopping/product?catalog_id=$CID&q=iPhone+17+Pro&load_all_stores=true&token=YOUR_TOKEN"

Legacy more_stores on the token path

The legacy token flow (immersive_product_page_token) uses more_stores=true to inline the expanded seller list. New integrations should prefer the catalog path; more_stores stays available for existing callers.

Handling Session Expiry

immersive_product_page_token values are tied to an upstream Google session that ages out after several hours. When that happens, the plugin returns HTTP 410 Gone:

{
  "error": "session expired",
  "message": "The immersive_product_page_token is older than 6h0m0s and is past Google's product-viewer session lifetime. Fetch /plugin/google/shopping again to mint a fresh token, then retry."
}

(The exact lifetime message may vary; the recovery is always the same.)

See Transient Errors for the full rotate-on-expiry pattern.

Error Handling

All endpoints return errors in a consistent JSON format:

{
  "error": "error_code",
  "message": "Human readable error message"
}

Common Error Codes