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 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 (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 */ } ],
  "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 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.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.next_page_token // empty')
done

Response shape is lean — only product_id, stores[], and (when more sellers remain) 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. The walk is billed per upstream hop and capped at about 10 pages by default. If the cap is reached or a later page fails, the response keeps the sellers collected so far and includes a next_page_token for manual continuation plus the Scrape.do-Auto-Page-Truncated: true response header. If the walk fails before collecting any sellers, the endpoint returns HTTP 502 and the request is not charged.

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