Review Weakness Intelligence — What Customers Actually Complain About

Turn a pile of reviews into a ranked list of complaints. Point it at a business (Google Maps, optionally Trustpilot) and instead of dumping raw reviews, it clusters them into themes — "slow service", "billing surprises", "rude staff" — with a sentiment read, mention counts, and example quotes. The output is a CX/competitive-intel brief, not a review export.

Keywords: review analysis, customer complaint analysis, voice of customer, google reviews sentiment, trustpilot analysis, competitor weakness research.

---

Why this actor

Every other review scraper hands you 500 raw rows and leaves the reading to you. This one does the synthesis:

• Theme clustering groups reviews by what they're about using a transparent keyword/topic method (no black-box ML) — clearly labeled so you can trust and tune it.
• Sentiment + severity per theme, so the worst problems float to the top.
• Example quotes per theme, so a human can sanity-check instantly.
• Two sources — Google Maps reviews (via Places API) and optionally a Trustpilot URL — merged into one themed view.

Use it to audit your own business, or to find a competitor's soft spots before a pitch.

---

What it does

1. Resolves the business: search by businessName + location, or use a provided placeId directly.
2. Fetches Place Details reviews (up to maxReviews).
3. Optionally fetches Trustpilot reviews from trustpilotUrl.
4. Clusters combined reviews into themes (keyword/topic), scores sentiment, keeps themes with at least minMentionsPerTheme mentions.
5. Pushes one record per theme per source and charges per pushed result.

Input

Field	Type	Default	Notes
businessName	string	—	required
location	string	—	helps resolve the right place
placeId	string	—	use directly instead of searching
trustpilotUrl	string	—	optional second source
maxReviews	integer	50	cap on reviews pulled
minMentionsPerTheme	integer	2	drop themes below this
googlePlacesApiKey	string (secret)	—	required — Places API (New) key
proxyConfiguration	object	—	optional Apify proxy

Output (per theme, per source)

theme, source (google_maps / trustpilot), mention_count, sentiment, severity, example_quotes, sample_ratings.

Notes & honesty

• Theme clustering is a transparent keyword/topic method, not an LLM — good for scale and cost, not perfect nuance. Tune keywords in theming.py.
• Google Place Details typically returns a limited number of reviews per call — maxReviews is bounded by what the API exposes (marked TODO-VERIFY in places_client.py).
• Trustpilot parsing in trustpilot_client.py is best-effort and marked TODO-VERIFY — confirm against a live page before production.
• Original implementation; not derived from any other actor's code.