# Amazon Customer Review & Rating Summary Scraper (`vexaloom-labs/amazon-customer-review-and-rating-summary-scraper`) Actor

Get Amazon customer reviews and a product-level rating summary by product URL, keyword, or category, with star-rating and sort filters, across 23 Amazon domains.

- **URL**: https://apify.com/vexaloom-labs/amazon-customer-review-and-rating-summary-scraper.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (community)
- **Categories:** E-commerce, Automation, Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Amazon Customer Review & Rating Summary Scraper

Turn 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.

### What this actor does

- **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.
- **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.
- **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.
- **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.
- **Filters that narrow the data:** star rating (including positive/critical), verified purchases, keyword, date, and media-only. Sorting is most-helpful or most-recent.
- **Empty fields are omitted.** A record only contains fields the source actually provided — never `null` or fake placeholders.

### Output

#### Review records

| Field | Description |
|---|---|
| `productAsin` | ASIN of the requested product. |
| `ratingScore` | Star rating, 1–5. |
| `reviewTitle` / `reviewDescription` | Headline and full review text. |
| `reviewUrl` / `reviewId` | Permalink and Amazon review ID when the source exposes them (the extended feed does not). |
| `reviewedIn` | Raw "Reviewed in … on …" sentence. |
| `reviewDate` / `reviewLocation` | Parsed ISO date and reviewer country. |
| `isVerified` / `isVineVoice` | Amazon Verified Purchase and Vine badges. |
| `variant` | Product variant the reviewer bought, when shown. |
| `reviewReaction` / `helpfulCount` | Raw helpful-vote sentence and parsed count. |
| `reviewImages` / `reviewVideos` | Reviewer media (`reviewVideos` entries carry a URL and optional thumbnail). |
| `hasImages` / `imageCount` / `hasVideos` / `videoCount` | Derived media flags. |
| `sentimentHint` | Derived `positive` / `neutral` / `negative` from the rating. |
| `wordCount` | Length, character-based for CJK/Hangul text. |
| `position` | Rank in the returned set after merging and filtering. |
| `reviewHash` | Stable content fingerprint used to deduplicate across sources. |
| `source` | `productPage`, `extendedHistory`, or `cookieMode`. |
| `sourceMarketplace` | Amazon domain the row came from. |
| `reviewedProductAsin` | Variant ASIN the review belongs to, when the page exposes it. |
| `reviewerName` / `reviewerProfile` / `reviewerAvatar` | Only present when `includeGdprSensitive` is on. |
| `scrapedAt` / `sourceUrl` | UTC scrape timestamp and the input URL. |

#### Rating summary records

One record per product with `type: "amazon_review_aggregate"`:

| Field | Description |
|---|---|
| `productAsin` / `productTitle` | ASIN and product title from the same page. |
| `averageRating` / `globalRatingsCount` | Overall stars and total ratings (not just written reviews). |
| `starsBreakdown` | Percentage per star, 5→1. |
| `ratingCountByStar` | Derived count per star (percentage × total, rounded). |
| `customersSay` / `customersSayAspects` | Amazon's AI summary and aspect sentiment, when Amazon shows them. |
| `productUrl` / `sourceUrl` / `scrapedAt` | Canonical product URL, input URL, and timestamp. |

#### Status records

