# Amazon Ratings Scraper API - Star Rating Histogram (`vonsensey/amazon-ratings-scraper-api`) Actor

Scrape Amazon star ratings by ASIN: average rating, total rating count and the full 1-5 star histogram, plus estimated counts per star that Amazon only shows as percentages. Covers every rating on the listing, not a sample. 24 marketplaces, each with its own distribution.

- **URL**: https://apify.com/vonsensey/amazon-ratings-scraper-api.md
- **Developed by:** [Blackcube Agency AB](https://apify.com/vonsensey) (community)
- **Categories:** E-commerce, SEO tools, Marketing
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 reviews

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 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 Ratings Scraper API — star ratings and the full rating histogram by ASIN

Give it ASINs, get back each product's **average rating, total rating count, and the complete 1–5 star breakdown** — plus estimated counts per star level, which Amazon shows as percentages only.

The distribution covers **every rating on the listing**, not the handful of reviews visible on the page. On a product with 635,244 ratings you get the shape of all 635,244, not a sample of eight.

Unofficial tool. Not affiliated with, endorsed by, or connected to Amazon.com, Inc.

***

### What a product row looks like

```json
{
  "rowType": "product",
  "asin": "B07PXGQC1Q",
  "marketplace": "amazon.com",
  "countryCode": "US",
  "averageRating": 4.7,
  "totalRatings": 635244,
  "ratingHistogram":       { "fiveStar": 87, "fourStar": 8, "threeStar": 3, "twoStar": 0, "oneStar": 2 },
  "estimatedRatingCounts": { "fiveStar": 552662, "fourStar": 50820, "threeStar": 19057, "twoStar": 0, "oneStar": 12705 },
  "positiveSharePct": 95,
  "negativeSharePct": 2,
  "histogramAverage": 4.78
}
```

Measured coverage: `totalRatings` and `averageRating` on **95.7%** of product rows, the full histogram on **89.4%**.

### The fields Amazon does not give you

Amazon publishes the percentages and the grand total but never the number of ratings at each star level. This Actor works them out:

- **`estimatedRatingCounts`** — how many 1-star ratings a product actually has, in units rather than percent. Derived as percentage × total and normalised against the real percentage sum, because Amazon's five buckets round and rarely add to exactly 100. They are labelled `estimated` because they are: treat them as close, not exact.
- **`positiveSharePct`** / **`negativeSharePct`** — the 4★+5★ and 1★+2★ shares, ready to chart without doing the arithmetic per row.
- **`histogramAverage`** — the mean recomputed from the distribution. Amazon's own `averageRating` is the authority; a gap between the two flags a listing whose displayed score and published distribution disagree, which is worth a look.

Every one of these is `null` rather than zero when the underlying data is missing. A guessed rating is worse than a missing one.

### How to scrape Amazon star ratings by ASIN

```json
{
  "products": ["B07PXGQC1Q", "B09B8V1LZ3", "B0CWXNS552", "B08H93ZRK9"]
}
```

Bare ASINs, or Amazon URLs pasted straight from the browser — both work, mixed in the same list.

### How to compare Amazon ratings across countries

**Every marketplace keeps its own rating pool**, with its own average, its own total and its own distribution. The same product can be 4.7 in the US and 3.8 in Italy. Add the marketplaces you sell in:

```json
{
  "products": ["B07PXGQC1Q"],
  "marketplaces": ["amazon.com", "amazon.co.uk", "amazon.de", "amazon.it", "amazon.ca"]
}
```

You get one product row **per marketplace**, each with its own histogram and rating count — so you can weight them properly instead of averaging averages. Measured on one product: 4.7 across 635,244 US ratings, 4.6 across 21,906 in Canada, 3.8 across 9 in Italy. All 24 Amazon retail marketplaces are supported.

A product not sold in a marketplace returns a free `not-listed-in-marketplace` row rather than vanishing, so a missing country is never ambiguous.

If Amazon serves a page whose reviews section did not render, you get a free `reviews-section-missing` row instead of a histogram silently reported as absent — the Actor retries first and never guesses.

### How to get the Amazon rating breakdown for many products at once

Paste as many ASINs as you like in one run. Each returns its own rows, and a bad ASIN never stops the run — it gets an `invalid-input` row and the rest continue.

Use **Maximum reviews** to put a hard, exact cap on any run's bill.

### How to export Amazon ratings to CSV or Excel

Every run's dataset exports as JSON, CSV, Excel, XML or HTML from the Apify UI or the API. A prepared **"Product ratings and histograms"** view puts the rating fields in a clean table with the review rows out of the way.

### How to call the Amazon Ratings API from Python

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("vonsensey/amazon-ratings-scraper-api").call(run_input={
    "products": ["B07PXGQC1Q", "B09B8V1LZ3"],
    "marketplaces": ["amazon.com", "amazon.de"],
})

for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    if row["rowType"] == "product":
        print(row["asin"], row["marketplace"], row["averageRating"],
              row["totalRatings"], row["ratingHistogram"])
```

### You also get the reviews

Every run returns the reviews Amazon publishes on each product page as well — rating, title, full text, date, verified-purchase badge, helpful votes, variant and images — at 100% fill on the core fields. Amazon publishes roughly **8–13 per product per marketplace**; that is the public ceiling for every tool, since review-specific pages now require a login.

For ratings work the histogram is usually the better input anyway: it describes every rating on the listing, while any review sample describes only what Amazon chose to show.

### What it costs

Charged **per review returned**. **The rating data is not billed at all** — histograms, averages, totals, estimated counts and shares are always free.

In practice that means **roughly $0.04 per product per marketplace** on the free tier (about 8 reviews × $0.005), and you can compute your bill before you run it: reviews returned × your tier price.

- **No start fee.**
- **Failures are free** — blocked pages, products not listed in a marketplace, products with no reviews and invalid inputs all cost nothing.
- **Product rows are free**, always.
- **Duplicates are free** — the same review found on two marketplaces is charged once.
- Turn on **Charge once per review, ever** for scheduled runs and previously-paid reviews stay free.

### Personal data and GDPR

Reviewer names, profile IDs and profile URLs are personal data and are **off by default**. Rating data contains none of it. This Actor reads only what Amazon publishes publicly; it never logs in.

### Proxy

Required and on by default — Amazon serves a CAPTCHA to unproxied cloud IPs. The default works; no residential proxy add-on needed.

### Related

Need to watch products over time? Use **Amazon Review Monitoring API**, which bills each review only once no matter how often you poll. Need the reviews themselves as the main event? Use **Amazon Product Reviews Scraper API**.

***

*Unofficial tool. Not affiliated with, endorsed by, or connected to Amazon.com, Inc. "Amazon" is a trademark of Amazon.com, Inc., used here only to describe what this tool reads. Publicly available data only.*

# Actor input Schema

## `products` (type: `array`):

One per line. Accepts a bare ASIN (B07PXGQC1Q) or any Amazon product URL pasted from your browser. If you paste a marketplace URL such as amazon.co.uk, that marketplace is used — your link is never silently redirected to amazon.com.

## `marketplaces` (type: `array`):

Amazon publishes a DIFFERENT set of reviews on each marketplace, so adding marketplaces adds genuinely new reviews rather than repeats. Measured on a test ASIN: 8 reviews on amazon.com alone, 36 unique across five marketplaces. Leave as 'Same marketplace as the product' to fetch only one page per product. Duplicates are removed automatically and you are never charged twice for the same review.

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

Hard cap on billable reviews for the entire run. 0 means no cap. Amazon publishes roughly 8 reviews per product per marketplace, so a run is naturally small: 20 products on one marketplace is about 160 reviews.

## `filterByStars` (type: `array`):

Leave empty for all ratings. Amazon no longer honours star filters on the public product page, so this is applied to the reviews after we fetch them — which means you are only ever charged for the reviews you actually keep.

## `onlyVerifiedPurchases` (type: `boolean`):

Return only reviews carrying Amazon's Verified Purchase badge.

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

A date (2026-01-15) or a relative period (30 days, 6 months, 1 year). Left empty, all dates are returned. Reviews whose date could not be read in the marketplace's language are excluded when you set this, rather than being guessed at.

## `includeProductSummary` (type: `boolean`):

One free row per product per marketplace carrying the average rating, the total number of ratings, the full 1-5 star histogram, estimated counts per star, and the positive and negative shares. The distribution covers EVERY rating on the listing, not just the reviews returned. Always free.

## `onlyChargeNewReviews` (type: `boolean`):

For repeat runs on the same products. Reviews you were already charged for in an earlier run are still returned in full, but free, and marked alreadyPaidForInPreviousRun. Turn this on for a daily or weekly monitoring schedule so you are not re-billed for the same reviews every run. Off by default so a first run behaves exactly as you expect.

## `includePersonalData` (type: `boolean`):

Reviewer name, profile ID and profile URL are personal data under GDPR and similar laws. Off by default. Only turn this on if you have a lawful basis for processing it.

## `proxyConfiguration` (type: `object`):

Required. Amazon serves a CAPTCHA to unproxied cloud IP addresses, so a run without a proxy returns no reviews. The default works and no residential proxy is needed.

## Actor input object example

```json
{
  "products": [
    "B07PXGQC1Q"
  ],
  "marketplaces": [
    "auto"
  ],
  "maxReviews": 200,
  "filterByStars": [],
  "onlyVerifiedPurchases": false,
  "reviewsNewerThan": "",
  "includeProductSummary": true,
  "onlyChargeNewReviews": false,
  "includePersonalData": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `csv` (type: `string`):

No description

## `runReport` (type: `string`):

No description

# 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 = {
    "products": [
        "B07PXGQC1Q"
    ],
    "marketplaces": [
        "auto"
    ],
    "maxReviews": 200,
    "includeProductSummary": true,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("vonsensey/amazon-ratings-scraper-api").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 = {
    "products": ["B07PXGQC1Q"],
    "marketplaces": ["auto"],
    "maxReviews": 200,
    "includeProductSummary": True,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("vonsensey/amazon-ratings-scraper-api").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 '{
  "products": [
    "B07PXGQC1Q"
  ],
  "marketplaces": [
    "auto"
  ],
  "maxReviews": 200,
  "includeProductSummary": true,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call vonsensey/amazon-ratings-scraper-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vonsensey/amazon-ratings-scraper-api"
        }
    }
}

```

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/x1CwIdLWvxC0YHwEM/builds/dch6AzmxLQGvxPfG2/openapi.json