# Product Review-to-Roadmap Extractor (`gifted_wagon/product-review-to-roadmap`) Actor

Turn Amazon, Google Maps, Trustpilot, G2, app-store, support, or survey reviews into ranked defect, feature, and objection tickets with traceable evidence.

- **URL**: https://apify.com/gifted\_wagon/product-review-to-roadmap.md
- **Developed by:** [Michael Olmos](https://apify.com/gifted_wagon) (community)
- **Categories:** AI, E-commerce, Marketing
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.80 / 1,000 actionable review analyzeds

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

## Product Review-to-Roadmap Extractor

Convert Amazon, Google Maps, Trustpilot, G2, app-store, survey, or support reviews into a ranked queue of **defects, feature requests, and objections** with traceable excerpts and roadmap-ready tickets. No AI key or external enrichment service is required.

### What you get

The default dataset contains:

- `review-analysis` — one successfully analyzed unique actionable review with theme, type, secondary themes, severity, recency, confidence, source context, matched phrases, and excerpt. This is the primary pay-per-event unit.
- `roadmap-ticket` — an uncharged aggregate ranked using transparent frequency, severity, recency, and confidence components. Each ticket includes evidence, affected versions, a problem statement, recommended action, acceptance criteria, and validation metric.

The `OUTPUT` key-value-store record is an uncharged summary of invalid, duplicate, non-actionable, processed, budget-limited, and ticket-type counts.

### Quick start

Run with no input for a useful built-in sample, or paste records:

```json
{
  "reviews": [
    {
      "id": "r-1",
      "text": "Please add CSV export and scheduled reports.",
      "rating": 3,
      "productName": "Northstar Analytics",
      "date": "2026-08-01"
    },
    {
      "id": "r-2",
      "text": "The app crashes whenever I apply more than three filters.",
      "rating": 1,
      "productName": "Northstar Analytics",
      "version": "6.4.0"
    }
  ]
}
```

Choose an upstream dataset for production. Common camelCase, snake\_case, nested author, timestamp, and rating formats are detected automatically; `fieldMap` supports explicit dot-separated paths.

### Deterministic analysis

1. Normalize text, ID, rating, date, version, platform, product name, locale, author, URL, and helpful count.
2. Reject textless rows and remove exact normalized duplicates.
3. Detect actionable defects, requests, and objections using a versioned domain taxonomy. Praise without an actionable signal is skipped.
4. Preserve the matched phrases and a short source excerpt.
5. Rank per-product themes using frequency (40%), severity (30%), recency (20%), and confidence (10%).
6. Generate an evidence-linked triage ticket with validation-oriented acceptance criteria.

The same input and settings produce the same classification. The Actor does not call an LLM, transmit review text to an external model, or invent quotations.

### Charging and budgets

The primary value event is `actionable-review-analyzed`. Invalid, exact-duplicate, non-actionable, and failed rows are not charged as analyzed reviews. Roadmap-ticket rows and the `OUTPUT` summary are uncharged. The Actor checks the maximum-charge budget before each paid batch and stops cleanly if no event capacity remains.

A one-time `$0.0003` Actor-start event covers measured startup overhead, including invalid-input runs. Set an Apify maximum total charge for unfamiliar inputs.

### Privacy and decision boundary

`includeOriginalReview` defaults to `false`; canonical fields are included by default. Review data may contain personal information—retain only the fields your purpose and policy permit.

Generated tickets are triage inputs, not customer commitments or proof of demand. Keyword methods can miss context, sarcasm, and unsupported languages. Validate roadmap choices with representative users, product strategy, effort, retention, support, and behavioral telemetry.

### Development

```bash
npm ci
npm run typecheck
npm test
npm run build
npm run benchmark
npm run launch:verify
```

See `launch/OPERATIONS.md` for release checks, maintenance, privacy, and rollback.

# Actor input Schema

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

Optional Apify dataset containing Amazon, Google Maps, Trustpilot, G2, App Store, Google Play, survey, or support review rows.

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

Review objects in common source formats. Text, rating, date, product, platform, and version aliases are detected automatically.

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

Hard cap across inline and dataset sources. Invalid, duplicate, and non-actionable rows are not charged as analyzed reviews.

## `recentWindowDays` (type: `integer`):

A review this old contributes half the maximum recency weight to roadmap priority.

## `minThemeReviews` (type: `integer`):

Only themes with at least this many paid review analyses become uncharged roadmap-ticket rows.

## `maxEvidencePerTheme` (type: `integer`):

Maximum number of high-severity review excerpts retained in each roadmap ticket.

## `fieldMap` (type: `object`):

Optional canonical-field to source-path map, for example {"text":"feedback.body","productName":"entity.name"}. Dot paths are supported.

## `includeNormalizedReview` (type: `boolean`):

Include the canonical fields used by classification on each paid review-analysis record.

## `includeOriginalReview` (type: `boolean`):

Copy the complete source row into output. Enable only when the output dataset may safely retain it.

## `payload` (type: `object`):

Automatically supplied when connected to another Actor run.

## Actor input object example

```json
{
  "reviews": [],
  "maxReviews": 500,
  "recentWindowDays": 180,
  "minThemeReviews": 1,
  "maxEvidencePerTheme": 5,
  "fieldMap": {},
  "includeNormalizedReview": true,
  "includeOriginalReview": false
}
```

# Actor output Schema

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

Paid review-analysis rows followed by uncharged ranked roadmap-ticket rows.

## `summary` (type: `string`):

Source, data-quality, budget, theme-type, and output counts. This record is not a primary value event.

# 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("gifted_wagon/product-review-to-roadmap").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("gifted_wagon/product-review-to-roadmap").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 '{}' |
apify call gifted_wagon/product-review-to-roadmap --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,gifted_wagon/product-review-to-roadmap"
        }
    }
}

```

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/geapEIfZqng6n8nTz/builds/L967wwaNlLgszIuxE/openapi.json