# Review Intelligence (`agentworkflowlab/review-intelligence`) Actor

Turn normalized customer reviews into one deterministic, evidence-backed product intelligence report.

- **URL**: https://apify.com/agentworkflowlab/review-intelligence.md
- **Developed by:** [Agent Workflow Lab](https://apify.com/agentworkflowlab) (community)
- **Categories:** Automation, Integrations
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

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

## Review Intelligence

Turn heterogeneous customer reviews into one auditable product-intelligence report. The Actor normalizes common review fields, summarizes ratings and negative-review share, measures ten business topics, ranks evidence-backed issues, and attaches short verbatim quotes.

**No external API key or LLM is required.** Review content is not sent to a model or third-party API; cloud runs use only Apify's input and output storage APIs. The analysis logic is deterministic keyword/rating analysis with a limited fixed lexical fallback for unrated reviews. The report timestamp (`generatedAt`) varies by run. This is not an LLM semantic-analysis product.

### Use cases

- Rank recurring product and service issues before roadmap planning.
- Compare rating outcomes with topic mention volume.
- Surface review evidence for support, product, and operations teams.
- Normalize exports from several review platforms into one stable report shape.
- Integrate a one-report-per-run analysis step into an API or automation workflow.

### Quick start

An omitted `reviews` field, including input `{}`, runs a **clearly labeled embedded sample** so the default path is useful and QA-safe:

```json
{}
```

To analyze your data, select an existing Apify Dataset in the **Source Dataset** resource picker. API clients can pass its Dataset ID:

```json
{
  "datasetId": "DATASET_ID",
  "productName": "Acme Cloud",
  "maxReviews": 1000
}
```

The Actor opens that Dataset from the caller's accessible storage, reads at most `maxReviews` items, and never writes to, deletes, or otherwise mutates the source. Dataset reports use `inputMode: "dataset"`, and `diagnostics.sourceItemCount` records the number of source items fetched. A missing or inaccessible Dataset still produces exactly one structured zero-review report with a warning instead of failing the run.

Or pass reviews inline:

```json
{
  "productName": "Acme Cloud",
  "negativeRatingThreshold": 3,
  "maxReviews": 1000,
  "reviews": [
    { "id": "r-1", "text": "Fast, but billing was confusing.", "rating": 3, "date": "2026-06-01" },
    { "reviewId": "r-2", "reviewText": "Support solved the setup problem.", "stars": 4, "publishedAt": "2026-06-03" },
    { "title": "Export failure", "body": "The app crashes during large exports.", "score": 1 }
  ],
  "topics": [
    { "label": "Exports", "keywords": ["export", "exports"] }
  ]
}
```

To request an intentional zero-review report, pass:

```json
{ "reviews": [] }
```

An explicit empty array never activates Dataset or sample data. Input precedence is based on property presence: if `reviews` exists, it is used (even `[]`) and `datasetId` is ignored; otherwise a nonblank `datasetId` is used; otherwise the embedded sample is used.

### Native upstream pipelines

Documented Dataset handoffs are covered by contract fixtures and regression tests for:

- [`compass/google-maps-reviews-scraper`](https://apify.com/compass/google-maps-reviews-scraper)
- [`junglee/amazon-reviews-scraper`](https://apify.com/junglee/amazon-reviews-scraper)
- [`thewolves/appstore-reviews-scraper`](https://apify.com/thewolves/appstore-reviews-scraper)

Select the upstream review Dataset in **Source Dataset**; no manual reshaping is required for the documented output forms. Google Maps uses `stars` rather than its external-site `rating` field and never treats place `title` as review text. Junglee Amazon combines `reviewTitle` + `reviewDescription`, maps `ratingScore`, and accepts optional `username`. App Store maps `score` and `userName`. The compatibility fixtures are reconstructed from public upstream schemas and samples; paid upstream Actors were not run.

### Output

Every run writes **exactly one** `review_intelligence_report` item to the default Dataset and writes the same report to the default key-value store record named `OUTPUT`. One report therefore equals one Dataset item with stable automation and output semantics.

Abbreviated output shape:

```json
{
  "type": "review_intelligence_report",
  "inputMode": "inline",
  "productName": "Acme Cloud",
  "summary": {
    "reviewCount": 3,
    "ratedReviewCount": 3,
    "averageRating": 2.67,
    "ratingDistribution": { "1": 1, "2": 0, "3": 1, "4": 1, "5": 0 },
    "negativeReviewCount": 2,
    "negativeReviewShare": 0.6667,
    "dateRange": { "from": "2026-06-01", "to": "2026-06-03" }
  },
  "topics": [],
  "topIssues": [],
  "methodology": {},
  "warnings": [],
  "diagnostics": {}
}
```

Each topic includes `mentions`, `negativeMentions`, `negativeRate`, `impactScore`, `trend`, and up to three verbatim negative-review quotes. `topIssues` ranks topics by:

```text
impact score = negative mentions × (negative mentions / all topic mentions)
```

### Supported review fields

| Canonical value | Accepted fields / behavior |
| --- | --- |
| Text | Generic: `text`, `reviewText`, `content`, `review`, then `title` + optional `body`; Junglee Amazon: `reviewTitle` + `reviewDescription`; source profiles apply safer documented mappings |
| Rating | Generic: `rating`, then `stars`, then `score`; Google Maps: `stars`; Junglee Amazon: `ratingScore`; numeric integers or single-digit decimal strings from 1–5 only |
| Date | Google Maps: valid `publishedAtDate` first; otherwise valid `date`, `publishedAt`, `publishedAtDate`, or `updatedAt`. ISO dates must be a valid date alone or a valid timestamp; their source-local calendar date is preserved. |
| Author | Generic: `author`, `reviewerName`, or `authorName`; Google Maps: `name`; Junglee Amazon: optional `username`; App Store: `userName` |
| ID | `id`, then `reviewId`; otherwise a deterministic content hash |
| Source | Explicit `source`; otherwise the detected profile label (`Google Maps`, `Amazon`, or `Apple App Store`) |

Records without usable text are skipped and counted. Invalid rating/date aliases do not block a later valid alias. Diagnostics expose normalized and detected source-profile counts, mapping counts, skipped records, duplicate-ID repairs, and truncation.

### Built-in topics

The default taxonomy covers product quality, usability, performance, reliability, price/value, customer support, delivery/shipping, documentation/setup, missing features, and billing/cancellation. Add up to 20 custom topics with up to 20 literal keywords each.

### Limits and evidence policy

- At most 5,000 records can be inspected; `maxReviews` defaults to 1,000 and is clamped to a minimum of 1.
- Review text is capped at 5,000 characters.
- Evidence quotes are copied verbatim from supplied text and capped at 240 characters.
- No causal conclusions or generated recommendations are claimed.
- Keyword matching can miss synonyms, negation, sarcasm, and context.
- A valid rating at or below the selected threshold is negative. Only unrated reviews use the documented fixed negative-term fallback.
- Trend compares topic negative rates in chronological earlier and later halves and requires at least two dated topic mentions.

### Privacy and storage

The Actor performs local, in-run computation and makes no external model or third-party API calls. When `datasetId` is used, Apify storage access reads the caller-accessible source Dataset without modifying it. User review data is written only as part of the single report in the run's default Dataset and `OUTPUT` record. The Actor does not write user data to named/shared stores or any external service. Apify account retention settings still govern the source and default storages.

### API integration

Run synchronously and return the Dataset item:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/agentworkflowlab~review-intelligence/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"productName":"Acme Cloud","reviews":[{"text":"Very slow exports","rating":2}]}'
```

Using the Apify JavaScript client:

```js
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('agentworkflowlab/review-intelligence').call({
    productName: 'Acme Cloud',
    reviews: [{ text: 'Very slow exports', rating: 2 }],
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0]);
```

# Actor input Schema

## `reviews` (type: `array`):

Inline review records or documented upstream shapes. Source-specific aliases include Google Maps text/stars/publishedAtDate/name, Junglee Amazon reviewTitle/reviewDescription/ratingScore/username, and App Store text/score/date/userName. The Console editor uses integer ratings and string IDs; Dataset records also normalize numeric strings and numeric IDs at runtime. Maximum 5,000 records are analyzed.

## `datasetId` (type: `string`):

Select an Apify Dataset to analyze. Used only when the reviews property is absent. The Actor receives read-only access to this Dataset and fetches at most maxReviews items.

## `productName` (type: `string`):

Optional product or service label included in the report.

## `topics` (type: `array`):

Up to 20 custom topics, each with up to 20 literal keywords.

## `negativeRatingThreshold` (type: `integer`):

Ratings at or below this value are treated as negative.

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

Maximum records to inspect; hard-capped at 5,000.

## Actor input object example

```json
{
  "negativeRatingThreshold": 3,
  "maxReviews": 1000
}
```

# Actor output Schema

## `reports` (type: `string`):

No description

## `report` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("agentworkflowlab/review-intelligence").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("agentworkflowlab/review-intelligence").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{}' |
apify call agentworkflowlab/review-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=agentworkflowlab/review-intelligence",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/CEaw535KqVcgS3aqQ/builds/MtEKdSH2dbKYHTHnt/openapi.json