# Google Maps Review Intelligence Analyzer (`headply/google-maps-review-intelligence`) Actor AI-powered review analysis. Turn reviews from Google Maps, Yelp, TripAdvisor, or any source into sentiment scores, topic breakdowns, reputation reports, and actionable business insights. - **URL**: https://apify.com/headply/google-maps-review-intelligence.md - **Developed by:** [Mayowa Ogedengbe](https://apify.com/headply) (community) - **Categories:** E-commerce, Automation, SEO tools - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $6.00 / 1,000 results 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 ## Google Maps Review Intelligence Analyzer **Turn customer reviews into business intelligence.** This Actor is not another review scraper. It's the AI analysis layer that sits on top of any scraper. Feed it reviews from Google Maps, Yelp, TripAdvisor, Booking.com, or any source, and get back: - Per-review sentiment scores (-1.0 to +1.0) and classifications - Topic-level sentiment (what customers love and hate, and by how much) - Key phrases extracted verbatim from each review - One actionable business insight per review - A full reputation report with strengths, weaknesses, trend analysis, and concrete recommendations --- ### How It Works **Step 1:** Run any review scraper on the Apify Store (or bring your own data). **Step 2:** Pass the dataset ID (or raw JSON) to this Actor. **Step 3:** Get AI-enriched reviews + a reputation intelligence report. The Actor auto-detects field names from any scraper output. No manual mapping needed. --- ### Example Output #### Per-Review (dataset) ```json { "placeName": "Joe's Pizza", "reviewerName": "Sarah M.", "stars": 4, "text": "Great pizza but the wait was too long. Staff were friendly though.", "sentiment": "mixed", "sentimentScore": 0.42, "topics": [ { "topic": "food quality", "sentiment": "positive", "score": 0.9 }, { "topic": "wait time", "sentiment": "negative", "score": -0.7 }, { "topic": "staff friendliness", "sentiment": "positive", "score": 0.8 } ], "keyPhrases": ["great pizza", "wait was too long", "staff were friendly"], "actionableInsight": "Food quality praised but wait times are a recurring pain point" } ```` #### Reputation Report (key-value store: `REPORT`) ```json { "placeName": "Joe's Pizza", "totalReviewsAnalyzed": 200, "overallSentiment": "positive", "overallSentimentScore": 0.65, "averageStars": 4.2, "sentimentDistribution": { "positive": 58.5, "negative": 18.0, "neutral": 12.5, "mixed": 11.0 }, "topicScores": { "food quality": { "score": 0.82, "mentionCount": 145, "mentionRate": 72.5, "sentiment": "positive" }, "wait time": { "score": -0.55, "mentionCount": 89, "mentionRate": 44.5, "sentiment": "negative" } }, "strengths": [ { "topic": "food quality", "score": 0.82, "mentions": 145, "summary": "..." } ], "weaknesses": [ { "topic": "wait time", "score": -0.55, "mentions": 89, "summary": "..." } ], "recommendations": [ "Reduce wait times with queue management or reservations", "Only 30% of negative reviews have owner responses. Responding shows customers you care.", "Your strongest area is food quality. Feature this in marketing materials." ], "responseAnalysis": { "totalResponseRate": 45.0, "negativeResponseRate": 30.0 }, "reviewVelocity": { "trend": "increasing", "changePercent": 15.2 }, "topPhrases": [ { "phrase": "great pizza", "count": 23 }, { "phrase": "long wait", "count": 18 } ], "sentimentTrend": [ { "month": "2026-01", "sentimentScore": 0.62, "averageStars": 4.1, "reviewCount": 45 } ] } ``` *** ### Two Input Modes #### Mode 1: Apify Dataset ID (recommended) Run any review scraper first, then pass its dataset ID. No re-scraping needed. ```json { "reviewDatasetId": "abc123xyz" } ``` **Compatible scrapers** (any output with text + rating fields works): - [Google Maps Reviews Scraper](https://apify.com/compass/google-maps-reviews-scraper) - [Yelp Scraper](https://apify.com/compass/yelp-reviews-scraper) - [TripAdvisor Scraper](https://apify.com/maxcopell/tripadvisor-reviews) - [Booking.com Reviews](https://apify.com/voyager/booking-reviews-scraper) - Any scraper that outputs `text`/`reviewText` and `stars`/`rating` fields #### Mode 2: Raw JSON (for testing or one-off analysis) ```json { "reviewData": [ { "text": "Amazing food, terrible service.", "stars": 2 }, { "text": "Hidden gem. Best ramen I've had.", "stars": 5 } ] } ``` *** ### Business Type Presets Select your business type to get optimized topic categories: | Preset | Topics | |---|---| | Restaurant | food quality, service, price/value, cleanliness, atmosphere, location, parking, wait time, portions, staff | | Hotel | room cleanliness, check-in, bed comfort, breakfast, wifi, noise, location, pool/amenities, staff, value | | Salon | skill/quality, wait, cleanliness, staff, pricing, atmosphere, location, booking, products, results | | Clinic | doctor competence, wait time, staff, cleanliness, booking, billing, diagnosis, follow-up, facility, communication | | Retail | product quality, variety, pricing, staff, cleanliness, layout, checkout, returns, location, parking | | Custom | Define your own 5-15 topics | *** ### What the Report Tells You | Section | Business Question It Answers | |---|---| | `sentimentDistribution` | What % of my reviews are positive vs negative? | | `topicScores` | Which aspects of my business do customers care about most? | | `strengths` | What should I double down on in marketing? | | `weaknesses` | What's hurting my rating the most? | | `recommendations` | What specific actions should I take? | | `responseAnalysis` | Am I responding to negative reviews enough? | | `reviewVelocity` | Are my reviews increasing or declining? | | `sentimentTrend` | Is customer satisfaction improving or getting worse? | | `topPhrases` | What words do customers use most? (word cloud data) | | `topPositiveQuotes` / `topNegativeQuotes` | What are my best and worst reviews? | When analyzing **multiple places**, the Actor also generates a `COMPARISON` report ranking all places by sentiment score with their top strengths and weaknesses side by side. *** ### AI Providers | Provider | Default Model | Setup | |---|---|---| | Built-in AI | GPT-5.4-mini | No key needed | | OpenAI | GPT-5.4-mini | Your key from platform.openai.com | | Anthropic | Claude Sonnet 4 | Your key from console.anthropic.com | | OpenRouter | GPT-4o-mini | Your key from openrouter.ai/keys | **Built-in AI** has zero setup. For high-volume runs (1000+ reviews), bring your own key to save on costs. *** ### Recommended Workflow 1. Run a review scraper (e.g. [Google Maps Reviews Scraper](https://apify.com/compass/google-maps-reviews-scraper)) 2. Copy the **dataset ID** from the completed run 3. Paste it into this Actor's `reviewDatasetId` field 4. Select your business type and click Start 5. Check the **Dataset** tab for enriched reviews (sentiment, topics, insights per review) 6. Check the **Key-value store** tab for the full reputation report (see below) For recurring monitoring, schedule both the scraper and this Actor to run monthly. *** ### How to Access the Reputation Report The aggregated report is stored in the **Key-value store**, not in the Dataset. The Dataset contains per-review analysis. The report is the big-picture summary. **To find it after a run completes:** 1. Go to your completed run in Apify Console 2. Click the **Key-value store** tab (next to Dataset, Log, Info) 3. Click the **REPORT** key to view the full JSON report 4. Click **Download** to save it as a JSON file If you analyzed multiple places in one run, each place gets its own report key (e.g. `REPORT_JOES_PIZZA`, `REPORT_MAMA_MIA`) plus a `COMPARISON` key ranking all places side by side. **Tip:** You can also access the report programmatically via the Apify API: ``` GET https://api.apify.com/v2/key-value-stores/{storeId}/records/REPORT ``` *** ### Field Auto-Detection The Actor automatically recognizes review fields from any scraper output: | Our Field | Detected From | |---|---| | Review text | `text`, `reviewText`, `review`, `snippet`, `body`, `comment`, `content` | | Star rating | `stars`, `rating`, `score`, `reviewRating`, `totalScore` (auto-scales 1-10 to 1-5) | | Date | `publishedAt`, `publishedAtDate`, `date`, `iso_date`, `createdAt` | | Reviewer | `reviewerName`, `authorName`, `author`, `user.name` | | Place name | `placeName`, `title`, `name`, `businessName` | | Owner response | `ownerResponse`, `responseFromOwnerText`, `response.snippet` | No manual field mapping needed. Just pipe in any dataset. *** ### Environment Variables (Actor Owners) | Variable | Value | Notes | |---|---|---| | `BUILT_IN_API_KEY` | Your OpenAI API key (`sk-...`) | Set as secret in Apify Console | *** ### Limitations - Reviews under 10 characters are skipped for AI analysis (still counted in rating distributions) - Review text is capped at 2000 characters to control AI costs - AI analysis quality depends on review text quality - Sentiment scores are AI-generated approximations, not ground truth *** ### Changelog #### v1.0 - Two input modes: Apify dataset ID, raw JSON - Auto-detection of review fields from any scraper output - Multi-provider AI: Built-in, OpenAI, Anthropic, OpenRouter - Business type presets: restaurant, hotel, salon, clinic, retail, custom - Per-review: sentiment, topic scoring, key phrases, actionable insights - Reputation report: sentiment distribution, topic analysis, owner response rate, review velocity, monthly trends, phrase frequency, recommendations - Multi-place comparison reports - Retry with exponential backoff on AI API failures # Actor input Schema ## `reviewDatasetId` (type: `string`): Apify dataset ID from a previous scraper run. Works with any Google Maps, Yelp, TripAdvisor, or Booking.com scraper output. Just paste the dataset ID and the Actor auto-detects the review format. ## `reviewData` (type: `array`): Paste a JSON array of review objects directly. Each must have at least a text field (any of: text, reviewText, review, snippet, body, comment) and a rating field (any of: stars, rating, score). Useful for testing or one-off analysis. ## `topicPreset` (type: `string`): Select your business type to use optimized topic categories. Choose 'Custom' to define your own topics below. ## `topics` (type: `array`): Define your own topic categories for AI classification. Only used when Business Type is set to 'Custom'. Add 5-15 topics relevant to your business. ## `includeReport` (type: `boolean`): Generate an aggregated report with strengths, weaknesses, recommendations, sentiment trends, owner response rate, and review velocity. Stored in the key-value store as 'REPORT'. When analyzing multiple places, also generates a 'COMPARISON' report. ## `aiProvider` (type: `string`): Which AI to use for sentiment analysis. 'Built-in AI' requires no API key but costs slightly more per review. Bring your own key for cheaper runs at scale. ## `aiApiKey` (type: `string`): Your API key for the selected AI provider. NOT required for Built-in AI. ## `aiModel` (type: `string`): Override the default model. Leave blank for defaults. Examples: 'gpt-4o' (OpenAI), 'claude-haiku-4-5-20251001' (Anthropic), 'google/gemini-flash-1.5' (OpenRouter). ## Actor input object example ```json { "reviewData": [], "topicPreset": "restaurant", "topics": [], "includeReport": true, "aiProvider": "built-in" } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "reviewData": [], "topics": [] }; // Run the Actor and wait for it to finish const run = await client.actor("headply/google-maps-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "reviewData": [], "topics": [], } # Run the Actor and wait for it to finish run = client.actor("headply/google-maps-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 '{ "reviewData": [], "topics": [] }' | apify call headply/google-maps-review-intelligence --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=headply/google-maps-review-intelligence", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Google Maps Review Intelligence Analyzer", "description": "AI-powered review analysis. Turn reviews from Google Maps, Yelp, TripAdvisor, or any source into sentiment scores, topic breakdowns, reputation reports, and actionable business insights.", "version": "1.0", "x-build-id": "BvU5ran0YW5cBYePn" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/headply~google-maps-review-intelligence/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-headply-google-maps-review-intelligence", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/headply~google-maps-review-intelligence/runs": { "post": { "operationId": "runs-sync-headply-google-maps-review-intelligence", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/headply~google-maps-review-intelligence/run-sync": { "post": { "operationId": "run-sync-headply-google-maps-review-intelligence", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "reviewDatasetId": { "title": "Review Dataset ID", "type": "string", "description": "Apify dataset ID from a previous scraper run. Works with any Google Maps, Yelp, TripAdvisor, or Booking.com scraper output. Just paste the dataset ID and the Actor auto-detects the review format." }, "reviewData": { "title": "Review Data (paste JSON)", "type": "array", "description": "Paste a JSON array of review objects directly. Each must have at least a text field (any of: text, reviewText, review, snippet, body, comment) and a rating field (any of: stars, rating, score). Useful for testing or one-off analysis." }, "topicPreset": { "title": "Business Type", "enum": [ "restaurant", "hotel", "salon", "clinic", "retail", "custom" ], "type": "string", "description": "Select your business type to use optimized topic categories. Choose 'Custom' to define your own topics below.", "default": "restaurant" }, "topics": { "title": "Custom Topic Categories", "type": "array", "description": "Define your own topic categories for AI classification. Only used when Business Type is set to 'Custom'. Add 5-15 topics relevant to your business.", "items": { "type": "string" } }, "includeReport": { "title": "Generate Reputation Report", "type": "boolean", "description": "Generate an aggregated report with strengths, weaknesses, recommendations, sentiment trends, owner response rate, and review velocity. Stored in the key-value store as 'REPORT'. When analyzing multiple places, also generates a 'COMPARISON' report.", "default": true }, "aiProvider": { "title": "AI Provider", "enum": [ "built-in", "openai", "anthropic", "openrouter" ], "type": "string", "description": "Which AI to use for sentiment analysis. 'Built-in AI' requires no API key but costs slightly more per review. Bring your own key for cheaper runs at scale.", "default": "built-in" }, "aiApiKey": { "title": "AI API Key", "type": "string", "description": "Your API key for the selected AI provider. NOT required for Built-in AI." }, "aiModel": { "title": "AI Model Override", "type": "string", "description": "Override the default model. Leave blank for defaults. Examples: 'gpt-4o' (OpenAI), 'claude-haiku-4-5-20251001' (Anthropic), 'google/gemini-flash-1.5' (OpenRouter)." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```