If 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.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `productUrls` | array | – | Amazon URLs or bare ASINs. Leave empty to use discovery. |
| `keywords` | array | `[]` | Search terms for product discovery. |
| `categoryUrls` | array | `[]` | Amazon search/category URLs for advanced discovery. |
| `maxProductsToDiscover` | integer | `5` | Products per keyword/category URL (1–50). |
| `country` | string | `amazon.com` | Storefront for bare ASINs, discovery, and URLs without a domain (23 options). |
| `maxReviews` | integer | `100` | Per-product cap after merging (1–2000). |
| `extendedHistory` | boolean | `true` | Merge the public extended review feed. |
| `mergeMarketplaces` | array | `[]` | Extra storefronts whose product pages are unioned. |
| `sortBy` | string | `helpful` | `helpful` or `recent`. |
| `filterByStar` | string | `""` (all) | `1`–`5`, `positive` (4–5), or `critical` (1–2). |
| `verifiedPurchasesOnly` | boolean | `false` | Keep only Verified Purchase reviews. |
| `filterKeywords` | array | `[]` | Keep reviews containing any of these keywords. |
| `reviewsNewerThan` | string | `""` (none) | Keep reviews on/after this date. |
| `mediaReviewsOnly` | boolean | `false` | Keep only reviews with images or videos. |
| `includeImages` | boolean | `true` | Extract reviewer images and videos. |
| `includeAggregates` | boolean | `true` | Emit the product rating-summary record. |
| `includeGdprSensitive` | boolean | `false` | Include reviewer name/profile/avatar. |
| `cookieString` | string | `""` (off) | Optional own session cookie for paginated history. Never required. |

#### Examples

Default run — one product, summary plus reviews:

```json
{ "productUrls": ["https://www.amazon.com/dp/B09X7MPX8L"] }
```

Discovery by keyword:

```json
{ "keywords": ["wireless earbuds"], "maxProductsToDiscover": 5, "maxReviews": 50 }
```

Critical reviews with media on two products:

```json
{
  "productUrls": ["B09X7MPX8L", "B08TJTCCV8"],
  "filterByStar": "critical",
  "mediaReviewsOnly": true,
  "verifiedPurchasesOnly": true,
  "maxReviews": 100
}
```

Merge two storefronts:

```json
{
  "productUrls": ["https://www.amazon.de/dp/B09X7MPX8L"],
  "country": "amazon.de",
  "mergeMarketplaces": ["amazon.co.uk", "amazon.fr"],
  "maxReviews": 200
}
```

### Use cases

- **Voice of customer:** export review text for sentiment, topic, and complaint analysis.
- **Rating monitoring:** track average rating, histogram, and the "Customers say" summary across a watch-list.
- **Competitive research:** compare products from a keyword or category with one run.
- **Storefront comparison:** see which reviews a product carries on other Amazon marketplaces.
- **Quality triage:** filter to critical or media reviews to find recurring defects quickly.

### FAQ

**Do I need an Amazon account or a proxy?**
No. 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.

**How many reviews can I get per product?**
The 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.

**Why do some products return fewer rows than others?**
Amazon 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.

**Why is my star filter returning zero results?**
Filters 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.

**Is the star histogram always available?**
Yes 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.

**What is `ratingCountByStar`?**
A 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.

**Does this actor cover non-US marketplaces?**
Yes — 23 storefronts for product-page collection and marketplace merge. The extended review feed is US-only.

**Is this affiliated with Amazon?**
No. It reads publicly available pages and is not endorsed by Amazon.

# Actor input Schema

## `productUrls` (type: `array`):

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.

## `keywords` (type: `array`):

Search terms used to discover products when `productUrls` is empty (e.g. "wireless earbuds"). Each keyword contributes up to `maxProductsToDiscover` products.

## `categoryUrls` (type: `array`):

Advanced discovery: Amazon `/s?...` search URLs or `/b?node=...` category URLs. Used only when `productUrls` is empty.

## `maxProductsToDiscover` (type: `integer`):

Maximum products discovered from each keyword or category URL (1-50). Ignored when `productUrls` is supplied.

## `country` (type: `string`):

Amazon storefront to use for bare ASINs, discovery, and products whose URL does not carry a domain. Product URLs keep their own domain.

## `maxReviews` (type: `integer`):

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.

## `extendedHistory` (type: `boolean`):

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.

## `mergeMarketplaces` (type: `array`):

Fetch the same product on these additional Amazon marketplaces and merge their deduplicated product-page reviews. Empty = the product's own marketplace only.

