Google Maps Review Pain-Point Miner

Turn Google Maps reviews into customer insight and sales opportunities. Find recurring complaints, service issues, sentiment patterns and positive differentiators for local businesses, locations and competitors.

Mines Google Maps reviews for recurring complaints, positive differentiators and an explainable business opportunity score.

Input

Field	Type	Default	Notes
placeUrls	string[]	[]	Google Maps place URLs (direct route) or search URLs (search route).
searchQueries	string[]	[]	Google Maps search queries (search route).
businessTargets	string[]	[]	Business name (+ optional location) looked up via the search route.
maxReviewsPerPlace	integer	120	Reviews analysed per place.
maxTotalReviews	integer	2000	Global cap on reviews analysed across the run.
language	string	"en"	hl hint.
requestTimeoutSecs	integer	30	Per-request timeout.
concurrency	integer	3	Places fetched in parallel.
minReviewsForConfidence	integer	15	Reviews needed for dataConfidence = 1.0; fewer reviews dampen the score.
emitReviewRows	boolean	false	Also emit one row per analysed review (topic tags + sentiment).

At least one of placeUrls / searchQueries / businessTargets is required. Invalid Google Maps hosts raise an actionable ConfigError. The direct place route and the search route are tracked separately and reported per place.

Output

type: "place_analysis" — one per place (see .actor/dataset_schema.json):

• rating: ratingReported, ratingFromReviews, ratingDistribution (1–5).
• ownerResponseRate — share of analysed reviews with an owner response.
• topicFindings — per recurring topic (waiting time, pricing, service, cleanliness, staff, availability, quality, location): mentions, negativeMentions, positiveMentions, negativeShare, sentiment, confidence (min(1, mentions / saturationHits)), sampleQuotes.
• painPoints — topics with enough mentions (≥ max(2, 10 % of reviews)) and negativeShare ≥ 0.4, most negative first.
• positiveDifferentiators — topics reviewers consistently praise.
• opportunityScore (0–100) / opportunityGrade / scoreTerms / scoreExplanation / recommendedActions.
• dataConfidence (0–1).

Optional type: "review" rows. A SUMMARY record with per-place reports, counts and failuresByReason is written to the key-value store.

The score formula (explainable)

opportunityScore = round( dampen × weightedAverage[
    low-rating(w3)         = inverse of rating vs a 2.5–4.7 benchmark
    pain-breadth(w2)       = number of distinct pain points, scaled 0–4
    pain-intensity(w2)     = negative share of the worst pain point
    owner-neglect(w1)      = inverse of owner response rate vs 0–0.6
    negative-sentiment(w2) = (1 − mean review sentiment) / 2
] )
dampen = 0.5 + 0.5 × dataConfidence
dataConfidence = min(1, reviewsAnalyzed / minReviewsForConfidence)

The exact term values are echoed back in every item's scoreExplanation and scoreTerms.

No fabrication

If a place returns no rating and no reviews, opportunityScore is null, opportunityGrade is "N/A", and recommendedActions says to gather data first. A high reputation opportunity is never invented from missing data. placesWithoutReviewData in the summary counts these.

Safety

All fetches use the shared safeFetch (http/https only, DNS checked against private ranges, manual redirects, content-type allow-list, byte ceiling, timeout cleared in finally). One failing place never aborts the run; failures are counted by reason. No CAPTCHA solving, no login, no private endpoints.

Known limitations

• Google serves reviews through a JS app / internal RPC. This Actor issues a GET and parses framed JSON or an embedded state blob heuristically; an interstitial or a layout change yields fewer / no reviews and a warning, never a crash. Review reviewId and absolute dates are usually unavailable via this path (relativeDate is kept when present). All aggregation, topic mining, sentiment, scoring and resilience logic is fully implemented and fixture-tested.

Commands

npm ci                                          # monorepo root
npm run check -w google-maps-review-pain-point-miner
npm run smoke -w google-maps-review-pain-point-miner   # offline
npx apify validate-schema

Deployment

Not deployed here. apify push is intentionally not run — the lead engineer handles deployment.