{ "data": { "id": "z8cnStIuloUeKmTKD", "actId": "1u5Fn40qo93nWNJ8t", "userId": "NL4ThgItAwaoBlffQ", "startedAt": "2026-11-06T13:30:53.411Z", "finishedAt": "2026-11-06T13:31:29.408Z", "status": "SUCCEEDED", "meta": { "origin": "CLI" }, "stats": { "durationMillis": 35785, "runTimeSecs": 35.785, "computeUnits": 0.03976111111111111, "imageSizeBytes": 3313318400 }, "options": { "useCache": true, "betaPackages": false, "memoryMbytes": 4096, "diskMbytes": 8192 }, "createdByOrganizationMemberUserId": "zifX0mkAFMHe8CatY", "exitCode": 0, "inputSchema": "{\n \"title\": \"Amazon Customer Review & Rating Summary Scraper Input\",\n \"description\": \"Collect Amazon customer reviews plus each product's rating summary with no login or proxy setup. Add product URLs/ASINs or discover products by keyword; reviews are merged and deduplicated, with optional extended history and filters.\",\n \"type\": \"object\",\n \"schemaVersion\": 1,\n \"properties\": {\n \"productUrls\": {\n \"title\": \"Product URLs or ASINs\",\n \"type\": \"array\",\n \"description\": \"Amazon product URLs (/dp/, /gp/product/, /gp/aw/d/, /product/) or bare 10-character ASINs, on any supported Amazon domain. Leave empty to discover products from `keywords`/`categoryUrls` instead.\",\n \"editor\": \"stringList\",\n \"prefill\": [\n \"https://www.amazon.com/dp/B09X7MPX8L\"\n ],\n \"items\": {\n \"type\": \"string\"\n },\n \"sectionCaption\": \"Products\",\n \"sectionDescription\": \"Scrape these products, or leave empty and discover products by keyword or category.\"\n },\n \"keywords\": {\n \"title\": \"Keywords (discover products)\",\n \"type\": \"array\",\n \"description\": \"Search terms used to discover products when `productUrls` is empty (e.g. \\\"wireless earbuds\\\"). Each keyword contributes up to `maxProductsToDiscover` products.\",\n \"editor\": \"stringList\",\n \"prefill\": [],\n \"default\": [],\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"categoryUrls\": {\n \"title\": \"Category or Search URLs (discover products)\",\n \"type\": \"array\",\n \"description\": \"Advanced discovery: Amazon `/s?...` search URLs or `/b?node=...` category URLs. Used only when `productUrls` is empty.\",\n \"editor\": \"stringList\",\n \"prefill\": [],\n \"default\": [],\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"maxProductsToDiscover\": {\n \"title\": \"Max Products to Discover\",\n \"type\": \"integer\",\n \"description\": \"Maximum products discovered from each keyword or category URL (1-50). Ignored when `productUrls` is supplied.\",\n \"editor\": \"number\",\n \"default\": 5,\n \"prefill\": 5,\n \"minimum\": 1,\n \"maximum\": 50\n },\n \"country\": {\n \"title\": \"Amazon Marketplace\",\n \"type\": \"string\",\n \"description\": \"Amazon storefront to use for bare ASINs, discovery, and products whose URL does not carry a domain. Product URLs keep their own domain.\",\n \"editor\": \"select\",\n \"default\": \"amazon.com\",\n \"prefill\": \"amazon.com\",\n \"enum\": [\n \"amazon.com\",\n \"amazon.co.uk\",\n \"amazon.de\",\n \"amazon.fr\",\n \"amazon.it\",\n \"amazon.es\",\n \"amazon.ca\",\n \"amazon.com.au\",\n \"amazon.co.jp\",\n \"amazon.in\",\n \"amazon.com.br\",\n \"amazon.com.mx\",\n \"amazon.nl\",\n \"amazon.sg\",\n \"amazon.ae\",\n \"amazon.sa\",\n \"amazon.pl\",\n \"amazon.se\",\n \"amazon.com.tr\",\n \"amazon.ie\",\n \"amazon.com.be\",\n \"amazon.co.za\",\n \"amazon.eg\"\n ],\n \"enumTitles\": [\n \"United States (amazon.com)\",\n \"United Kingdom (amazon.co.uk)\",\n \"Germany (amazon.de)\",\n \"France (amazon.fr)\",\n \"Italy (amazon.it)\",\n \"Spain (amazon.es)\",\n \"Canada (amazon.ca)\",\n \"Australia (amazon.com.au)\",\n \"Japan (amazon.co.jp)\",\n \"India (amazon.in)\",\n \"Brazil (amazon.com.br)\",\n \"Mexico (amazon.com.mx)\",\n \"Netherlands (amazon.nl)\",\n \"Singapore (amazon.sg)\",\n \"United Arab Emirates (amazon.ae)\",\n \"Saudi Arabia (amazon.sa)\",\n \"Poland (amazon.pl)\",\n \"Sweden (amazon.se)\",\n \"Turkey (amazon.com.tr)\",\n \"Ireland (amazon.ie)\",\n \"Belgium (amazon.com.be)\",\n \"South Africa (amazon.co.za)\",\n \"Egypt (amazon.eg)\"\n ]\n },\n \"maxReviews\": {\n \"title\": \"Max Reviews per Product\",\n \"type\": \"integer\",\n \"description\": \"Hard cap per product after merging and deduplication (1-2000). The product-page sample alone yields about 8-13 rows; the optional extended feed can add 100-800+ for popular US products. In optional cookie mode this is the paginated cap.\",\n \"editor\": \"number\",\n \"default\": 100,\n \"prefill\": 15,\n \"minimum\": 1,\n \"maximum\": 2000,\n \"sectionCaption\": \"Review collection\",\n \"sectionDescription\": \"Control review depth and which public sources are merged.\"\n },\n \"extendedHistory\": {\n \"title\": \"Extended Review History\",\n \"type\": \"boolean\",\n \"description\": \"Merge Amazon's public extended review feed for each ASIN (no login): up to 100 rows per star/sort bucket, typically 100-800+ unique reviews for popular US products, deduplicated against the product-page sample. Coverage varies by ASIN and the feed carries Amazon.com reviews only.\",\n \"default\": true,\n \"prefill\": true\n },\n \"mergeMarketplaces\": {\n \"title\": \"Merge Extra Marketplaces\",\n \"type\": \"array\",\n \"description\": \"Fetch the same product on these additional Amazon marketplaces and merge their deduplicated product-page reviews. Empty = the product's own marketplace only.\",\n \"editor\": \"select\",\n \"prefill\": [],\n \"default\": [],\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"amazon.com\",\n \"amazon.co.uk\",\n \"amazon.de\",\n \"amazon.fr\",\n \"amazon.it\",\n \"amazon.es\",\n \"amazon.ca\",\n \"amazon.com.au\",\n \"amazon.co.jp\",\n \"amazon.in\",\n \"amazon.com.br\",\n \"amazon.com.mx\",\n \"amazon.nl\",\n \"amazon.sg\",\n \"amazon.ae\",\n \"amazon.sa\",\n \"amazon.pl\",\n \"amazon.se\",\n \"amazon.com.tr\",\n \"amazon.ie\",\n \"amazon.com.be\",\n \"amazon.co.za\",\n \"amazon.eg\"\n ],\n \"enumTitles\": [\n \"United States (amazon.com)\",\n \"United Kingdom (amazon.co.uk)\",\n \"Germany (amazon.de)\",\n \"France (amazon.fr)\",\n \"Italy (amazon.it)\",\n \"Spain (amazon.es)\",\n \"Canada (amazon.ca)\",\n \"Australia (amazon.com.au)\",\n \"Japan (amazon.co.jp)\",\n \"India (amazon.in)\",\n \"Brazil (amazon.com.br)\",\n \"Mexico (amazon.com.mx)\",\n \"Netherlands (amazon.nl)\",\n \"Singapore (amazon.sg)\",\n \"United Arab Emirates (amazon.ae)\",\n \"Saudi Arabia (amazon.sa)\",\n \"Poland (amazon.pl)\",\n \"Sweden (amazon.se)\",\n \"Turkey (amazon.com.tr)\",\n \"Ireland (amazon.ie)\",\n \"Belgium (amazon.com.be)\",\n \"South Africa (amazon.co.za)\",\n \"Egypt (amazon.eg)\"\n ]\n }\n },\n \"sortBy\": {\n \"title\": \"Sort Reviews By\",\n \"type\": \"string\",\n \"description\": \"Order of the returned reviews: most helpful first, or most recent first.\",\n \"editor\": \"select\",\n \"default\": \"helpful\",\n \"prefill\": \"helpful\",\n \"enum\": [\n \"helpful\",\n \"recent\"\n ],\n \"enumTitles\": [\n \"Most Helpful\",\n \"Most Recent\"\n ]\n },\n \"filterByStar\": {\n \"title\": \"Filter by Star Rating\",\n \"type\": \"string\",\n \"description\": \"Keep only reviews with this rating. `positive` keeps 4-5 stars and `critical` keeps 1-2 stars. Applied after merging, so narrow filters can legitimately return few or no rows.\",\n \"editor\": \"select\",\n \"default\": \"\",\n \"enum\": [\n \"\",\n \"1\",\n \"2\",\n \"3\",\n \"4\",\n \"5\",\n \"positive\",\n \"critical\"\n ],\n \"enumTitles\": [\n \"All Stars\",\n \"1 Star\",\n \"2 Stars\",\n \"3 Stars\",\n \"4 Stars\",\n \"5 Stars\",\n \"Positive (4-5 stars)\",\n \"Critical (1-2 stars)\"\n ]\n },\n \"verifiedPurchasesOnly\": {\n \"title\": \"Verified Purchases Only\",\n \"type\": \"boolean\",\n \"description\": \"Keep only reviews carrying Amazon's Verified Purchase badge. Applied server-side in the extended feed (and cookie mode) and client-side for product-page rows.\",\n \"default\": false,\n \"prefill\": false\n },\n \"filterKeywords\": {\n \"title\": \"Filter by Keywords\",\n \"type\": \"array\",\n \"description\": \"Keep only reviews whose title or text contains at least one of these keywords (case-insensitive). Empty = no keyword filter.\",\n \"editor\": \"stringList\",\n \"prefill\": [],\n \"default\": [],\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"reviewsNewerThan\": {\n \"title\": \"Reviews Newer Than\",\n \"type\": \"string\",\n \"description\": \"Keep only reviews dated on or after this date (YYYY-MM-DD or any ISO date). Reviews whose localized date cannot be parsed are kept. Empty = no date filter.\",\n \"editor\": \"datepicker\",\n \"default\": \"\",\n \"prefill\": \"\"\n },\n \"mediaReviewsOnly\": {\n \"title\": \"Media Reviews Only\",\n \"type\": \"boolean\",\n \"description\": \"Keep only reviews that include at least one reviewer-uploaded image or video.\",\n \"default\": false,\n \"prefill\": false\n },\n \"includeImages\": {\n \"title\": \"Include Review Images and Videos\",\n \"type\": \"boolean\",\n \"description\": \"Extract full-resolution image and video URLs uploaded by reviewers.\",\n \"default\": true,\n \"prefill\": true,\n \"sectionCaption\": \"Output options\",\n \"sectionDescription\": \"Toggle optional fields. GDPR-sensitive reviewer identity is off by default.\"\n },\n \"includeAggregates\": {\n \"title\": \"Include Rating Summary\",\n \"type\": \"boolean\",\n \"description\": \"Emit one `amazon_review_aggregate` record per product with product title, average rating, global ratings count, star histogram, derived per-star counts, and Amazon's \\\"Customers say\\\" summary with aspects. The histogram is filled from the rating-summary popover when the page omits it.\",\n \"default\": true,\n \"prefill\": true\n },\n \"includeGdprSensitive\": {\n \"title\": \"Include Reviewer Names and Profiles\",\n \"type\": \"boolean\",\n \"description\": \"Include reviewer display name, profile link, and avatar. Leave off for GDPR-sensitive workloads.\",\n \"default\": false,\n \"prefill\": false\n },\n \"cookieString\": {\n \"title\": \"Amazon Session Cookie (optional)\",\n \"type\": \"string\",\n \"description\": \"Optional. Paste your own logged-in Amazon session cookie (the literal Cookie header value) to use paginated /product-reviews/ and unlock deeper history. Never required; the actor returns real public data without it. Never paste a password.\",\n \"editor\": \"textarea\",\n \"isSecret\": true\n }\n }\n}", "readme": "# Amazon Customer Review & Rating Summary Scraper\n\nTurn Amazon product pages into a clean review dataset and a product-level rating summary — no login, no cookie, no proxy configuration. Give it product URLs or bare ASINs, or let it find products from a keyword or category page. It works across 23 Amazon storefronts, merges the public review sources, and lets you narrow the result by stars, verified purchases, keywords, date, or media.\n\n## What this actor does\n\n- **Two ways in:** paste `productUrls` (URLs or bare ASINs) or leave them empty and use `keywords` / `categoryUrls` to discover products first. Discovery runs over plain HTTP on Amazon's mobile search page and falls back to a browser only when needed.\n- **Review rows:** rating, headline, full text, date and reviewer location, verified-purchase and Vine labels, helpful votes, variant, and reviewer media — from the public product-page review block. The block is probabilistic, so the actor retries fresh sessions across the desktop and mobile product pages.\n- **Rating summary, always first:** one `amazon_review_aggregate` record per product with product title, average rating, global ratings count, the 5→1 star histogram, derived per-star counts, and Amazon's \"Customers say\" summary with aspect sentiment. When the page omits the histogram, the actor fills it from Amazon's own rating-summary popover widget.\n- **Optional depth:** `extendedHistory` merges Amazon's public extended review feed for US products (up to 100 rows per star/sort bucket; 100–800+ unique on popular ASINs), deduplicated against the product-page sample. `mergeMarketplaces` additionally unions the product page from other storefronts.\n- **Filters that narrow the data:** star rating (including positive/critical), verified purchases, keyword, date, and media-only. Sorting is most-helpful or most-recent.\n- **Empty fields are omitted.** A record only contains fields the source actually provided — never `null` or fake placeholders.\n\n## Output\n\n### Review records\n\n| Field | Description |\n|---|---|\n| `productAsin` | ASIN of the requested product. |\n| `ratingScore` | Star rating, 1–5. |\n| `reviewTitle` / `reviewDescription` | Headline and full review text. |\n| `reviewUrl` / `reviewId` | Permalink and Amazon review ID when the source exposes them (the extended feed does not). |\n| `reviewedIn` | Raw \"Reviewed in … on …\" sentence. |\n| `reviewDate` / `reviewLocation` | Parsed ISO date and reviewer country. |\n| `isVerified` / `isVineVoice` | Amazon Verified Purchase and Vine badges. |\n| `variant` | Product variant the reviewer bought, when shown. |\n| `reviewReaction` / `helpfulCount` | Raw helpful-vote sentence and parsed count. |\n| `reviewImages` / `reviewVideos` | Reviewer media (`reviewVideos` entries carry a URL and optional thumbnail). |\n| `hasImages` / `imageCount` / `hasVideos` / `videoCount` | Derived media flags. |\n| `sentimentHint` | Derived `positive` / `neutral` / `negative` from the rating. |\n| `wordCount` | Length, character-based for CJK/Hangul text. |\n| `position` | Rank in the returned set after merging and filtering. |\n| `reviewHash` | Stable content fingerprint used to deduplicate across sources. |\n| `source` | `productPage`, `extendedHistory`, or `cookieMode`. |\n| `sourceMarketplace` | Amazon domain the row came from. |\n| `reviewedProductAsin` | Variant ASIN the review belongs to, when the page exposes it. |\n| `reviewerName` / `reviewerProfile` / `reviewerAvatar` | Only present when `includeGdprSensitive` is on. |\n| `scrapedAt` / `sourceUrl` | UTC scrape timestamp and the input URL. |\n\n### Rating summary records\n\nOne record per product with `type: \"amazon_review_aggregate\"`:\n\n| Field | Description |\n|---|---|\n| `productAsin` / `productTitle` | ASIN and product title from the same page. |\n| `averageRating` / `globalRatingsCount` | Overall stars and total ratings (not just written reviews). |\n| `starsBreakdown` | Percentage per star, 5→1. |\n| `ratingCountByStar` | Derived count per star (percentage × total, rounded). |\n| `customersSay` / `customersSayAspects` | Amazon's AI summary and aspect sentiment, when Amazon shows them. |\n| `productUrl` / `sourceUrl` / `scrapedAt` | Canonical product URL, input URL, and timestamp. |\n\n### Status records\n\nIf a run cannot return any review or summary, the dataset receives one typed status record so the run is never silently empty: `amazon_reviews_blocked`, `amazon_reviews_no_star_match`, `amazon_reviews_no_products_discovered`, `amazon_reviews_cookie_invalid`, `amazon_reviews_cookie_expired`, or `amazon_reviews_cookie_robot_blocked`. A blocked page is also reported in the run status message.\n\n## Input\n\n| Field | Type | Default | Description |\n|---|---|---|---|\n| `productUrls` | array | – | Amazon URLs or bare ASINs. Leave empty to use discovery. |\n| `keywords` | array | `[]` | Search terms for product discovery. |\n| `categoryUrls` | array | `[]` | Amazon search/category URLs for advanced discovery. |\n| `maxProductsToDiscover` | integer | `5` | Products per keyword/category URL (1–50). |\n| `country` | string | `amazon.com` | Storefront for bare ASINs, discovery, and URLs without a domain (23 options). |\n| `maxReviews` | integer | `100` | Per-product cap after merging (1–2000). |\n| `extendedHistory` | boolean | `true` | Merge the public extended review feed. |\n| `mergeMarketplaces` | array | `[]` | Extra storefronts whose product pages are unioned. |\n| `sortBy` | string | `helpful` | `helpful` or `recent`. |\n| `filterByStar` | string | `\"\"` (all) | `1`–`5`, `positive` (4–5), or `critical` (1–2). |\n| `verifiedPurchasesOnly` | boolean | `false` | Keep only Verified Purchase reviews. |\n| `filterKeywords` | array | `[]` | Keep reviews containing any of these keywords. |\n| `reviewsNewerThan` | string | `\"\"` (none) | Keep reviews on/after this date. |\n| `mediaReviewsOnly` | boolean | `false` | Keep only reviews with images or videos. |\n| `includeImages` | boolean | `true` | Extract reviewer images and videos. |\n| `includeAggregates` | boolean | `true` | Emit the product rating-summary record. |\n| `includeGdprSensitive` | boolean | `false` | Include reviewer name/profile/avatar. |\n| `cookieString` | string | `\"\"` (off) | Optional own session cookie for paginated history. Never required. |\n\n### Examples\n\nDefault run — one product, summary plus reviews:\n\n```json\n{ \"productUrls\": [\"https://www.amazon.com/dp/B09X7MPX8L\"] }\n```\n\nDiscovery by keyword:\n\n```json\n{ \"keywords\": [\"wireless earbuds\"], \"maxProductsToDiscover\": 5, \"maxReviews\": 50 }\n```\n\nCritical reviews with media on two products:\n\n```json\n{\n \"productUrls\": [\"B09X7MPX8L\", \"B08TJTCCV8\"],\n \"filterByStar\": \"critical\",\n \"mediaReviewsOnly\": true,\n \"verifiedPurchasesOnly\": true,\n \"maxReviews\": 100\n}\n```\n\nMerge two storefronts:\n\n```json\n{\n \"productUrls\": [\"https://www.amazon.de/dp/B09X7MPX8L\"],\n \"country\": \"amazon.de\",\n \"mergeMarketplaces\": [\"amazon.co.uk\", \"amazon.fr\"],\n \"maxReviews\": 200\n}\n```\n\n## Use cases\n\n- **Voice of customer:** export review text for sentiment, topic, and complaint analysis.\n- **Rating monitoring:** track average rating, histogram, and the \"Customers say\" summary across a watch-list.\n- **Competitive research:** compare products from a keyword or category with one run.\n- **Storefront comparison:** see which reviews a product carries on other Amazon marketplaces.\n- **Quality triage:** filter to critical or media reviews to find recurring defects quickly.\n\n## FAQ\n\n**Do I need an Amazon account or a proxy?**\nNo. The actor works with public product data and chooses its own connection automatically. `cookieString` is optional and only for users who want to paginate their own session.\n\n**How many reviews can I get per product?**\nThe product-page block normally shows 8–13. With `extendedHistory` on, popular US products can yield several hundred unique reviews (measured 620, 824; up to 100 per star/sort bucket). Coverage varies by ASIN.\n\n**Why do some products return fewer rows than others?**\nAmazon gates the product-page block probabilistically and the extended feed only covers a subset of ASINs. The actor retries and reports what it actually collected; it never invents rows.\n\n**Why is my star filter returning zero results?**\nFilters run over the merged set, so a rating that is rare on the product page and absent from the feed can legitimately return nothing. The dataset then contains an `amazon_reviews_no_star_match` status record.\n\n**Is the star histogram always available?**\nYes in practice: the actor reads it from the product page and falls back to Amazon's rating-summary popover when the page omits it. `customersSay` is source-dependent and appears only when Amazon displays it.\n\n**What is `ratingCountByStar`?**\nA derived count: Amazon publishes percentages, so the actor multiplies each percentage by `globalRatingsCount` and rounds. It is labelled as derived, not read from a separate count field.\n\n**Does this actor cover non-US marketplaces?**\nYes — 23 storefronts for product-page collection and marketplace merge. The extended review feed is US-only.\n\n**Is this affiliated with Amazon?**\nNo. It reads publicly available pages and is not endorsed by Amazon.\n", "actorDefinition": { "actorSpecification": 1, "name": "amazon-customer-review-and-rating-summary-scraper", "title": "Amazon Customer Review & Rating Summary Scraper", "description": "Get Amazon customer reviews plus a product-level rating summary by URL, ASIN, keyword, or category, with extended history, marketplace merge, and star/verified/keyword/date filters.", "version": "1.0", "buildTag": "latest", "meta": { "templateId": "python-playwright" }, "input": { "title": "Amazon Customer Review & Rating Summary Scraper Input", "description": "Collect Amazon customer reviews plus each product's rating summary with no login or proxy setup. Add product URLs/ASINs or discover products by keyword; reviews are merged and deduplicated, with optional extended history and filters.", "type": "object", "schemaVersion": 1, "properties": { "productUrls": { "title": "Product URLs or ASINs", "type": "array", "description": "Amazon product URLs (/dp/, /gp/product/, /gp/aw/d/, /product/) or bare 10-character ASINs, on any supported Amazon domain. Leave empty to discover products from `keywords`/`categoryUrls` instead.", "editor": "stringList", "prefill": [ "https://www.amazon.com/dp/B09X7MPX8L" ], "items": { "type": "string" }, "sectionCaption": "Products", "sectionDescription": "Scrape these products, or leave empty and discover products by keyword or category." }, "keywords": { "title": "Keywords (discover products)", "type": "array", "description": "Search terms used to discover products when `productUrls` is empty (e.g. \"wireless earbuds\"). Each keyword contributes up to `maxProductsToDiscover` products.", "editor": "stringList", "prefill": [], "default": [], "items": { "type": "string" } }, "categoryUrls": { "title": "Category or Search URLs (discover products)", "type": "array", "description": "Advanced discovery: Amazon `/s?...` search URLs or `/b?node=...` category URLs. Used only when `productUrls` is empty.", "editor": "stringList", "prefill": [], "default": [], "items": { "type": "string" } }, "maxProductsToDiscover": { "title": "Max Products to Discover", "type": "integer", "description": "Maximum products discovered from each keyword or category URL (1-50). Ignored when `productUrls` is supplied.", "editor": "number", "default": 5, "prefill": 5, "minimum": 1, "maximum": 50 }, "country": { "title": "Amazon Marketplace", "type": "string", "description": "Amazon storefront to use for bare ASINs, discovery, and products whose URL does not carry a domain. Product URLs keep their own domain.", "editor": "select", "default": "amazon.com", "prefill": "amazon.com", "enum": [ "amazon.com", "amazon.co.uk", "amazon.de", "amazon.fr", "amazon.it", "amazon.es", "amazon.ca", "amazon.com.au", "amazon.co.jp", "amazon.in", "amazon.com.br", "amazon.com.mx", "amazon.nl", "amazon.sg", "amazon.ae", "amazon.sa", "amazon.pl", "amazon.se", "amazon.com.tr", "amazon.ie", "amazon.com.be", "amazon.co.za", "amazon.eg" ], "enumTitles": [ "United States (amazon.com)", "United Kingdom (amazon.co.uk)", "Germany (amazon.de)", "France (amazon.fr)", "Italy (amazon.it)", "Spain (amazon.es)", "Canada (amazon.ca)", "Australia (amazon.com.au)", "Japan (amazon.co.jp)", "India (amazon.in)", "Brazil (amazon.com.br)", "Mexico (amazon.com.mx)", "Netherlands (amazon.nl)", "Singapore (amazon.sg)", "United Arab Emirates (amazon.ae)", "Saudi Arabia (amazon.sa)", "Poland (amazon.pl)", "Sweden (amazon.se)", "Turkey (amazon.com.tr)", "Ireland (amazon.ie)", "Belgium (amazon.com.be)", "South Africa (amazon.co.za)", "Egypt (amazon.eg)" ] }, "maxReviews": { "title": "Max Reviews per Product", "type": "integer", "description": "Hard cap per product after merging and deduplication (1-2000). The product-page sample alone yields about 8-13 rows; the optional extended feed can add 100-800+ for popular US products. In optional cookie mode this is the paginated cap.", "editor": "number", "default": 100, "prefill": 15, "minimum": 1, "maximum": 2000, "sectionCaption": "Review collection", "sectionDescription": "Control review depth and which public sources are merged." }, "extendedHistory": { "title": "Extended Review History", "type": "boolean", "description": "Merge Amazon's public extended review feed for each ASIN (no login): up to 100 rows per star/sort bucket, typically 100-800+ unique reviews for popular US products, deduplicated against the product-page sample. Coverage varies by ASIN and the feed carries Amazon.com reviews only.", "default": true, "prefill": true }, "mergeMarketplaces": { "title": "Merge Extra Marketplaces", "type": "array", "description": "Fetch the same product on these additional Amazon marketplaces and merge their deduplicated product-page reviews. Empty = the product's own marketplace only.", "editor": "select", "prefill": [], "default": [], "items": { "type": "string", "enum": [ "amazon.com", "amazon.co.uk", "amazon.de", "amazon.fr", "amazon.it", "amazon.es", "amazon.ca", "amazon.com.au", "amazon.co.jp", "amazon.in", "amazon.com.br", "amazon.com.mx", "amazon.nl", "amazon.sg", "amazon.ae", "amazon.sa", "amazon.pl", "amazon.se", "amazon.com.tr", "amazon.ie", "amazon.com.be", "amazon.co.za", "amazon.eg" ], "enumTitles": [ "United States (amazon.com)", "United Kingdom (amazon.co.uk)", "Germany (amazon.de)", "France (amazon.fr)", "Italy (amazon.it)", "Spain (amazon.es)", "Canada (amazon.ca)", "Australia (amazon.com.au)", "Japan (amazon.co.jp)", "India (amazon.in)", "Brazil (amazon.com.br)", "Mexico (amazon.com.mx)", "Netherlands (amazon.nl)", "Singapore (amazon.sg)", "United Arab Emirates (amazon.ae)", "Saudi Arabia (amazon.sa)", "Poland (amazon.pl)", "Sweden (amazon.se)", "Turkey (amazon.com.tr)", "Ireland (amazon.ie)", "Belgium (amazon.com.be)", "South Africa (amazon.co.za)", "Egypt (amazon.eg)" ] } }, "sortBy": { "title": "Sort Reviews By", "type": "string", "description": "Order of the returned reviews: most helpful first, or most recent first.", "editor": "select", "default": "helpful", "prefill": "helpful", "enum": [ "helpful", "recent" ], "enumTitles": [ "Most Helpful", "Most Recent" ] }, "filterByStar": { "title": "Filter by Star Rating", "type": "string", "description": "Keep only reviews with this rating. `positive` keeps 4-5 stars and `critical` keeps 1-2 stars. Applied after merging, so narrow filters can legitimately return few or no rows.", "editor": "select", "default": "", "enum": [ "", "1", "2", "3", "4", "5", "positive", "critical" ], "enumTitles": [ "All Stars", "1 Star", "2 Stars", "3 Stars", "4 Stars", "5 Stars", "Positive (4-5 stars)", "Critical (1-2 stars)" ] }, "verifiedPurchasesOnly": { "title": "Verified Purchases Only", "type": "boolean", "description": "Keep only reviews carrying Amazon's Verified Purchase badge. Applied server-side in the extended feed (and cookie mode) and client-side for product-page rows.", "default": false, "prefill": false }, "filterKeywords": { "title": "Filter by Keywords", "type": "array", "description": "Keep only reviews whose title or text contains at least one of these keywords (case-insensitive). Empty = no keyword filter.", "editor": "stringList", "prefill": [], "default": [], "items": { "type": "string" } }, "reviewsNewerThan": { "title": "Reviews Newer Than", "type": "string", "description": "Keep only reviews dated on or after this date (YYYY-MM-DD or any ISO date). Reviews whose localized date cannot be parsed are kept. Empty = no date filter.", "editor": "datepicker", "default": "", "prefill": "" }, "mediaReviewsOnly": { "title": "Media Reviews Only", "type": "boolean", "description": "Keep only reviews that include at least one reviewer-uploaded image or video.", "default": false, "prefill": false }, "includeImages": { "title": "Include Review Images and Videos", "type": "boolean", "description": "Extract full-resolution image and video URLs uploaded by reviewers.", "default": true, "prefill": true, "sectionCaption": "Output options", "sectionDescription": "Toggle optional fields. GDPR-sensitive reviewer identity is off by default." }, "includeAggregates": { "title": "Include Rating Summary", "type": "boolean", "description": "Emit one `amazon_review_aggregate` record per product with product title, average rating, global ratings count, star histogram, derived per-star counts, and Amazon's \"Customers say\" summary with aspects. The histogram is filled from the rating-summary popover when the page omits it.", "default": true, "prefill": true }, "includeGdprSensitive": { "title": "Include Reviewer Names and Profiles", "type": "boolean", "description": "Include reviewer display name, profile link, and avatar. Leave off for GDPR-sensitive workloads.", "default": false, "prefill": false }, "cookieString": { "title": "Amazon Session Cookie (optional)", "type": "string", "description": "Optional. Paste your own logged-in Amazon session cookie (the literal Cookie header value) to use paginated /product-reviews/ and unlock deeper history. Never required; the actor returns real public data without it. Never paste a password.", "editor": "textarea", "isSecret": true } } }, "output": { "actorOutputSchemaVersion": 1, "title": "Amazon Customer Review & Rating Summary Scraper Output", "description": "One record per Amazon customer review (rating, text, verified/Vine flags, helpful votes, variant, media, dates, source metadata) plus one type=amazon_review_aggregate record per product with the rating summary and star histogram. Empty fields are omitted, never pushed as null.", "properties": { "reviews": { "type": "string", "title": "Amazon reviews", "description": "Dataset containing all scraped Amazon customer reviews.", "template": "{{links.apiDefaultDatasetUrl}}/items" } } }, "dockerfile": "../Dockerfile", "readme": "# Amazon Customer Review & Rating Summary Scraper\n\nTurn Amazon product pages into a clean review dataset and a product-level rating summary — no login, no cookie, no proxy configuration. Give it product URLs or bare ASINs, or let it find products from a keyword or category page. It works across 23 Amazon storefronts, merges the public review sources, and lets you narrow the result by stars, verified purchases, keywords, date, or media.\n\n## What this actor does\n\n- **Two ways in:** paste `productUrls` (URLs or bare ASINs) or leave them empty and use `keywords` / `categoryUrls` to discover products first. Discovery runs over plain HTTP on Amazon's mobile search page and falls back to a browser only when needed.\n- **Review rows:** rating, headline, full text, date and reviewer location, verified-purchase and Vine labels, helpful votes, variant, and reviewer media — from the public product-page review block. The block is probabilistic, so the actor retries fresh sessions across the desktop and mobile product pages.\n- **Rating summary, always first:** one `amazon_review_aggregate` record per product with product title, average rating, global ratings count, the 5→1 star histogram, derived per-star counts, and Amazon's \"Customers say\" summary with aspect sentiment. When the page omits the histogram, the actor fills it from Amazon's own rating-summary popover widget.\n- **Optional depth:** `extendedHistory` merges Amazon's public extended review feed for US products (up to 100 rows per star/sort bucket; 100–800+ unique on popular ASINs), deduplicated against the product-page sample. `mergeMarketplaces` additionally unions the product page from other storefronts.\n- **Filters that narrow the data:** star rating (including positive/critical), verified purchases, keyword, date, and media-only. Sorting is most-helpful or most-recent.\n- **Empty fields are omitted.** A record only contains fields the source actually provided — never `null` or fake placeholders.\n\n## Output\n\n### Review records\n\n| Field | Description |\n|---|---|\n| `productAsin` | ASIN of the requested product. |\n| `ratingScore` | Star rating, 1–5. |\n| `reviewTitle` / `reviewDescription` | Headline and full review text. |\n| `reviewUrl` / `reviewId` | Permalink and Amazon review ID when the source exposes them (the extended feed does not). |\n| `reviewedIn` | Raw \"Reviewed in … on …\" sentence. |\n| `reviewDate` / `reviewLocation` | Parsed ISO date and reviewer country. |\n| `isVerified` / `isVineVoice` | Amazon Verified Purchase and Vine badges. |\n| `variant` | Product variant the reviewer bought, when shown. |\n| `reviewReaction` / `helpfulCount` | Raw helpful-vote sentence and parsed count. |\n| `reviewImages` / `reviewVideos` | Reviewer media (`reviewVideos` entries carry a URL and optional thumbnail). |\n| `hasImages` / `imageCount` / `hasVideos` / `videoCount` | Derived media flags. |\n| `sentimentHint` | Derived `positive` / `neutral` / `negative` from the rating. |\n| `wordCount` | Length, character-based for CJK/Hangul text. |\n| `position` | Rank in the returned set after merging and filtering. |\n| `reviewHash` | Stable content fingerprint used to deduplicate across sources. |\n| `source` | `productPage`, `extendedHistory`, or `cookieMode`. |\n| `sourceMarketplace` | Amazon domain the row came from. |\n| `reviewedProductAsin` | Variant ASIN the review belongs to, when the page exposes it. |\n| `reviewerName` / `reviewerProfile` / `reviewerAvatar` | Only present when `includeGdprSensitive` is on. |\n| `scrapedAt` / `sourceUrl` | UTC scrape timestamp and the input URL. |\n\n### Rating summary records\n\nOne record per product with `type: \"amazon_review_aggregate\"`:\n\n| Field | Description |\n|---|---|\n| `productAsin` / `productTitle` | ASIN and product title from the same page. |\n| `averageRating` / `globalRatingsCount` | Overall stars and total ratings (not just written reviews). |\n| `starsBreakdown` | Percentage per star, 5→1. |\n| `ratingCountByStar` | Derived count per star (percentage × total, rounded). |\n| `customersSay` / `customersSayAspects` | Amazon's AI summary and aspect sentiment, when Amazon shows them. |\n| `productUrl` / `sourceUrl` / `scrapedAt` | Canonical product URL, input URL, and timestamp. |\n\n### Status records\n\nIf a run cannot return any review or summary, the dataset receives one typed status record so the run is never silently empty: `amazon_reviews_blocked`, `amazon_reviews_no_star_match`, `amazon_reviews_no_products_discovered`, `amazon_reviews_cookie_invalid`, `amazon_reviews_cookie_expired`, or `amazon_reviews_cookie_robot_blocked`. A blocked page is also reported in the run status message.\n\n## Input\n\n| Field | Type | Default | Description |\n|---|---|---|---|\n| `productUrls` | array | – | Amazon URLs or bare ASINs. Leave empty to use discovery. |\n| `keywords` | array | `[]` | Search terms for product discovery. |\n| `categoryUrls` | array | `[]` | Amazon search/category URLs for advanced discovery. |\n| `maxProductsToDiscover` | integer | `5` | Products per keyword/category URL (1–50). |\n| `country` | string | `amazon.com` | Storefront for bare ASINs, discovery, and URLs without a domain (23 options). |\n| `maxReviews` | integer | `100` | Per-product cap after merging (1–2000). |\n| `extendedHistory` | boolean | `true` | Merge the public extended review feed. |\n| `mergeMarketplaces` | array | `[]` | Extra storefronts whose product pages are unioned. |\n| `sortBy` | string | `helpful` | `helpful` or `recent`. |\n| `filterByStar` | string | `\"\"` (all) | `1`–`5`, `positive` (4–5), or `critical` (1–2). |\n| `verifiedPurchasesOnly` | boolean | `false` | Keep only Verified Purchase reviews. |\n| `filterKeywords` | array | `[]` | Keep reviews containing any of these keywords. |\n| `reviewsNewerThan` | string | `\"\"` (none) | Keep reviews on/after this date. |\n| `mediaReviewsOnly` | boolean | `false` | Keep only reviews with images or videos. |\n| `includeImages` | boolean | `true` | Extract reviewer images and videos. |\n| `includeAggregates` | boolean | `true` | Emit the product rating-summary record. |\n| `includeGdprSensitive` | boolean | `false` | Include reviewer name/profile/avatar. |\n| `cookieString` | string | `\"\"` (off) | Optional own session cookie for paginated history. Never required. |\n\n### Examples\n\nDefault run — one product, summary plus reviews:\n\n```json\n{ \"productUrls\": [\"https://www.amazon.com/dp/B09X7MPX8L\"] }\n```\n\nDiscovery by keyword:\n\n```json\n{ \"keywords\": [\"wireless earbuds\"], \"maxProductsToDiscover\": 5, \"maxReviews\": 50 }\n```\n\nCritical reviews with media on two products:\n\n```json\n{\n \"productUrls\": [\"B09X7MPX8L\", \"B08TJTCCV8\"],\n \"filterByStar\": \"critical\",\n \"mediaReviewsOnly\": true,\n \"verifiedPurchasesOnly\": true,\n \"maxReviews\": 100\n}\n```\n\nMerge two storefronts:\n\n```json\n{\n \"productUrls\": [\"https://www.amazon.de/dp/B09X7MPX8L\"],\n \"country\": \"amazon.de\",\n \"mergeMarketplaces\": [\"amazon.co.uk\", \"amazon.fr\"],\n \"maxReviews\": 200\n}\n```\n\n## Use cases\n\n- **Voice of customer:** export review text for sentiment, topic, and complaint analysis.\n- **Rating monitoring:** track average rating, histogram, and the \"Customers say\" summary across a watch-list.\n- **Competitive research:** compare products from a keyword or category with one run.\n- **Storefront comparison:** see which reviews a product carries on other Amazon marketplaces.\n- **Quality triage:** filter to critical or media reviews to find recurring defects quickly.\n\n## FAQ\n\n**Do I need an Amazon account or a proxy?**\nNo. The actor works with public product data and chooses its own connection automatically. `cookieString` is optional and only for users who want to paginate their own session.\n\n**How many reviews can I get per product?**\nThe product-page block normally shows 8–13. With `extendedHistory` on, popular US products can yield several hundred unique reviews (measured 620, 824; up to 100 per star/sort bucket). Coverage varies by ASIN.\n\n**Why do some products return fewer rows than others?**\nAmazon gates the product-page block probabilistically and the extended feed only covers a subset of ASINs. The actor retries and reports what it actually collected; it never invents rows.\n\n**Why is my star filter returning zero results?**\nFilters run over the merged set, so a rating that is rare on the product page and absent from the feed can legitimately return nothing. The dataset then contains an `amazon_reviews_no_star_match` status record.\n\n**Is the star histogram always available?**\nYes in practice: the actor reads it from the product page and falls back to Amazon's rating-summary popover when the page omits it. `customersSay` is source-dependent and appears only when Amazon displays it.\n\n**What is `ratingCountByStar`?**\nA derived count: Amazon publishes percentages, so the actor multiplies each percentage by `globalRatingsCount` and rounds. It is labelled as derived, not read from a separate count field.\n\n**Does this actor cover non-US marketplaces?**\nYes — 23 storefronts for product-page collection and marketplace merge. The extended review feed is US-only.\n\n**Is this affiliated with Amazon?**\nNo. It reads publicly available pages and is not endorsed by Amazon.\n", "categories": [ "ECOMMERCE", "PRODUCTS" ], "defaultRunOptions": { "build": "latest", "memoryMbytes": 2048, "timeoutSecs": 3600 }, "storages": { "dataset": { "actorSpecification": 1, "title": "Amazon Reviews", "views": { "reviews": { "title": "Reviews", "transformation": { "fields": [ "productAsin", "ratingScore", "reviewTitle", "reviewDescription", "isVerified", "reviewedIn", "reviewReaction", "variant", "reviewImages", "position", "reviewId", "helpfulCount", "reviewDate", "reviewLocation", "sentimentHint", "wordCount", "hasImages", "imageCount", "scrapedAt", "sourceUrl", "reviewUrl", "isVineVoice", "reviewVideos", "hasVideos", "reviewHash", "source", "sourceMarketplace", "reviewedProductAsin" ] }, "display": { "component": "table", "properties": { "productAsin": { "label": "ASIN", "format": "text" }, "ratingScore": { "label": "Rating", "format": "number" }, "reviewTitle": { "label": "Title", "format": "text" }, "isVerified": { "label": "Verified", "format": "boolean" }, "reviewId": { "label": "Review ID", "format": "text" }, "helpfulCount": { "label": "Helpful", "format": "number" }, "reviewDate": { "label": "Date", "format": "text" }, "reviewLocation": { "label": "Location", "format": "text" }, "sentimentHint": { "label": "Sentiment", "format": "text" }, "wordCount": { "label": "Words", "format": "number" }, "hasImages": { "label": "Has Images", "format": "boolean" }, "reviewHash": { "label": "Review Hash", "format": "text" }, "source": { "label": "Source", "format": "text" }, "sourceMarketplace": { "label": "Marketplace", "format": "text" }, "reviewUrl": { "label": "Review URL", "format": "text" }, "isVineVoice": { "label": "Vine", "format": "boolean" } } } } } } } }, "buildNumber": "1.0.3", "imageDigest": "86d5f2260c7c63817ffe61689c3b5ef6ebdc5f8990dbad286cddc857119e9c53", "actVersion": { "sourceType": "TARBALL", "buildTag": "latest", "versionNumber": "1.0" }, "usage": { "ACTOR_COMPUTE_UNITS": 0.03976111111111111 } } }