## `sortBy` (type: `string`):

Order of the returned reviews: most helpful first, or most recent first.

## `filterByStar` (type: `string`):

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.

## `verifiedPurchasesOnly` (type: `boolean`):

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.

## `filterKeywords` (type: `array`):

Keep only reviews whose title or text contains at least one of these keywords (case-insensitive). Empty = no keyword filter.

## `reviewsNewerThan` (type: `string`):

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.

## `mediaReviewsOnly` (type: `boolean`):

Keep only reviews that include at least one reviewer-uploaded image or video.

## `includeImages` (type: `boolean`):

Extract full-resolution image and video URLs uploaded by reviewers.

## `includeAggregates` (type: `boolean`):

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.

## `includeGdprSensitive` (type: `boolean`):

Include reviewer display name, profile link, and avatar. Leave off for GDPR-sensitive workloads.

## `cookieString` (type: `string`):

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.

## Actor input object example

```json
{
  "productUrls": [
    "https://www.amazon.com/dp/B09X7MPX8L"
  ],
  "keywords": [],
  "categoryUrls": [],
  "maxProductsToDiscover": 5,
  "country": "amazon.com",
  "maxReviews": 15,
  "extendedHistory": true,
  "mergeMarketplaces": [],
  "sortBy": "helpful",
  "filterByStar": "",
  "verifiedPurchasesOnly": false,
  "filterKeywords": [],
  "reviewsNewerThan": "",
  "mediaReviewsOnly": false,
  "includeImages": true,
  "includeAggregates": true,
  "includeGdprSensitive": false
}
```

# Actor output Schema

## `reviews` (type: `string`):

Dataset containing all scraped Amazon customer reviews.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "productUrls": [
        "https://www.amazon.com/dp/B09X7MPX8L"
    ],
    "keywords": [],
    "categoryUrls": [],
    "maxProductsToDiscover": 5,
    "country": "amazon.com",
    "maxReviews": 15,
    "extendedHistory": true,
    "mergeMarketplaces": [],
    "sortBy": "helpful",
    "verifiedPurchasesOnly": false,
    "filterKeywords": [],
    "reviewsNewerThan": "",
    "mediaReviewsOnly": false,
    "includeImages": true,
    "includeAggregates": true,
    "includeGdprSensitive": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("vexaloom-labs/amazon-customer-review-and-rating-summary-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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "productUrls": ["https://www.amazon.com/dp/B09X7MPX8L"],
    "keywords": [],
    "categoryUrls": [],
    "maxProductsToDiscover": 5,
    "country": "amazon.com",
    "maxReviews": 15,
    "extendedHistory": True,
    "mergeMarketplaces": [],
    "sortBy": "helpful",
    "verifiedPurchasesOnly": False,
    "filterKeywords": [],
    "reviewsNewerThan": "",
    "mediaReviewsOnly": False,
    "includeImages": True,
    "includeAggregates": True,
    "includeGdprSensitive": False,
}

# Run the Actor and wait for it to finish
run = client.actor("vexaloom-labs/amazon-customer-review-and-rating-summary-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "productUrls": [
    "https://www.amazon.com/dp/B09X7MPX8L"
  ],
  "keywords": [],
  "categoryUrls": [],
  "maxProductsToDiscover": 5,
  "country": "amazon.com",
  "maxReviews": 15,
  "extendedHistory": true,
  "mergeMarketplaces": [],
  "sortBy": "helpful",
  "verifiedPurchasesOnly": false,
  "filterKeywords": [],
  "reviewsNewerThan": "",
  "mediaReviewsOnly": false,
  "includeImages": true,
  "includeAggregates": true,
  "includeGdprSensitive": false
}' |
apify call vexaloom-labs/amazon-customer-review-and-rating-summary-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/amazon-customer-review-and-rating-summary-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/1u5Fn40qo93nWNJ8t/builds/Uz8bhFkvsoBLw91SC/openapi.json