Google Shopping tools

Product results, specifications, prices, stores, and reviews.

4 tools are implemented in this family. The definitions below come from the service’s actual tool catalog.

Authenticate, inspect the schema, then request an estimate using dry_run where supported. Research can spend workspace credits.

Search Google Shopping

shopping_search_products

Google Shopping results for a query in rank order, with store, price, previous price, rating, delivery and the ids the other shopping tools take: what Shopping shows for a query, which stores win, what rivals charge. Not for Amazon (amazon_search_products) or web results (seo_get_serp). Read live; can take up to a minute. Returns keyword and rows[]: rank (1 to N across returned rows), product_id, gid, data_docid, title, seller, price, old_price, currency, rating, ratings_count, tags[], delivery, url. Carousels and results without a product page are left out, so rows can be fewer than depth; each row is an offer, so one product can appear twice. Cost: 1 credit per 40 results. Default 40 = 1 credit. Cached 1 day.

REST endpoint

POST /api/shopping/tools/shopping_search_products

Product-credit cost

1 credit per 40 results. Default 40 = 1 credit. Cached 1 day.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "keyword": {
      "type": "string",
      "minLength": 1,
      "maxLength": 700,
      "description": "Required. The product search."
    },
    "depth": {
      "default": 40,
      "description": "Max rows. Default 40, max 120; billed per 40.",
      "type": "integer",
      "minimum": 1,
      "maximum": 120
    },
    "location": {
      "default": "United States",
      "description": "Provider location name or code. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "keyword"
  ]
}

Get a Google Shopping product

shopping_get_product

One product's description, specs, images, rating and offers from each store. For a price comparison with shipping and totals use shopping_get_sellers; for reviews use shopping_get_reviews. Pass product_id, gid and data_docid together from the same shopping_search_products row: Google matches the product most reliably with all three. Read live; can take up to a minute. Returns product_id, gid, data_docid, title, description, url, images[], rating, ratings_count, specs[] (name, value), offers[] (seller, url, price, regular_price, currency, seller_rating, seller_ratings_count, availability). Cost: 1 credit. Cached 1 day.

REST endpoint

POST /api/shopping/tools/shopping_get_product

Product-credit cost

1 credit. Cached 1 day.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Required. product_id from a shopping_search_products row."
    },
    "gid": {
      "description": "gid from the same search row. Pass with product_id.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "data_docid": {
      "description": "data_docid from the same search row. Pass with product_id.",
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    },
    "location": {
      "default": "United States",
      "description": "Provider location name or code. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "product_id"
  ]
}

Compare a product's sellers

shopping_get_sellers

The stores Google shows for one product with base price, shipping, total and store rating: the cheapest seller, undercutting, which retailers carry it. Not for specs (shopping_get_product) or Amazon sellers (amazon_get_sellers). Pass product_id, gid and data_docid together from the same shopping_search_products row: Google matches the product most reliably with all three. Read live; can take up to a minute. Returns product_id, title and rows[]: rank, seller, domain, url, price, shipping (null when free or not shown), total_price, currency, seller_rating, seller_ratings_count, availability, note. Up to 20 stores, usually 5 to 10: Google's selection, not every retailer, and the store on the search row can be missing. Cost: 2 credits. Cached 6 hours.

REST endpoint

POST /api/shopping/tools/shopping_get_sellers

Product-credit cost

2 credits. Cached 6 hours.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Required. product_id from a shopping_search_products row."
    },
    "gid": {
      "description": "gid from the same search row. Pass with product_id.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "data_docid": {
      "description": "data_docid from the same search row. Pass with product_id.",
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    },
    "location": {
      "default": "United States",
      "description": "Provider location name or code. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "product_id"
  ]
}

Get a product's reviews

shopping_get_reviews

Reviews of one product pooled from the stores that sell it, with counts per star: buyer sentiment and the complaints in rivals' low-star reviews. Not for app reviews (apps_get_reviews); Amazon reviews are not available. Pass product_id, gid and data_docid together from the same shopping_search_products row: Google matches the product most reliably with all three. Read live; can take up to a minute. Returns product_id, title, rating, ratings_count, stars[] (stars, count) and rows[]: rating, title, text, author, source (the store it came from), published_at. Reviews arrive in batches of tens. Cost: 5 credits per 100 reviews. Default 100 = 5 credits. Cached 7 days.

REST endpoint

POST /api/shopping/tools/shopping_get_reviews

Product-credit cost

5 credits per 100 reviews. Default 100 = 5 credits. Cached 7 days.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Required. product_id from a shopping_search_products row."
    },
    "gid": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Required. gid from the same search row."
    },
    "data_docid": {
      "description": "data_docid from the same search row. Pass with product_id.",
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    },
    "location": {
      "default": "United States",
      "description": "Provider location name or code. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "limit": {
      "default": 100,
      "description": "Max rows. Default 100, cap 1000.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "product_id",
    "gid"
  ]
}