# Google Maps Review Sentiment Analysis Tool (`invaluable_rondeau/google-maps-reviews-ai-competitive-report`) Actor

Turn your existing Google Maps review data into evidence-linked sentiment and competitive reports; AI claims require exact source quotes.

- **URL**: https://apify.com/invaluable\_rondeau/google-maps-reviews-ai-competitive-report.md
- **Developed by:** [PROOFNEXA](https://apify.com/invaluable_rondeau) (community)
- **Categories:** AI, Developer tools
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $15.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## Every AI claim is backed by an exact-match quote from a real review

### Google Maps Reviews → AI Competitive Report

**New Actor.** Turn an existing Apify reviews dataset or your own JSON into one evidence-backed competitive report per place. This Actor does not scrape Google Maps, Yelp, or any website. You bring the reviews you already have, plus your own OpenAI API key.

It analyzes review text and ratings only. Reviewer names, profile URLs, and other reviewer personal data are ignored and never returned.

### Why the output is safer to use

AI can make a plausible claim without adequate evidence. This Actor rejects that failure mode in code: every AI-produced competitive claim, strength, complaint, and recommendation must carry a `quotedReview` that exactly equals one original review body. A quote that is edited, shortened, invented, or merged is dropped from the output.

Source-derived rating fields (`averageRating` and `sentimentBreakdown`) are calculated directly from supplied star ratings. `sentimentBreakdown` uses 4–5 stars = positive, 3 = neutral, and 1–2 = negative.

### Input

Provide exactly one review source and an OpenAI API key:

| Field | Required | Description |
|---|---:|---|
| `datasetId` | One source required | Existing Apify dataset ID containing place records and/or review rows. |
| `reviewsJson` | One source required | Array of place records with `reviews` arrays and/or individual review rows. |
| `openaiApiKey` | Yes | Your OpenAI API key. Used only for this run; never emitted in output or logs. |
| `language` | No | `en` (default) or `ja` for the report wording. |
| `maxReviewsPerPlace` | No | Maximum source reviews per place; default 200. |

For compatibility with common Google Maps dataset shapes, review text may be in `reviews[].text`, `reviewText`, `comment`, or `content`; ratings may be in `stars`, `rating`, or `score`. Each place is compressed to no more than 12,000 review-text characters before the AI call.

### Output

One record per place:

```json
{
  "placeName": "Example Cafe",
  "sourceReviewCount": 84,
  "reviewsAnalyzed": 71,
  "averageRating": 4.23,
  "sentimentBreakdown": { "positive": 62, "neutral": 4, "negative": 5 },
  "competitiveSummary": { "claim": "Guests praise the coffee quality.", "quotedReview": "The espresso was excellent and beautifully balanced." },
  "strengths": [{ "theme": "Coffee quality", "quotedReview": "The espresso was excellent and beautifully balanced." }],
  "complaints": [{ "theme": "Slow service", "quotedReview": "It took thirty minutes to get our order." }],
  "recommendations": [{ "action": "Improve peak-hour service speed.", "quotedReview": "It took thirty minutes to get our order." }],
  "aiTokenUsage": { "promptTokens": 0, "completionTokens": 0, "totalTokens": 0 },
  "sourceDatasetId": "existing-dataset-id",
  "analyzedAt": "2026-08-02T00:00:00.000Z"
}
```

If no exact source quote supports an AI claim, the claim is omitted (`competitiveSummary: null` or an empty array). This is intentional.

### Pricing and limits

The Actor is priced per output place report. Your OpenAI usage is billed by your own API provider, separately from Apify. It does not provide or resell an AI key.

### Notes

- This Actor analyzes supplied data only; it does not retrieve reviews itself.
- A run fails clearly before analysis if `openaiApiKey` is missing.
- The default dataset contains the evidence-backed output records. A `SUMMARY` key-value record reports success rate, AI token total, and rejected unsupported-claim count.

# Actor input Schema

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

An existing dataset containing Google Maps place records and/or review rows. No scraping is performed.

## `datasetItemsUrl` (type: `string`):

Optional short-lived signed URL for reading a private dataset without changing its access setting. Keep this value secret.

## `reviewsJson` (type: `array`):

Place records with reviews arrays and/or individual review rows. Review author names and profiles are ignored.

## `openaiApiKey` (type: `string`):

Bring your own OpenAI-compatible API key. It is used only for this run and is never written to output or logs.

## `language` (type: `string`):

Language used for the generated competitive report.

## `maxReviewsPerPlace` (type: `integer`):

Maximum number of source reviews analyzed for each place. Review text is additionally compressed to 12,000 characters per place before AI analysis.

## Actor input object example

```json
{
  "language": "en",
  "maxReviewsPerPlace": 200
}
```

# 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("invaluable_rondeau/google-maps-reviews-ai-competitive-report").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("invaluable_rondeau/google-maps-reviews-ai-competitive-report").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 invaluable_rondeau/google-maps-reviews-ai-competitive-report --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=invaluable_rondeau/google-maps-reviews-ai-competitive-report",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/RB1csRbCxSQraTw5y/builds/zNsnfpcvOSknoAlcg/openapi.json