Google Maps Reviews Scraper Apify Skill

Overview

This skill helps an AI agent run the Apify Google Maps Reviews Scraper actor for exact-place review extraction.

Default actor:

• Actor ID: V2kIsQs3Ta9C9kkEt
• Actor name: x_guru/google-maps-reviews-scraper
• Store page: https://apify.com/x_guru/google-maps-reviews-scraper

Use this skill when a user asks to:

• export Google reviews from a known Google Maps place
• scrape reviews from Google Maps place URLs, CID URLs, review data URLs, or Place IDs
• collect review text, star ratings, dates, review IDs, and direct review URLs
• include public reviewer profile fields
• collect owner replies, review images, review context, detailed ratings, and place metadata
• build review datasets for local SEO, reputation monitoring, sentiment analysis, competitor research, or BI exports

Quick Workflow

1. Confirm the user has exact sources: Google Maps place URLs, CID URLs, review URLs, or Place IDs.
2. If the user only has a keyword/location search, run the main Google Maps Scraper first to discover places.
3. Build input with startUrls or placeIds, maxReviews, reviewsSort, language, and personalData.
4. Set reviewsStartDate only when the user needs recent reviews.
5. Set a budget guard with Apify maxTotalChargeUsd when spend matters.
6. Run scripts/google_maps_reviews_scraper_actor.py or call the Apify API directly.
7. Return rows plus a compact summary. Mention RUN_SUMMARY for diagnostics.

Payload Rules

• startUrls must be array objects: [{"url": "https://www.google.com/maps/..."}].
• placeIds accepts raw Google Place IDs, place_id: values, or compatible URLs.
• maxReviews is required in practice and should be a positive integer.
• reviewsSort must be one of newest, mostRelevant, highestRanking, or lowestRanking.
• Use reviewsSort: "newest" with reviewsStartDate.
• reviewsStartDate accepts YYYY-MM-DD or relative values such as 8 days, 3 months, or 1 year.
• reviewsOrigin should usually be google; all is accepted for compatibility.
• Set personalData=false when the user only needs review text, rating, date, and place metadata.

Authentication

Use an Apify token:

export APIFY_TOKEN='apify_api_xxx'

Never hardcode or print the full token.

Script Usage

The bundled script uses only Python standard library.

Run by Place ID:

APIFY_TOKEN='apify_api_xxx' \
python3 scripts/google_maps_reviews_scraper_actor.py quick-place-id \
  --place-id "ChIJ8Q2WSpJZwokRQz-bYYgEskM" \
  --max-reviews 25 \
  --budget-usd 1

Run by Google Maps URL:

APIFY_TOKEN='apify_api_xxx' \
python3 scripts/google_maps_reviews_scraper_actor.py quick-url \
  --url "https://www.google.com/maps/place/Joe%27s+Pizza/..." \
  --max-reviews 100 \
  --reviews-sort newest \
  --budget-usd 1

Run custom JSON:

APIFY_TOKEN='apify_api_xxx' \
python3 scripts/google_maps_reviews_scraper_actor.py run \
  --input-file references/sample_input.json \
  --budget-usd 1

Input Examples

Place URL

{
  "startUrls": [
    {
      "url": "https://www.google.com/maps/place/Joe%27s+Pizza/@40.7306597,-74.0021707,17z/data=!3m1!4b1!4m6!3m5!1s0x89c259924a960df1:0x43b20488619b3f43!8m2!3d40.7306597!4d-74.0021707!16s%2Fg%2F1tyyy0n3"
    }
  ],
  "maxReviews": 100,
  "reviewsSort": "newest",
  "language": "en",
  "personalData": true
}

Place ID

{
  "placeIds": ["ChIJ8Q2WSpJZwokRQz-bYYgEskM"],
  "maxReviews": 250,
  "reviewsSort": "mostRelevant",
  "reviewsOrigin": "google",
  "language": "en"
}

Recent Reviews

{
  "placeIds": ["ChIJ8Q2WSpJZwokRQz-bYYgEskM"],
  "maxReviews": 100,
  "reviewsSort": "newest",
  "reviewsStartDate": "3 months",
  "personalData": false
}

Output Contract

The runner returns:

• ok
• actorId
• fetchedAt
• inputUsed
• itemCount
• rows[]

Rows are actor dataset items. Important groups:

• Source: searchString, inputStartUrl, inputPlaceId, rank, searchPageUrl, searchPageLoadedUrl
• Review: reviewId, reviewUrl, text, textTranslated, publishAt, publishedAtDate, stars, rating, likesCount, reviewOrigin, originalLanguage, translatedLanguage
• Owner response: responseFromOwnerDate, responseFromOwnerText
• Review extras: reviewImageUrls, reviewContext, reviewDetailedRating, visitedIn, isAdvertisement
• Reviewer: reviewerId, reviewerUrl, name, reviewerNumberOfReviews, isLocalGuide, reviewerPhotoUrl
• Place: title, placeId, fid, cid, kgmid, categoryName, categories, totalScore, reviewsCount, url, imageUrl, price
• Address/runtime: address, city, state, countryCode, location, scrapedAt, language

For the full contract, read references/input-output-contract.md.

Agent Response Rules

• If the user provides a broad search URL, explain that this reviews actor needs exact places.
• If no rows are returned, say the run succeeded but no matching reviews were saved, then suggest checking RUN_SUMMARY.
• If reviewer profile fields are null, check whether personalData=false was used before treating it as missing data.
• If date filtering is active, describe it as best-effort because Google often returns relative dates.
• For large jobs, split by place list and use budget limits.

References

• references/input-output-contract.md
• references/sample_input.json
• references/troubleshooting.md