Review Aggregator Analyzer

Reliable multi-source review monitor for Google Maps and TripAdvisor with sentiment analysis, date filtering, webhook alerts, and incremental mode.

How it works

This actor is an orchestrator. Instead of scraping Google or TripAdvisor directly (which breaks constantly due to DOM changes and anti-bot updates), it delegates to proven, maintained child actors on the Apify platform:

Platform	Child Actor	Maintained by
Google Maps	compass/Google-Maps-Reviews-Scraper	Compass
TripAdvisor	maxcopell/tripadvisor-reviews	maxcopell

Our value layer on top:

• Unified review schema across both platforms
• Local sentiment analysis (positive / neutral / negative + score)
• Date filtering, rating filtering, sentiment filtering
• Incremental mode — only new reviews since the last run
• Webhook / n8n alerts for negative reviews
• Run summary stored in KV store

Pricing

You are billed for:

1. This actor — lightweight orchestration, typically < $0.01 per run
2. Child actor usage — billed automatically to your Apify account at each child actor's own rate

No proxy costs on your end — child actors manage their own proxies.

---

Quick Start

Simple input (form mode)

{
    "businessName": "McDonald's Times Square",
    "businessLocation": "New York, USA",
    "googleMapsUrl": "https://www.google.com/maps/place/McDonald's/@40.7579787,-73.9877438,17z/...",
    "tripAdvisorUrl": "https://www.tripadvisor.com/Restaurant_Review-g60763-d479078-Reviews-McDonald_s-New_York_City_New_York.html",
    "dateFilter": "last_month",
    "maxReviewsPerBusiness": 50,
    "enableSentiment": true
}

Multiple businesses (API / JSON mode)

{
    "businesses": [
        {
            "name": "McDonald's Times Square",
            "location": "New York, USA",
            "platforms": ["google", "tripadvisor"],
            "urls": {
                "google": "https://www.google.com/maps/place/...",
                "tripadvisor": "https://www.tripadvisor.com/Restaurant_Review-..."
            }
        }
    ],
    "dateFilter": "last_month",
    "maxReviewsPerBusiness": 50,
    "enableSentiment": true
}

Google Maps only (no TripAdvisor URL needed)

{
    "businessName": "My Business",
    "businessLocation": "City, Country",
    "googleMapsUrl": "https://www.google.com/maps/place/...",
    "dateFilter": "last_week"
}

TripAdvisor note: A TripAdvisor URL is required for TripAdvisor scraping. If you omit tripAdvisorUrl, TripAdvisor is skipped gracefully with a log message — it is not an error.

If only businessName + businessLocation are provided (no googleMapsUrl), a Google Maps search URL is constructed automatically. This works for most businesses but a direct Maps URL is more reliable.

---

How to find business URLs

Google Maps URL

1. Go to Google Maps
2. Search for the business
3. Click the business listing so the info panel opens
4. Copy the URL from your browser address bar

The URL should contain /place/ — e.g.:

https://www.google.com/maps/place/McDonald's/@40.7579787,-73.9877438,17z/data=...

TripAdvisor URL

1. Go to TripAdvisor
2. Search for the business
3. Click the listing
4. Copy the URL from your browser address bar

URL formats:

# Restaurant
https://www.tripadvisor.com/Restaurant_Review-g{GEO_ID}-d{LOCATION_ID}-Reviews-Name-City.html

# Hotel
https://www.tripadvisor.com/Hotel_Review-g{GEO_ID}-d{LOCATION_ID}-Reviews-Name-City.html

---

Input Parameters

Business Details

Parameter	Type	Description
businessName	String	Business name (used for labelling and as Google search fallback)
businessLocation	String	City and country (used with businessName for Google search fallback)
googleMapsUrl	String	Google Maps place URL
tripAdvisorUrl	String	TripAdvisor listing URL (required for TripAdvisor; skipped if omitted)
businesses	Array	JSON array of { name, location, platforms, urls } for multi-business runs

Scraping Options

Parameter	Type	Default	Description
platforms	Array	["google","tripadvisor"]	Which platforms to include
maxReviewsPerBusiness	Integer	50	Max reviews per platform per business
sortBy	String	newest	newest, most_relevant, highest_rating, lowest_rating
dateFilter	String	last_month	last_24h, last_48h, last_week, last_month, last_3_months, last_year, all, custom
dateFrom	String	—	Custom range start (YYYY-MM-DD)
dateTo	String	—	Custom range end (YYYY-MM-DD)

Sentiment & Filtering

Parameter	Type	Default	Description
enableSentiment	Boolean	true	Run local sentiment analysis on each review
sentimentFilter	String	all	all, negative_only, neutral_only, positive_only
minRating	Integer	—	Only include reviews with rating ≥ this value
maxRating	Integer	—	Only include reviews with rating ≤ this value
includeBusinessResponse	Boolean	true	Include owner replies in output

Webhook Alerts

