# Amazon Review Insights & Sentiment (`apt_marble/amazon-review-insights`) Actor

One row per Amazon product instead of one per review: the full star breakdown, the share of critical ratings, and the themes customers keep raising — each with how many said it and how it split between praise and complaint. Find what to fix, or what a rival's buyers grumble about.

- **URL**: https://apify.com/apt\_marble/amazon-review-insights.md
- **Developed by:** [Hamza](https://apify.com/apt_marble) (community)
- **Categories:** E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.50 / 1,000 product analyseds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## Amazon Review Insights & Sentiment

Turn a list of Amazon products into a list of answers about what customers
actually think. One row per product — not one row per review — carrying the full
star breakdown, the share of ratings that are critical, and the themes buyers
keep raising, each with how many customers mentioned it and how that split
between praise and complaint. Give it your own catalogue to find out what to fix,
or a competitor's to find out what their customers keep grumbling about.

### What you can do with it

- **See what customers praise and complain about**, ranked by how many of them
  said it, instead of reading a hundred reviews yourself.
- **Find a competitor's weak spot** — the theme with the most complaints is
  usually the feature to beat them on.
- **Screen a product before you source it** by looking at the share of critical
  ratings rather than the headline star average.
- **Prioritise a fix** using the number of customers who raised each issue, so
  the biggest complaint gets worked on first.
- **Compare a shortlist side by side** — every product returns the same columns,
  so a hundred candidates sort straight into a spreadsheet.
- **Track how opinion shifts over time** by running it on a schedule and letting
  the rows accumulate.

### What you get

One row per product. An abridged row:

```json
{
  "asin": "B079VP6DH5",
  "parentAsin": "B0CT5WBY8Q",
  "title": "Bounty Paper Towels Quick Size, White, 16 Family Rolls",
  "brand": "Bounty",
  "url": "https://www.amazon.com/dp/B079VP6DH5",
  "rating": 4.8,
  "ratingsCount": 235305,
  "starHistogram": { "five": 90, "four": 8, "three": 1, "two": 0, "one": 1 },
  "fiveStarPercent": 90,
  "oneStarPercent": 1,
  "positiveSharePercent": 98,
  "criticalSharePercent": 1,
  "ratingScope": "variant-family",
  "reviewsAnalysed": 13,
  "reviewsForThisProduct": 6,
  "reviewsForOtherVariants": 7,
  "verifiedSharePercent": 100,
  "themeSource": "amazon-aspects",
  "themeCount": 8,
  "topTheme": "quality",
  "topThemeMentions": 2696,
  "positiveThemes": "quality, durability, size, functionality, softness, cleaning, brand",
  "negativeThemes": "",
  "mixedThemes": "thickness",
  "mostCriticisedTheme": "quality",
  "mostCriticisedThemeNegativeMentions": 256,
  "mostCriticisedThemePositivePercent": 91,
  "themes": [
    {
      "label": "quality",
      "sentiment": "positive",
      "mentions": 2696,
      "positiveMentions": 2440,
      "negativeMentions": 256,
      "positivePercent": 91,
      "summary": "Customers appreciate the quality of the paper towels…"
    }
  ],
  "customersSayHeading": "Customers say",
  "customersSaySummary": "Customers find these paper towels durable, noting they stay strong even when wet…",
  "collectedAt": "2026-08-07T10:00:00.000Z"
}
```

### Where each number comes from

The row mixes three sources of different sizes, and every figure says which one
it came from — because reading a theme count as if it were a review count, or a
sample statistic as if it covered everything, is exactly how review analysis goes
wrong.

| Group | Based on | How big |
| --- | --- | --- |
| `rating`, `ratingsCount`, the star breakdown and every `…SharePercent` | Amazon's own star breakdown | Every rating ever left on the product family — by far the largest signal on the row |
| `themes`, `topTheme`, `positiveThemes`, `negativeThemes` | Amazon's own analysis of what customers mention | Thousands of customers on a popular product; the mention counts are Amazon's, not counted from the reviews on the row |
| `reviewsAnalysed`, `verifiedSharePercent`, `averageSampleRating`, `sampleReviews` | The reviews Amazon publishes on the product page | A dozen or so, ranked by relevance rather than by date |

`ratingsCount` is how many people left a **star rating**. It is not the number of
written reviews, which Amazon does not publish, and the two are never mixed.

For the small number of products where Amazon has published no theme analysis,
themes are worked out from the wording of the published reviews instead, and the
row says so with `themeSource: "review-text"`. Those mention counts are much
smaller by nature, because they can only count the reviews on the page.

### Input reference

| Setting | Type | Default | Description |
| --- | --- | --- | --- |
| **Amazon product URLs or ASINs** | list of text | — | **Required.** The products to analyse. Full Amazon links or bare ASINs both work, mixed freely. Duplicates are removed. |
| **Extract recurring themes** | yes / no | yes | Include the themes buyers raise, split into positive, negative and mixed. Turn it off for a rating-only summary. |
| **Attach the reviews analysed** | yes / no | no | Include the individual published reviews the sample figures were built from, so the numbers can be checked. |
| **Minimum mentions for a theme** | whole number | 2 | A theme must have been raised by at least this many customers to be reported. Maximum 20. |
| **Maximum products** | whole number | 100 | Stop after this many products. Maximum 2,000. |
| **Amazon marketplace** | choice | United States | Which country's Amazon site to read. Ratings and reviews differ between marketplaces. |
| **Parallel targets** | whole number | 4 | How many products to work on at the same time. Maximum 10. Leave it at 4 unless you have a reason. |

### Output fields

| Field | Type | Description |
| --- | --- | --- |
| `asin` | string | The product's ASIN. |
| `parentAsin` | string | The family this product belongs to, when it has one. |
| `title` / `brand` | string | Product title and brand. |
| `url` | string | Clean link to the product. |
| `marketplace` | string | The marketplace this reading came from. |
| `rating` | number | Average star rating. |
| `ratingsCount` | number | How many star ratings the product has. |
| `starHistogram` | object | The five star levels, as percentages. |
| `fiveStarPercent` … `oneStarPercent` | number | Each star level on its own column. |
| `positiveSharePercent` | number | Share of ratings at 4 or 5 stars. |
| `neutralSharePercent` | number | Share at 3 stars. |
| `criticalSharePercent` | number | Share at 1 or 2 stars. |
| `ratingBasis` / `ratingScope` | string | What the rating figures are based on, and that they cover the whole product family. |
| `reviewsAnalysed` | number | How many published reviews were on the page. |
| `reviewsForThisProduct` | number | How many of them are about this exact product. |
| `reviewsForOtherVariants` | number | How many are about a sibling variant. |
| `verifiedPurchaseCount` / `verifiedSharePercent` | number | Verified purchases among the published reviews. |
| `verifiedShareBasis` | string | States that the verified share is a sample statistic. |
| `averageSampleRating` | number | Average rating of the published reviews — usually higher than the overall average, since they are chosen for relevance. |
| `sampleRatingCounts` | object | Star counts within the published reviews. |
| `localReviewCount` / `internationalReviewCount` | number | Split of the published reviews by origin. |
| `themeSource` | string | `amazon-aspects`, `review-text`, `none` or `not-requested`. |
| `themeCount` | number | How many themes met the minimum. |
| `themes` | array | Each theme with its label, sentiment, mention count, positive and negative split, and Amazon's own one-sentence summary. |
| `positiveThemes` / `negativeThemes` / `mixedThemes` | string | The theme labels in each sentiment group, comma separated. |
| `topTheme` / `topThemeMentions` | string, number | The theme the most customers raised. |
| `mostCriticisedTheme` | string | The theme with the largest number of negative mentions. |
| `mostCriticisedThemeNegativeMentions` | number | How many of those there were. |
| `mostCriticisedThemePositivePercent` | number | How positive that same theme is overall — a popular theme can carry the most complaints and still be praised by most people. |
| `customersSayHeading` / `customersSaySummary` | string | Amazon's own written summary of customer opinion, when it publishes one. |
| `quotedReviewCount` / `quotedReviewIds` | number, array | Reviews quoted by the theme analysis, including ones beyond those published on the page. |
| `sampleReviews` | array | The published reviews themselves, when you ask for them. |
| `collectedAt` | string | When the reading was taken. |

### Pricing

Pay per event, with a single event:

| What | When you pay |
| --- | --- |
| **Product analysed** | Once for every product row returned. A product that is unavailable, or that could not be read, produces no row and costs nothing. |

There is no per-review charge and no second event. Analysing a product with
thousands of ratings costs exactly the same as one with a handful.

**Worked example.** A shortlist of 200 products costs about $0.30. A full
catalogue sweep of 2,000 products costs about $3.00.

### Limits & what this actor cannot do

- Amazon shows only a selection of customer reviews on a public product page.
  This actor returns that public selection together with the full star
  breakdown, not every review ever written. Any tool promising every review of a
  product is not describing what Amazon publishes.
- Those published reviews are pooled across a product's variant family, so some
  of them are about a sibling size or colour. The row tells you exactly how many
  are about the product you asked for and how many are not.
- The published reviews are ranked by relevance, not by date, so they are not
  "the latest reviews" and their average rating is usually flattering compared
  with the overall star breakdown. Treat every sample figure as a sample.
- Ratings, the star breakdown and the theme analysis are published by Amazon for
  a whole product family. Two variants of the same product return the same
  figures, so this actor does not offer per-variant sentiment — it would be the
  same answer wearing a different ASIN.
- The ratings count is not a count of written reviews. Amazon does not publish
  the second number anywhere on a public product page, so it is not reported and
  is never substituted.
- Customer questions and answers are not publicly listed and are not returned.
- Themes come from Amazon's own analysis wherever it exists. Where it does not,
  they are worked out from the wording of the published reviews, which is a much
  smaller basis, is English-oriented, and is marked as such on the row.
- Opinion data is a snapshot at the moment of collection and keeps changing
  afterwards.
- Ratings and reviews differ between Amazon marketplaces; results reflect the
  marketplace you select.
- Products that are removed, restricted or unavailable in the selected
  marketplace are reported as unavailable rather than returned empty.
- Speed depends on how many products you analyse and on Amazon's own response
  times. No fixed throughput is promised.
- Amazon's terms govern automated access. You are responsible for using the data
  lawfully and in line with the source site's terms, and for handling any
  personal data in line with applicable privacy law.

### FAQ

**Do I need an Amazon account?**
No. It reads only what Amazon shows the public.

**Does it need my login or password?**
No, and it will never ask for one.

**Can I schedule it?**
Yes. Running it weekly or monthly on the same list is a good way to watch
opinion shift over time.

**Is the data complete?**
The rating distribution is complete — it covers every star rating the product
family has received. The theme analysis is Amazon's own and draws on far more
reviews than the page displays. The individual reviews attached to the row are
the selection Amazon publishes publicly, which is around a dozen per product, so
anything derived from them is labelled as a sample.

**Why does the theme mention count dwarf the number of reviews on the row?**
Because they measure different things. The mention counts come from Amazon's
analysis of all its reviews; the reviews on the row are only the ones Amazon
chose to display. Both are reported so the difference is visible.

**Why is a theme both "most criticised" and positive?**
Because a theme everybody talks about collects the most complaints in absolute
terms while still being praised by the large majority. That is why the row
carries the number of complaints and the positive percentage side by side.

**Why is `negativeThemes` often empty?**
Because Amazon labels a theme negative only when opinion genuinely leans that
way. Themes people disagree about show up under `mixedThemes`, and the complaint
counts inside `themes` let you rank pain points even when nothing is labelled
negative.

# Actor input Schema

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

Products to analyse. Full links or bare ASINs both work.

## `includeThemes` (type: `boolean`):

Analyse the published reviews for the words and topics buyers raise most, split into positive and negative.

## `includeSampleReviews` (type: `boolean`):

Include the individual reviews the summary was built from, so the numbers can be checked.

## `minThemeMentions` (type: `integer`):

A word or topic must appear at least this many times to be reported as a theme.

## `maxProducts` (type: `integer`):

Stop after this many products.

## `marketplace` (type: `string`):

Which country's Amazon site to read. Prices, availability and rankings differ between marketplaces, and results come back in that marketplace's own currency.

## `maxConcurrency` (type: `integer`):

How many targets to work on at the same time. Higher is faster but Amazon serves fewer complete pages when pushed hard. Leave at 4 unless you have a reason.

## Actor input object example

```json
{
  "productUrls": [
    "https://www.amazon.com/dp/B079VP6DH5"
  ],
  "includeThemes": true,
  "includeSampleReviews": false,
  "minThemeMentions": 2,
  "maxProducts": 100,
  "marketplace": "us",
  "maxConcurrency": 4
}
```

# Actor output Schema

## `results` (type: `string`):

Every row this run produced.

## `runSummary` (type: `string`):

What this run collected, and anything it could not read.

# 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/B079VP6DH5"
    ],
    "includeThemes": true,
    "includeSampleReviews": false,
    "minThemeMentions": 2,
    "maxProducts": 100,
    "marketplace": "us",
    "maxConcurrency": 4
};

// Run the Actor and wait for it to finish
const run = await client.actor("apt_marble/amazon-review-insights").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/B079VP6DH5"],
    "includeThemes": True,
    "includeSampleReviews": False,
    "minThemeMentions": 2,
    "maxProducts": 100,
    "marketplace": "us",
    "maxConcurrency": 4,
}

# Run the Actor and wait for it to finish
run = client.actor("apt_marble/amazon-review-insights").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/B079VP6DH5"
  ],
  "includeThemes": true,
  "includeSampleReviews": false,
  "minThemeMentions": 2,
  "maxProducts": 100,
  "marketplace": "us",
  "maxConcurrency": 4
}' |
apify call apt_marble/amazon-review-insights --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,apt_marble/amazon-review-insights"
        }
    }
}

```

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/7ulYk0UgaNmOmhuIe/builds/k7rqS7P7vojuuXYeo/openapi.json