# SiteVerdict — Review Stars & Rating Schema Checker (`siteverdict/siteverdict-review-schema-checker`) Actor

Will Google show review stars for your pages? Checks Review and AggregateRating markup (JSON-LD, microdata, RDFa) against Google's review snippet rules and self-serving review policy, then gives exact fixes and corrected JSON-LD. Monitoring and alerts built in.

- **URL**: https://apify.com/siteverdict/siteverdict-review-schema-checker.md
- **Developed by:** [Aman Thakran](https://apify.com/siteverdict) (community)
- **Categories:** SEO tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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/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

## Review Stars & Rating Schema Checker — will Google show your stars?

**Find out in seconds why your product, recipe, course or app pages are not getting review stars in Google — and get the exact fix.** SiteVerdict reads the Review and AggregateRating markup on each page (JSON-LD, microdata and RDFa), checks it against Google's review snippet rules and the **self-serving review policy**, and gives you a plain-English verdict, a fix for every problem and a corrected JSON-LD block.

- ✅ **Star eligibility per page**: `eligible`, `eligible-with-warnings`, `not-eligible` or `no-review-markup`
- 🚫 **Self-serving review detection**: catches the #1 reason businesses lose stars — a LocalBusiness or Organization rating itself on its own site
- 🔧 **Fixes, not just errors**: every issue has a fix, plus ready-to-paste corrected JSON-LD
- 🔁 **Monitoring**: schedule it and get a Slack/webhook alert the day a theme update, app or plugin breaks your stars
- 🧩 **Spots review widgets** (Trustpilot, Yotpo, Judge.me, REVIEWS.io, Feefo, Okendo, Stamped, Loox, Bazaarvoice, PowerReviews…) that inject markup with JavaScript
- 🤖 **Optional AI fix** with your own Anthropic or OpenAI key (off by default)

### Who it is for

1. **E-commerce and Shopify/WooCommerce stores** — check every product page from your sitemap after a theme or review-app change.
2. **SEO agencies** — audit a client's whole catalogue in one run and hand over a report with fixes.
3. **Local businesses and their developers** — confirm whether that "4.9 ★" markup on the homepage can ever show in Google (spoiler: usually not — it is self-serving).

### What it checks

| Check | Based on |
|---|---|
| `aggregateRating` has `ratingValue` and `ratingCount` or `reviewCount` | Google review snippet required properties |
| Counts are whole numbers above 0; rating is a number inside `worstRating`–`bestRating` (default 1–5) | Google review snippet docs |
| Comma decimals (`"4,5"`), `"9/10"`, `"90%"` | Parsed and flagged where Google may misread them |
| `Review` has an `author` with a real name (< 100 characters, not promo text), `itemReviewed` when stand-alone, `reviewRating`, `datePublished` | Google review snippet docs |
| The reviewed item's `@type` is supported (Product, Recipe, Book, Course, Event, HowTo, LocalBusiness, Organization, SoftwareApplication, Movie, Game, CreativeWorkSeason/Series, Episode, MediaObject, MusicPlaylist, MusicRecording and their subtypes) and has a `name` | Google list of valid `itemReviewed` types |
| **Self-serving reviews**: LocalBusiness/Organization rating itself on its own domain → not eligible. Third-party review pages about *another* business are recognised and allowed | Google self-serving review policy |
| Ratings visible on the page (rating or count appears in the HTML text) | Google: marked-up reviews must be visible to users |
| Ratings on category/list pages; many rated products on one page | Google: ratings must be about one specific item |
| Duplicate markup (e.g. JSON-LD plus microdata, or theme plus review app) | Avoids conflicting counts |
| Invalid JSON-LD blocks, blocks split across scripts with the same `@id` (merged correctly) | JSON-LD 1.1 |

### Example output (one page)

```json
{
  "url": "https://shop.example.com/products/rain-jacket",
  "starEligibility": "not-eligible",
  "score": 26,
  "summary": "1 reviewed item: NOT eligible for stars - 4 error(s), 2 warning(s).",
  "issues": [
    { "severity": "error", "code": "aggregateRating-missing-count", "message": "Product \"Rain Jacket\": aggregateRating needs ratingCount or reviewCount (at least one is required).", "fix": "Add \"ratingCount\" (number of ratings) and/or \"reviewCount\" (number of written reviews)." },
    { "severity": "error", "code": "aggregateRating-out-of-range", "message": "Product \"Rain Jacket\": ratingValue 9.2 is outside the 1-5 scale.", "fix": "Add \"bestRating\": 10 to declare your scale." },
    { "severity": "error", "code": "review-author-promo", "message": "... author name \"50% OFF TODAY\" looks like promotional text.", "fix": "Author must be a real person or organization name." }
  ],
  "items": [{ "type": "Product", "name": "Rain Jacket", "eligibility": "not-eligible", "fixSnippet": "<script type=\"application/ld+json\">{ ... \"bestRating\": 10 ... }</script>" }],
  "widgets": ["Judge.me"]
}
```

**Before:** "Why don't we get stars?" — **After:** a list of 3 exact errors, a corrected JSON-LD block and an alert if it ever breaks again.

### How to use

1. Paste page URLs into **Pages to check** and/or add your **sitemap** (we take up to 2,000 pages from it).
2. Click **Start**. Open the **Star eligibility** and **Issues & fixes** tabs, or download the HTML report (`REPORT` in the key-value store) or `RESULTS_CSV`.
3. For ongoing protection, switch on **Monitor mode**, add a Slack or webhook URL and schedule the Actor weekly.

No URLs? It runs on fictional sample pages so you can see every kind of finding for free.

### Pricing

Pay per event — you only pay for pages that were actually checked:

| Event | Price (proposed) |
|---|---|
| Page checked (`page-checked`) | $0.004 |
| AI fix generated (`ai-fix-generated`, only when you switch on AI and it succeeds) | $0.01 |

Examples: **100 product pages ≈ $0.40**, a 1,000-page catalogue ≈ **$4**, weekly monitoring of 50 key pages ≈ **$0.80 a month**. Errors, robots-blocked pages and sample mode are free. If your run's maximum cost is reached, every remaining page gets a `not-processed` row and is not charged; a page is always paid for before an AI fix is added to it. Your AI provider bills you directly for the AI step.

### Benchmark (honest summary)

We compared ours with the structured-data validators on the Apify Store by their documented features (we do not run competitors' Actors).

| | SiteVerdict | Generic schema validators |
|---|---|---|
| Google review-snippet rules (required props, scale, counts) | ✅ | Partial (schema.org syntax only) |
| Self-serving review policy | ✅ | ❌ |
| JSON-LD node merging across blocks (`@id`) | ✅ | Rarely |
| Microdata + RDFa | ✅ | Usually JSON-LD only |
| Fix snippets / AI fix | ✅ | ❌ |
| Monitoring + alerts | ✅ | ❌ |

Live check on 11 Oct 2026: BBC Good Food's pancake recipe splits its Recipe and aggregateRating into two script blocks with the same `@id`. A naive parser reports "missing type/name"; we merge them and correctly report **eligible**.

### FAQ

**Does "eligible" mean Google will show stars?** No. Google decides case by case. Eligible means the markup follows the documented rules, so nothing on the page is stopping it.

**My stars come from a JavaScript widget. Will you see them?** This Actor reads the HTML your server sends (no browser), which is what most review apps output for SEO. If a widget injects markup only in the browser, we tell you and suggest checking with Google's Rich Results Test.

**Why is my LocalBusiness rating "not eligible"?** Since 2019 Google does not show stars for reviews a business hosts about itself (self-serving reviews). Keep ratings on products, recipes, courses etc.; your Google Business Profile reviews show separately.

**Do you store my pages?** No. Only the result is saved in your own Apify storage. Monitor mode keeps a small snapshot (eligibility + issue codes) in a named key-value store in your account.

### Limits

- HTTP only, no JavaScript rendering. robots.txt is always respected; pages that block bots are reported as `robots-blocked` and not charged. Empty or HTTP 202 responses (usually a bot-protection holding page) are reported as errors and not charged; sites behind such protection cannot be checked.
- Max 2,000 URLs per run, 4 MB of HTML per page. Same-host requests are spaced (default 1 s, or the site's Crawl-delay up to 30 s).
- Rule set follows Google documentation as of 11 Oct 2026 (re-checked 3 Nov 2026); Google may change its rules.

### Sources & compliance

- Google Search Central — Review snippet structured data: https://developers.google.com/search/docs/appearance/structured-data/review-snippet (read 11 Oct 2026)
- Google — Structured data general guidelines: https://developers.google.com/search/docs/appearance/structured-data/sd-policies (read 11 Oct 2026)
- Google blog — "Making review rich results more helpful" (self-serving reviews, 16 Sep 2019): https://developers.google.com/search/blog/2019/09/making-review-rich-results-more-helpful
- schema.org vocabulary (CC BY-SA 3.0): https://schema.org/docs/terms.html — type names only.
- Only public pages you choose are fetched, with the honest User-Agent `SiteVerdictBot` (contact hello@webrevenuescan.com), robots.txt (RFC 9309) on every request and redirect, no bot-protection bypass, SSRF protection (private/internal addresses refused; connections are DNS-pinned to the checked address, so DNS rebinding cannot switch the target).
- **Personal data:** reviewer names inside markup are not output (only counts and codes). UK GDPR/PECR: you are responsible for having a lawful basis to audit the sites you submit; audit your own or your clients' sites.
- AI fix (optional) sends only the findings, never secrets, to the provider you choose with your own key.
- This is an independent checker of Google's published rules. It is **not** Google's Rich Results Test and does not call any Google tool; use the Rich Results Test or Search Console for Google's own verdict.
- Not legal advice. Not affiliated with Google.

# Changelog

This Actor's version history is a separate document: https://apify.com/siteverdict/siteverdict-review-schema-checker/changelog.md

# Actor input Schema

## `startUrls` (type: `array`):

Public page URLs (max 2,000 per run). Only http(s) URLs on public hosts are accepted. robots.txt is respected.

## `sitemapUrls` (type: `array`):

XML sitemap or sitemap index URLs. Page URLs found are added to the list (up to 'Max pages from sitemaps').

## `maxSitemapUrls` (type: `integer`):

Cap on page URLs taken from the sitemaps.

## `sampleMode` (type: `boolean`):

Check built-in fictional pages that show every kind of problem. Nothing is fetched or charged. Switched on automatically when no URLs are given.

## `monitorMode` (type: `boolean`):

Remembers each page's result in a named key-value store in your account and reports what changed: star eligibility lost or regained, new or fixed issues. Schedule the Actor daily or weekly.

## `monitorStateName` (type: `string`):

Use a different name for each site or watch list (stored as siteverdict-review-schema-<name>).

## `onlyChanges` (type: `boolean`):

In monitor mode, unchanged pages are not pushed to the dataset (they are still checked and charged).

## `alertOn` (type: `string`):

Regressions = a page lost star eligibility or got a new problem since the last run (needs monitor mode).

## `slackWebhookUrl` (type: `string`):

Optional. https://hooks.slack.com/services/... Stored encrypted, never logged.

## `webhookUrl` (type: `string`):

Optional HTTPS endpoint (Zapier, Make, n8n, your API). Stored encrypted, never logged.

## `aiProvider` (type: `string`):

Off by default. Sends the audit findings (not the page) to YOUR Anthropic or OpenAI account to draft an explanation and corrected JSON-LD. Review it before publishing.

## `aiApiKey` (type: `string`):

Your own Anthropic or OpenAI API key. Stored encrypted by Apify, never logged or output. Your provider bills you for usage.

## `aiModel` (type: `string`):

Leave empty for the default (claude-sonnet-5-5 or gpt-4o-mini).

## `aiMaxPages` (type: `integer`):

Only pages with problems are sent.

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

Different hosts are fetched in parallel; the same host is always spaced out politely.

## `requestDelaySecs` (type: `number`):

Minimum spacing per host. A larger robots.txt Crawl-delay always wins (capped at 30 s).

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.example.com/"
    }
  ],
  "maxSitemapUrls": 100,
  "sampleMode": false,
  "monitorMode": false,
  "monitorStateName": "default",
  "onlyChanges": false,
  "alertOn": "regressions",
  "aiProvider": "none",
  "aiMaxPages": 20,
  "maxConcurrency": 4,
  "requestDelaySecs": 1
}
```

# Actor output Schema

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

No description

## `report` (type: `string`):

No description

## `output` (type: `string`):

No description

## `files` (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 = {
    "startUrls": [
        {
            "url": "https://www.example.com/"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("siteverdict/siteverdict-review-schema-checker").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 = { "startUrls": [{ "url": "https://www.example.com/" }] }

# Run the Actor and wait for it to finish
run = client.actor("siteverdict/siteverdict-review-schema-checker").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 '{
  "startUrls": [
    {
      "url": "https://www.example.com/"
    }
  ]
}' |
apify call siteverdict/siteverdict-review-schema-checker --silent --output-dataset

```

## MCP server setup

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

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/knv1PdCkT0l7UOKWK/builds/8Cnelp1WfkTbdj5Nm/openapi.json