Parameter	Type	Default	Description
webhookUrl	String	—	POST target for negative review alerts (n8n, Zapier, etc.)
negativeThreshold	Integer	2	Reviews at or below this rating trigger a webhook alert

Advanced (Incremental Mode)

Parameter	Type	Default	Description
onlyNewReviews	Boolean	false	Only fetch reviews newer than the last run
firstRunDateLimit	String	last_month	Lookback on the very first incremental run

---

Output Schema

Every item in the dataset follows this shape. All keys are always present — null is used where the source does not supply a value.

{
    "id": "compass-review-id-or-generated",
    "business": {
        "name": "McDonald's Times Square",
        "location": "New York, USA",
        "businessId": null,
        "platformBusinessId": null
    },
    "platform": "google",
    "platformUrl": "https://www.google.com/maps/place/...",
    "reviewer": {
        "name": "R J",
        "profileUrl": null,
        "reviewCount": null,
        "isLocalGuide": false,
        "avatarUrl": null
    },
    "review": {
        "rating": 4,
        "ratingNormalized": 4,
        "text": "Convenient location and great customer service staff.",
        "date": "2025-12-18",
        "dateISO": "2025-12-18T21:41:33.000Z",
        "language": "en",
        "helpfulVotes": 0,
        "photos": []
    },
    "businessResponse": null,
    "sentiment": {
        "score": 0.47,
        "label": "positive",
        "confidence": 0.68,
        "source": "combined",
        "breakdown": { "text": 0.43, "rating": 0.5 }
    },
    "metadata": {
        "scrapedAt": "2025-12-18T21:41:33.277Z",
        "isNew": true,
        "runId": "VTnrK3BNnx",
        "architecture": "orchestrator-v2"
    }
}

Sentiment Score Interpretation

Label	Score Range	Meaning
positive	> 0.2	Happy customer
neutral	-0.2 to 0.2	Mixed or average
negative	< -0.2	Needs attention

---

Webhook Payload

When a review at or below negativeThreshold stars is found, a POST is sent to webhookUrl:

{
    "alertType": "negative_review",
    "timestamp": "2025-12-18T21:41:33.277Z",
    "business": { "name": "McDonald's Times Square", "location": "New York, USA" },
    "platform": "google",
    "review": {
        "id": "...",
        "rating": 1,
        "text": "Very bad experience...",
        "reviewerName": "John D.",
        "date": "2025-12-18",
        "url": "https://..."
    },
    "sentiment": { "score": -0.7, "label": "negative" }
}

A run-complete summary is also sent after all reviews are processed:

{
    "alertType": "run_complete",
    "summary": {
        "totalReviews": 47,
        "negativeReviews": 5,
        "positiveReviews": 38,
        "neutralReviews": 4,
        "averageRating": 4.1
    }
}

---

API Usage

Start a Run

curl -X POST "https://api.apify.com/v2/acts/malikgen~google-and-tripadvisor-review-scraper/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "McDonald'\''s Times Square",
    "businessLocation": "New York, USA",
    "googleMapsUrl": "https://www.google.com/maps/place/...",
    "tripAdvisorUrl": "https://www.tripadvisor.com/Restaurant_Review-...",
    "dateFilter": "last_month",
    "maxReviewsPerBusiness": 50,
    "enableSentiment": true
  }'

Get Results

curl "https://api.apify.com/v2/datasets/DATASET_ID/items?token=YOUR_TOKEN&format=json"
curl "https://api.apify.com/v2/datasets/DATASET_ID/items?token=YOUR_TOKEN&format=csv"

---

n8n Integration

1. Import the included n8n-workflow-async-polling.json into n8n
2. Add your Apify API token as a Query Auth credential
3. Set the Actor ID to malikgen~google-and-tripadvisor-review-scraper
4. Optionally connect a webhook URL for instant negative review alerts

---

Troubleshooting

No reviews returned?

• Verify URLs open correctly in a browser
• Try dateFilter: "last_3_months" or "all" to confirm reviews exist
• For TripAdvisor, confirm you provided tripAdvisorUrl (it is required)

Fewer reviews than expected?

• Increase maxReviewsPerBusiness
• Widen the date filter
• Child actors may have their own rate limits — check their logs in your Apify run history

Run times out?

• This orchestrator runs child actors synchronously. For large maxReviewsPerBusiness values, the child actors may take several minutes. The parent actor's timeoutSecs (default 3600) should be sufficient for most cases.

---

Changelog

v0.0 (Orchestrator Architecture)

• Replaced native scrapers with child-actor calls (compass + maxcopell)
• Removed proxy configuration requirement — child actors handle proxies
• Retained all value-layer features: sentiment, filtering, webhook, incremental mode
• Reduced orchestrator memory to 1024 MB (lightweight — no browser)
• Added unified field-mapping layer for consistent output across platforms

v0.0.21 (Previous — Native Scrapers)

• Native Google Maps and TripAdvisor scrapers (now replaced)
• Sentiment analysis, date filtering, webhook alerts