# Google Shopping Price Tracker — Offers & Price History (`sian.agency/google-shopping-price-scraper`) Actor Track Google Shopping prices across every retailer. Product search, cross-store offers, full price history, reviews and deals in one actor — clean JSON, pay per result. Built for price monitoring, competitor price tracking and product price intelligence. - **URL**: https://apify.com/sian.agency/google-shopping-price-scraper.md - **Developed by:** [SIÁN OÜ](https://apify.com/sian.agency) (community) - **Categories:** E-commerce, Business, Marketing - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $1.50 / 1,000 product search results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Google Shopping Price Tracker — Offers & Price History 🚀 [![SIÁN Agency Store](https://img.shields.io/badge/Store-SI%C3%81N%20Agency-1AE392)](https://apify.com/sian.agency?fpr=sian) [![Walmart Scraper](https://img.shields.io/badge/Store-Walmart%20Scraper-0071CE)](https://apify.com/sian.agency/walmart-data-scraper?fpr=sian) [![eBay Scraper](https://img.shields.io/badge/Store-eBay%20Scraper-E53238)](https://apify.com/sian.agency/ebay-data-scraper?fpr=sian) [![Amazon ASIN Lookup](https://img.shields.io/badge/Store-Amazon%20ASIN%20Lookup-FF9900)](https://apify.com/sian.agency/amazon-asin-lookup?fpr=sian) #### 🎉 The only Google Shopping actor that returns cross-retailer PRICE HISTORY — a per-store price time series no other scraper gives you ##### Built for price-monitoring teams, competitive-intelligence analysts, repricing tools, and deal/affiliate sites that need real cross-store price data --- ### 📋 Overview **Track what every retailer charges for a product — and how that price moved over time.** Google Shopping Price Tracker turns Google Shopping into clean, structured datasets: search products, pull every store's offer for one product, get a per-store price-history time series, scrape reviews and deals — all from one actor, with no account or API key to manage. **Why price-intelligence teams choose us:** - 📈 **Cross-retailer price history**: a per-store time series of a product's price over months — the one column no other Google Shopping actor on the store returns. - 🛒 **Every store's offer in one call**: see each retailer's price, original price, shipping, returns, condition, and store rating side by side — instant cross-store price comparison. - ⚡ **8 operations in one actor**: search, light search, deals, product details, product offers, price history, product reviews, and store reviews — no juggling separate tools. - 💰 **Pay per result**: only charged for successful rows, priced to undercut the category. A free tier lets you test with zero commitment. - 💎 **Clean JSON, ready to use**: curated camelCase fields (`productTitle`, `offerPrice`, `store`, `priceHistory`, `latestPrice`, `reviewText`) plus the full raw payload spread alongside. --- ### ✨ Features - 🔍 **Product Search**: find products by keyword with rating, photos, offer count, and the headline offer per product. - ⚡ **Light Search**: a faster, lighter search mode for high-volume scans at a lower per-result cost. - 🏷️ **Deals**: surface on-sale products and discount percentages across stores for any query. - 📦 **Product Details**: full product record — description, attributes, photos, variants, rating, and reviews insights. - 🛒 **Product Offers**: every store selling a product, with price, shipping, returns, condition, and store reputation — paginated. - 📈 **Price History**: per-store price time series with first/last date, latest price, and observed min/max — one tidy row per store. - ⭐ **Product Reviews**: paginated reviews with rating, author, source, and the rating distribution. - 🏪 **Store Reviews**: merchant-level reviews by domain for seller-reputation analysis. - 🌍 **Multi-market**: target any Google Shopping country and language. --- ### 🎬 Quick Start Pick an operation, give it a query or a product ID, and run. Results land in the Apify dataset as flat rows you can export to JSON, CSV, or Excel. Start with **Product Search** to grab `productId` values, then feed them into Product Offers, Price History, or Reviews. ```bash curl -X POST "https://api.apify.com/v2/acts/sian.agency~google-shopping-price-scraper/runs?token=YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"operation": "search", "query": "airpods pro", "country": "us", "maxPages": 2}' ```` *** ### 🚀 Getting Started (3 Simple Steps) #### Step 1: Choose an operation Select one of the eight operations (e.g. `search`, `productOffers`, `priceHistory`) — each run does one operation. #### Step 2: Provide the input it needs Search/deals need a `query`; details/offers/price history/product reviews need a `productId`; store reviews need a `storeDomain`. #### Step 3: Run and export Hit **Start** and watch rows fill the dataset. Export to JSON, CSV, or Excel, or pull them via the API. **That's it! In under a minute, you'll have:** - Clean, structured Google Shopping rows - A ready-to-query dataset (filter by `_operation`) - An HTML run report with counts and timing *** ### 📥 Input Configuration | Field | Type | Required | Description | |-------|------|----------|-------------| | operation | string | Yes | One of `search`, `searchLight`, `deals`, `productDetails`, `productOffers`, `priceHistory`, `productReviews`, `storeReviews` | | query | string | For search/deals | Keyword to search (e.g. `4k monitor`) | | productId | string | For details/offers/price history/reviews | Google Shopping product ID (copy from a search row) | | storeDomain | string | For store reviews | Merchant root domain (e.g. `walmart.com`) | | country | string | No | Two-letter market code (default `us`) | | language | string | No | Two-letter language code (default `en`) | | maxPages | integer | No | Max pages for paginated ops (default 3) | | sortBy | string | No | `BEST_MATCH`, `LOWEST_PRICE`, `HIGHEST_PRICE`, `TOP_RATED` | | minPrice / maxPrice | integer | No | Price range filter for search/deals | | productCondition | string | No | `ANY`, `NEW`, `USED`, `REFURBISHED` | | onSale / freeShipping / freeReturns | boolean | No | Offer filters for search/deals | | reviewSort | string | No | `MOST_RELEVANT` or `DATE` (newest) | **Example — cross-store offers:** ```json { "operation": "productOffers", "productId": "catalogid:2327420681279440941,productid:15969768374614330185,...", "country": "us", "maxPages": 2 } ``` **Example — price history:** ```json { "operation": "priceHistory", "productId": "catalogid:2327420681279440941,productid:15969768374614330185,..." } ``` *** ### 📤 Output Results are saved to the Apify dataset as flat rows. Filter by `_operation` to split modes. Key fields include: | Field | Type | Description | |-------|------|-------------| | productId | string | Google Shopping product ID | | productTitle | string | Product name | | productRating | number | Average rating | | offerStoreName | string | Headline offer's store | | offerPrice | string | Headline offer price | | store | string | Store name (Price History rows) | | priceHistory | array | Per-store `{date, price}` time series | | latestPrice | string | Most recent observed price | | minPriceObserved / maxPriceObserved | number | Lowest / highest price in the series | | storeName / price / shipping / returns | string | Per-offer fields (Product Offers) | | storeRating / storeReviewCount | string / int | Merchant reputation | | reviewText / reviewRating / reviewAuthor | string / number | Review fields | | \_operation / \_page / status | string | Run metadata | **Example — a Price History row:** ```json { "_operation": "priceHistory", "store": "Walmart", "productId": "catalogid:2327420681279440941,...", "latestPrice": "$249.00", "minPriceObserved": 199, "maxPriceObserved": 249, "pointCount": 273, "firstDate": "2025-09-09", "lastDate": "2026-06-08", "priceHistory": [ { "date": "2025-09-09", "price": "$249.00" }, { "date": "2025-11-28", "price": "$199.00" } ], "status": "success" } ``` *** ### 💼 Use Cases & Examples #### 1. Cross-Retailer Price Comparison **E-commerce analysts who need the cheapest seller for any product across every store.** **Input:** A `productId` with the **Product Offers** operation. **Output:** One row per store — price, original price, shipping, returns, condition, store rating. **Use:** Find the lowest price, benchmark your buy-box position, build a price-comparison page. #### 2. Price History & Trend Monitoring **Repricing and MAP-compliance tools that need real historical price data.** **Input:** A `productId` with the **Price History** operation. **Output:** A per-store time series with min/max/latest and date range. **Use:** Detect price drops, validate MAP compliance, power "price dropped" alerts, spot seasonal patterns. #### 3. Competitor Price Tracking **Brand and category managers tracking how rivals price your segment.** **Input:** A category keyword with **Product Search**, scheduled daily. **Output:** Ranked products with prices, ratings, and headline offers. **Use:** Diff the dataset over time to quantify where you sit and when competitors move. #### 4. Deal & Promotion Discovery **Affiliate and deal-site builders feeding fresh discounts to their audience.** **Input:** A query with the **Deals** operation. **Output:** On-sale products with discount percentages across stores. **Use:** Populate deal aggregators, promo calendars, and affiliate feeds with structured rows. #### 5. Voice-of-Customer Sentiment Analysis **Product teams mining what buyers actually say about a product.** **Input:** A `productId` with the **Product Reviews** operation. **Output:** Paginated reviews with rating, text, author, source, and the rating distribution. **Use:** Feed sentiment models, surface complaints and feature requests, and quantify what drives a product's score. #### 6. Merchant Reputation & Seller-Risk Screening **Trust, procurement, and marketplace teams vetting which stores to buy from or list against.** **Input:** A `storeDomain` (e.g. `walmart.com`) with the **Store Reviews** operation. **Output:** Merchant-level reviews by domain with rating, text, and distribution. **Use:** Benchmark seller reputation, flag high-risk merchants, and weight cross-store offers by store trust. #### 7. High-Volume Catalog Scans **Data teams crawling thousands of queries on a tight per-result budget.** **Input:** A `query` with the **Light Search** operation, scheduled in bulk. **Output:** A faster, leaner product feed at a lower per-result cost than full search. **Use:** Cover a wide catalog cheaply, then deepen only the products worth a full Details or Offers pull. *** ### 🔗 Integration Examples #### JavaScript/Node.js ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_TOKEN' }); const run = await client.actor('sian.agency/google-shopping-price-scraper').call({ operation: 'search', query: 'airpods pro', country: 'us', maxPages: 2, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items[0]); ``` #### Python ```python from apify_client import ApifyClient client = ApifyClient('YOUR_TOKEN') run = client.actor('sian.agency/google-shopping-price-scraper').call( run_input={'operation': 'priceHistory', 'productId': 'PRODUCT_ID'} ) for item in client.dataset(run['defaultDatasetId']).iterate_items(): print(item) ``` #### cURL ```bash curl -X POST 'https://api.apify.com/v2/acts/sian.agency~google-shopping-price-scraper/runs?token=YOUR_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"operation": "productOffers", "productId": "PRODUCT_ID"}' ``` #### Automation Workflows (N8N / Zapier / Make) 1. **Trigger**: Schedule (e.g. daily price check) or webhook 2. **HTTP Request**: Call the actor API 3. **Process**: Handle the JSON rows (diff prices, detect drops) 4. **Action**: Alert, save to a sheet, or update your repricing engine *** ### 📊 Performance & Pricing #### FREE Tier (Try It Now) - Test every operation with full feature access — same data quality - No credit card required - Perfect for evaluating fit and small projects #### PAID Tier (Production Ready) - Scale across thousands of products on a schedule - Pay-per-result: only charged for successful rows - Premium operations (cross-store offers, price history) priced for their value 💰 **Priced to undercut the category** — pay only for the rows you keep. 🔗 [View current pricing](https://apify.com/sian.agency/google-shopping-price-scraper?fpr=sian) *** ### ❓ Frequently Asked Questions **Q: What is a `productId` and where do I get it?** A: It's the Google Shopping product identifier. Run **Product Search** first and copy the `productId` field from any row, then use it with Product Details, Product Offers, Price History, or Product Reviews. **Q: Which operation gives cross-store price comparison?** A: **Product Offers** — it returns one row per store selling the product, with price, shipping, returns, condition, and store rating. **Q: How far back does price history go?** A: **Price History** returns the full per-store series Google Shopping exposes (often several months). Each store is one row with a nested `{date, price}` array plus computed min/max/latest. **Q: What output formats are available?** A: JSON, CSV, and Excel — export directly from the Apify dataset, or pull rows via the API. **Q: Can I scrape other countries?** A: Yes — set `country` and `language` to target any Google Shopping market. **Q: Do I pay per page or per result?** A: Per result — you're only charged for the successful rows you keep, not for pages or failed calls. The free tier lets you test every operation before scaling. **Q: How do I run cross-retailer price comparison at scale?** A: Run **Product Search** on a schedule to collect `productId` values, then fan them into **Product Offers** (cross-store prices) and **Price History** (per-store trends). Diff the dataset over time to track movement automatically. **Q: Is this legal?** A: Yes — only publicly available product data is extracted. See the legal section below. *** ### 🐛 Troubleshooting **No rows returned for a search** - Broaden the query, remove price/condition filters, and confirm the `country` has Shopping results. **"Invalid parameters" error** - Check that the operation has its required field (search/deals → `query`; details/offers/price history/reviews → `productId`; store reviews → `storeDomain`). **Price History returned no stores** - Not every product has multi-store history on Google Shopping. Try a popular product `productId` from a fresh search. **Pagination stops early** - The actor stops when the data source signals no more results. Increase `maxPages` if you need a deeper crawl. *** ### ⚠️ Trademark Disclaimer This actor is an independent tool built by SIÁN Agency. It is **not** affiliated with, endorsed by, or sponsored by Google LLC. "Google" and "Google Shopping" are trademarks of Google LLC. Retailer and store names that appear in results (Walmart, Amazon, etc.) are trademarks of their respective owners. This actor accesses only publicly available product information and is intended for lawful, ethical use. *** ### ⚖️ Is it legal to scrape data? Our actors are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what has been chosen to be shared publicly. We therefore believe that our actors, when used for ethical purposes by Apify users, are safe. However, you should be aware that your results could contain personal data. Personal data is protected by the **GDPR** in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers. You can also read Apify's blog post on the [legality of web scraping](https://blog.apify.com/is-web-scraping-legal/). *** ### 🤝 Support [![Telegram Support](https://img.shields.io/badge/Telegram-Support%20Group-0088cc?logo=telegram)](https://t.me/+vyh1sRE08sAxMGRi) **Join our active support community** - For issues or questions, open an issue in the actor's Issues tab - Check the [SIÁN Agency Store](https://apify.com/sian.agency?fpr=sian) for more automation tools - 📧 *** **Built by [SIÁN Agency](https://www.sian-agency.online)** | **[More Tools](https://apify.com/sian.agency?fpr=sian)** # Actor input Schema ## `operation` (type: `string`): Which Google Shopping operation to run. Each run does exactly one operation. • **Product Search** — search products by keyword (rich rows: title, rating, photos, headline offer) • **Product Search (Light)** — faster, lighter search rows (cheaper per result) • **Deals** — on-sale products & discounts for a query • **Product Details** — full details for one product by ID • **Product Offers** — every store's offer for one product (cross-retailer price comparison) • **Price History** — per-store price time series for one product (the exclusive column) • **Product Reviews** — paginated reviews for one product • **Store Reviews** — reviews for a merchant by domain ## `query` (type: `string`): 🔍 Keyword to search. Required for **Product Search**, **Product Search (Light)** and **Deals** (e.g. `airpods pro`, `4k monitor`). ## `productId` (type: `string`): 📦 Google Shopping product ID. Required for **Product Details**, **Product Offers**, **Price History** and **Product Reviews**. Copy the `productId` value from a Product Search row. ## `storeDomain` (type: `string`): 🏪 Merchant root domain for **Store Reviews** (e.g. `walmart.com`, `bestbuy.com`). ## `country` (type: `string`): 🌍 Two-letter country code for the Google Shopping market (e.g. `us`, `gb`, `de`). Defaults to `us`. ## `language` (type: `string`): 🗣️ Two-letter language code (e.g. `en`, `de`, `fr`). Defaults to `en`. ## `maxPages` (type: `integer`): 📄 Maximum pages to fetch for paginated operations (search, search-light, deals, offers, reviews, store reviews). Each page is one upstream call. Single-shot ops (details, price history) ignore this. ## `sortBy` (type: `string`): ↕️ Sort order for **Product Search** and **Deals**. ## `minPrice` (type: `integer`): 💵 Minimum price filter for **Product Search** / **Deals** (optional). ## `maxPrice` (type: `integer`): 💵 Maximum price filter for **Product Search** / **Deals** (optional). ## `productCondition` (type: `string`): 🏷️ Condition filter for **Product Search** / **Deals** (optional). ## `onSale` (type: `boolean`): 🔖 Limit **Product Search** / **Deals** to on-sale products only. ## `freeShipping` (type: `boolean`): 🚚 Limit **Product Search** / **Deals** to free-shipping offers only. ## `freeReturns` (type: `boolean`): ↩️ Limit **Product Search** / **Deals** to free-returns offers only. ## `stores` (type: `string`): 🏬 Comma-separated store names to limit **Product Search** / **Deals** to specific retailers (optional, e.g. `Walmart,Amazon`). ## `reviewSort` (type: `string`): ⭐ Sort order. For **Product Reviews**: Most relevant or Newest. For **Store Reviews**, Newest maps to most-recent and Most relevant to most-helpful. ## `reviewRating` (type: `integer`): 🌟 Only return reviews with this star rating (1–5) for **Product Reviews** / **Store Reviews** (optional). ## `reviewLimit` (type: `integer`): 🔢 Reviews per page for **Product Reviews** / **Store Reviews** (optional, upstream default ~10). ## Actor input object example ```json { "operation": "search", "query": "airpods pro", "country": "us", "language": "en", "maxPages": 3, "sortBy": "BEST_MATCH", "productCondition": "ANY", "onSale": false, "freeShipping": false, "freeReturns": false, "reviewSort": "MOST_RELEVANT" } ``` # Actor output Schema ## `output` (type: `string`): Per-row results — one flat row per upstream item with curated camelCase aliases (productId, productTitle, price, offerPrice, store, priceHistory, latestPrice, reviewText, …) plus the raw upstream fields spread alongside. Price History returns one row per store with a nested time series. ## `report` (type: `string`): HTML report with run status, success/error row counts, success rate, pages fetched, duration, and the inputs used — written even on fatal crash. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "query": "airpods pro", "country": "us", "language": "en", "maxPages": 3 }; // Run the Actor and wait for it to finish const run = await client.actor("sian.agency/google-shopping-price-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "query": "airpods pro", "country": "us", "language": "en", "maxPages": 3, } # Run the Actor and wait for it to finish run = client.actor("sian.agency/google-shopping-price-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "query": "airpods pro", "country": "us", "language": "en", "maxPages": 3 }' | apify call sian.agency/google-shopping-price-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=sian.agency/google-shopping-price-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Google Shopping Price Tracker — Offers & Price History", "description": "Track Google Shopping prices across every retailer. Product search, cross-store offers, full price history, reviews and deals in one actor — clean JSON, pay per result. Built for price monitoring, competitor price tracking and product price intelligence.", "version": "1.0", "x-build-id": "IzHvdII7bH3pW4KbC" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/sian.agency~google-shopping-price-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-sian.agency-google-shopping-price-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/sian.agency~google-shopping-price-scraper/runs": { "post": { "operationId": "runs-sync-sian.agency-google-shopping-price-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/sian.agency~google-shopping-price-scraper/run-sync": { "post": { "operationId": "run-sync-sian.agency-google-shopping-price-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "operation" ], "properties": { "operation": { "title": "Operation", "enum": [ "search", "searchLight", "deals", "productDetails", "productOffers", "priceHistory", "productReviews", "storeReviews" ], "type": "string", "description": "Which Google Shopping operation to run. Each run does exactly one operation.\n\n• **Product Search** — search products by keyword (rich rows: title, rating, photos, headline offer)\n• **Product Search (Light)** — faster, lighter search rows (cheaper per result)\n• **Deals** — on-sale products & discounts for a query\n• **Product Details** — full details for one product by ID\n• **Product Offers** — every store's offer for one product (cross-retailer price comparison)\n• **Price History** — per-store price time series for one product (the exclusive column)\n• **Product Reviews** — paginated reviews for one product\n• **Store Reviews** — reviews for a merchant by domain", "default": "search" }, "query": { "title": "Search query", "type": "string", "description": "🔍 Keyword to search. Required for **Product Search**, **Product Search (Light)** and **Deals** (e.g. `airpods pro`, `4k monitor`)." }, "productId": { "title": "Product ID", "type": "string", "description": "📦 Google Shopping product ID. Required for **Product Details**, **Product Offers**, **Price History** and **Product Reviews**. Copy the `productId` value from a Product Search row." }, "storeDomain": { "title": "Store domain", "type": "string", "description": "🏪 Merchant root domain for **Store Reviews** (e.g. `walmart.com`, `bestbuy.com`)." }, "country": { "title": "Country", "type": "string", "description": "🌍 Two-letter country code for the Google Shopping market (e.g. `us`, `gb`, `de`). Defaults to `us`.", "default": "us" }, "language": { "title": "Language", "type": "string", "description": "🗣️ Two-letter language code (e.g. `en`, `de`, `fr`). Defaults to `en`.", "default": "en" }, "maxPages": { "title": "Max pages", "minimum": 1, "maximum": 50, "type": "integer", "description": "📄 Maximum pages to fetch for paginated operations (search, search-light, deals, offers, reviews, store reviews). Each page is one upstream call. Single-shot ops (details, price history) ignore this.", "default": 3 }, "sortBy": { "title": "Sort by (search / deals)", "enum": [ "BEST_MATCH", "LOWEST_PRICE", "HIGHEST_PRICE", "TOP_RATED" ], "type": "string", "description": "↕️ Sort order for **Product Search** and **Deals**.", "default": "BEST_MATCH" }, "minPrice": { "title": "Min price", "type": "integer", "description": "💵 Minimum price filter for **Product Search** / **Deals** (optional)." }, "maxPrice": { "title": "Max price", "type": "integer", "description": "💵 Maximum price filter for **Product Search** / **Deals** (optional)." }, "productCondition": { "title": "Product condition", "enum": [ "ANY", "NEW", "USED", "REFURBISHED" ], "type": "string", "description": "🏷️ Condition filter for **Product Search** / **Deals** (optional).", "default": "ANY" }, "onSale": { "title": "On sale only", "type": "boolean", "description": "🔖 Limit **Product Search** / **Deals** to on-sale products only.", "default": false }, "freeShipping": { "title": "Free shipping only", "type": "boolean", "description": "🚚 Limit **Product Search** / **Deals** to free-shipping offers only.", "default": false }, "freeReturns": { "title": "Free returns only", "type": "boolean", "description": "↩️ Limit **Product Search** / **Deals** to free-returns offers only.", "default": false }, "stores": { "title": "Stores filter", "type": "string", "description": "🏬 Comma-separated store names to limit **Product Search** / **Deals** to specific retailers (optional, e.g. `Walmart,Amazon`)." }, "reviewSort": { "title": "Review sort", "enum": [ "MOST_RELEVANT", "DATE" ], "type": "string", "description": "⭐ Sort order. For **Product Reviews**: Most relevant or Newest. For **Store Reviews**, Newest maps to most-recent and Most relevant to most-helpful.", "default": "MOST_RELEVANT" }, "reviewRating": { "title": "Review rating filter", "minimum": 1, "maximum": 5, "type": "integer", "description": "🌟 Only return reviews with this star rating (1–5) for **Product Reviews** / **Store Reviews** (optional)." }, "reviewLimit": { "title": "Reviews per page", "minimum": 1, "maximum": 100, "type": "integer", "description": "🔢 Reviews per page for **Product Reviews** / **Store Reviews** (optional, upstream default ~10)." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```