# Product Reviews with Sentiment Analysis (`e-commerce/product-reviews-sentiment`) Actor Collect product reviews, enrich each with sentiment, and generate a per-product sentiment report. - **URL**: https://apify.com/e-commerce/product-reviews-sentiment.md - **Developed by:** [E Commerce](https://apify.com/e-commerce) (Apify) - **Categories:** E-commerce, AI - **Stats:** 3 total users, 0 monthly users, 87.5% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $1.34 / 1,000 review sentiments 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 ## Product Reviews with Sentiment Analysis Collects product reviews, enriches every review with sentiment, and generates a full sentiment report per product. ### What it does 1. **Collects reviews** by calling the deployed e-commerce standby Actors directly (`e-commerce---standby.apify.actor`, `POST /reviews`) for each product or review URL, following pagination until every review is collected. 35 marketplaces are supported (Amazon, Walmart, eBay, IKEA, Target, Best Buy, and more). 2. **Enriches each review** with sentiment (positive / neutral / negative), a confidence score, and per-aspect sentiment, using OpenAI. One enriched row per review is written to the dataset. 3. **Generates a per-product report** across all of that product's reviews: an aspect-based sentiment analysis with themes, pain points, representative quotes, and recommendations. Each report is stored in the key-value store and summarized in the run log. ### Input Provide at least one product URL or review listing URL on a supported marketplace. Options: `sortReview`, `additionalReviewProperties`, `maxReviewsPerProduct`, `maxProducts` (report-spend safety cap), `generateReport`, and `reportFormat` (markdown / html / pdf). The OpenAI models and sentiment is handled internally - the customer pays per review scored and per report. #### Configuration (operator only, via env) - `OPENAI_API_KEY` - required. The Actor uses the operator's OpenAI account; the customer does not supply a key. - `PLATFORM_ACCOUNT_TOKEN` - required. Full Apify account token used to authenticate calls to the standby Actors (falls back to `APIFY_TOKEN`). - `SENTIMENT_MODEL` / `REPORT_MODEL` - optional overrides (default `gpt-4o-mini` / `gpt-4o`). ### Output - **Dataset**: one enriched review per row (`sentimentLabel`, `sentimentScore`, `aspects`, plus the original review fields). - **Key-value store**: per product, `report-.json` (machine-readable), `report-.md` or `.html` (human-readable), and `reports-index.json` mapping every product URL to its report records. ### Pricing (pay-per-event) | Event | When it is charged | | ------------------ | -------------------------------------------------- | | `review-sentiment` | Once per review scored and written to the dataset. | | `sentiment-report` | Once per product, after its report is stored. | # Actor input Schema ## `searchKeywords` (type: `array`): Enter product keywords (for example "wireless earbuds"). Each keyword is searched on every selected marketplace and the best-matching product is analyzed. Use this instead of, or alongside, pasting product URLs below. ## `searchSources` (type: `array`): Which marketplaces each keyword is searched on (78 supported). Only applies to keyword search, not to pasted URLs. ## `productReviewUrls` (type: `array`): Direct links to individual product pages on a supported marketplace. All reviews for each product are collected and analyzed. ## `reviewListingUrls` (type: `array`): Links to category or listing pages that contain multiple products (for example a Walmart category page). Each product found on the page is collected and its reviews analyzed. Bounded by "Maximum products". ## `sortReview` (type: `string`): How reviews are sorted before collection. Some marketplaces may not support all options and fall back to the default. ## `additionalReviewProperties` (type: `boolean`): Includes additional marketplace-specific properties on each collected review. ## `maxReviewsPerProduct` (type: `integer`): The maximum number of reviews to collect per product. ## `maxProducts` (type: `integer`): Safety cap on how many distinct products are analyzed in one run. A sentiment report is generated (and charged) per product, so this bounds report spend. ## `generateReport` (type: `boolean`): Off by default. When enabled, a full sentiment report is generated per product and stored in the key-value store. Each report is a paid event, so turn this on only when you want the reports. ## `reportFormat` (type: `string`): Human-readable report written to the key-value store. A machine-readable JSON report is always written alongside it. ## Actor input object example ```json { "searchSources": [ "amazon", "ebay", "walmart", "mercadolibre" ], "sortReview": "Most recent", "additionalReviewProperties": true, "maxReviewsPerProduct": 100, "maxProducts": 25, "generateReport": false, "reportFormat": "html" } ```` # 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 = { "additionalReviewProperties": true, "maxReviewsPerProduct": 100 }; // Run the Actor and wait for it to finish const run = await client.actor("e-commerce/product-reviews-sentiment").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 = { "additionalReviewProperties": True, "maxReviewsPerProduct": 100, } # Run the Actor and wait for it to finish run = client.actor("e-commerce/product-reviews-sentiment").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 '{ "additionalReviewProperties": true, "maxReviewsPerProduct": 100 }' | apify call e-commerce/product-reviews-sentiment --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=e-commerce/product-reviews-sentiment", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Product Reviews with Sentiment Analysis", "description": "Collect product reviews, enrich each with sentiment, and generate a per-product sentiment report.", "version": "0.0", "x-build-id": "nxzjdGPVjdOZoKPd4" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/e-commerce~product-reviews-sentiment/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-e-commerce-product-reviews-sentiment", "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/e-commerce~product-reviews-sentiment/runs": { "post": { "operationId": "runs-sync-e-commerce-product-reviews-sentiment", "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/e-commerce~product-reviews-sentiment/run-sync": { "post": { "operationId": "run-sync-e-commerce-product-reviews-sentiment", "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", "properties": { "searchKeywords": { "title": "Product keywords", "type": "array", "description": "Enter product keywords (for example \"wireless earbuds\"). Each keyword is searched on every selected marketplace and the best-matching product is analyzed. Use this instead of, or alongside, pasting product URLs below.", "items": { "type": "string" } }, "searchSources": { "title": "Marketplaces to search", "type": "array", "description": "Which marketplaces each keyword is searched on (78 supported). Only applies to keyword search, not to pasted URLs.", "items": { "type": "string", "enum": [ "academy", "ae", "albertsons", "aldi-uk", "alibaba", "allegro", "alza", "amazon", "anthropologie", "ao", "argos", "ariat", "asda-uk", "ashleyfurniture", "autozone", "barnesandnoble", "basspro", "bestbuy", "bjs", "bloomingdales", "bluemercury", "boots", "cdiscount", "chewy", "coles", "coop-uk", "costco", "cvs", "deliveroo", "dicks", "ebay", "galaxus-ch", "glovo", "goofish", "google-shopping", "harborfreight", "homedepot", "iceland-uk", "idealo", "ikea", "instacart", "insulationpoint", "john-lewis", "justeat", "kaufland", "kohls", "lidl-uk", "lowes", "macys", "mands-food-uk", "meijer", "menswearhouse", "mercadolibre", "morrisons-uk", "newegg", "noon", "nordstrom", "ocado-uk", "petco", "sainsburys-uk", "saloncentric", "sephora", "smyths", "spacenk", "staples-ca", "staples-us", "superdrug", "takealot", "taobao", "target", "tesco-uk", "tractorsupply", "ulta", "waitrose-uk", "walgreens", "walmart", "wayfair", "wolt" ], "enumTitles": [ "Academy Sports + Outdoors", "American Eagle", "Albertsons", "Aldi (UK)", "Alibaba", "Allegro", "Alza", "Amazon", "Anthropologie", "AO", "Argos", "Ariat", "Asda (UK)", "Ashley Furniture", "AutoZone", "Barnes & Noble", "Bass Pro Shops", "Best Buy", "BJ’s Wholesale", "Bloomingdale’s", "Bluemercury", "Boots", "Cdiscount", "Chewy", "Coles", "Co-op (UK)", "Costco", "CVS", "Deliveroo", "Dick’s Sporting Goods", "eBay", "Galaxus (CH)", "Glovo", "Goofish", "Google Shopping", "Harbor Freight", "The Home Depot", "Iceland (UK)", "Idealo", "IKEA", "Instacart", "Insulation Point", "John Lewis", "Just Eat", "Kaufland", "Kohl’s", "Lidl (UK)", "Lowe’s", "Macy’s", "M&S Food (UK)", "Meijer", "Men’s Wearhouse", "Mercado Libre", "Morrisons (UK)", "Newegg", "Noon", "Nordstrom", "Ocado (UK)", "Petco", "Sainsbury’s (UK)", "SalonCentric", "Sephora", "Smyths Toys", "Space NK", "Staples (CA)", "Staples", "Superdrug", "Takealot", "Taobao", "Target", "Tesco (UK)", "Tractor Supply", "Ulta", "Waitrose (UK)", "Walgreens", "Walmart", "Wayfair", "Wolt" ] }, "default": [ "amazon", "ebay", "walmart", "mercadolibre" ] }, "productReviewUrls": { "title": "Product URLs", "type": "array", "description": "Direct links to individual product pages on a supported marketplace. All reviews for each product are collected and analyzed.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "reviewListingUrls": { "title": "Review listing URLs", "type": "array", "description": "Links to category or listing pages that contain multiple products (for example a Walmart category page). Each product found on the page is collected and its reviews analyzed. Bounded by \"Maximum products\".", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "sortReview": { "title": "Review sort type", "enum": [ "Most recent", "Most relevant", "Most helpful", "Highest rated", "Lowest rated" ], "type": "string", "description": "How reviews are sorted before collection. Some marketplaces may not support all options and fall back to the default.", "default": "Most recent" }, "additionalReviewProperties": { "title": "Include additional review properties", "type": "boolean", "description": "Includes additional marketplace-specific properties on each collected review." }, "maxReviewsPerProduct": { "title": "Maximum reviews per product", "minimum": 1, "type": "integer", "description": "The maximum number of reviews to collect per product." }, "maxProducts": { "title": "Maximum products", "minimum": 1, "type": "integer", "description": "Safety cap on how many distinct products are analyzed in one run. A sentiment report is generated (and charged) per product, so this bounds report spend.", "default": 25 }, "generateReport": { "title": "Generate per-product report", "type": "boolean", "description": "Off by default. When enabled, a full sentiment report is generated per product and stored in the key-value store. Each report is a paid event, so turn this on only when you want the reports.", "default": false }, "reportFormat": { "title": "Report format", "enum": [ "html", "pdf" ], "type": "string", "description": "Human-readable report written to the key-value store. A machine-readable JSON report is always written alongside it.", "default": "html" } } }, "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 } } } } } } } } } } ```