Google Maps Scraper Apify Skill

Overview

This skill helps an AI agent run the Apify Google Maps Scraper actor for local business collection and enrichment.

Default actor:

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

Use this skill when a user asks to:

• collect Google Maps places by search term and location
• scrape direct Google Maps search URLs or place URLs
• enrich existing Google Place IDs
• build local lead lists with websites, phones, addresses, ratings, and coordinates
• add public website contact extraction
• extract Google Maps reviews or images
• create Apify-ready JSON payloads for n8n, CRM, Sheets, or API workflows

Quick Workflow

1. Clarify the target: business type, location, desired count, and whether add-ons are needed.
2. Build the smallest useful payload first.
3. Set a budget guard with Apify maxTotalChargeUsd when the user cares about spend.
4. Run the actor through scripts/google_maps_scraper_actor.py or the Apify API.
5. Return summary metrics and dataset rows.
6. Explain missing fields as normal best-effort behavior when Google Maps or the business website does not expose data.

Payload Rules

• Standard discovery uses searchStringsArray, locationQuery, and maxCrawledPlacesPerSearch.
• Exact Google Maps URLs use startUrls as objects: [{"url": "https://www.google.com/maps/..."}].
• Exact Google Place IDs use placeIds.
• Structured search area uses countryCode, city, state, county, postalCode, customGeolocation, and strictLocationBounds; locationQuery has priority when present.
• Broad visible-map collection uses allPlacesNoSearchAction="all_visible" and optional allPlacesZoom; use it only for concrete local areas.
• Paid filters include placeCategories, customPlaceCategories, searchMatching, minStars, website, and skipClosedPlaces.
• Use scrapeCompanyContacts only when the user needs public website emails, phones, or social links.
• Use maxReviews only when the user explicitly needs review rows or review fields.
• Use maxImages only when the user needs image URLs beyond the main image.
• Use scrapePlaceDetailPage for richer opening hours, menu links, plus code, inside places, web results, and detailed place metadata.
• Place details can be extended with scrapeTableReservationProviderData, scrapeOrderOnlineWidgetData, includeWebResults, and scrapeInsidePlaces.
• Image extraction can be extended with scrapeImageAuthors.
• Keep initial tests small: 10-50 places before scaling.

Authentication

Use the Apify API token from the environment:

export APIFY_TOKEN='apify_api_xxx'

Never hardcode or print the full token in user-facing output.

Script Usage

Install requirements if your runtime expects a requirements step:

pip install -r requirements.txt

Run a quick search:

APIFY_TOKEN='apify_api_xxx' \
python3 scripts/google_maps_scraper_actor.py quick-search \
  --query "bike repair shop" \
  --location "Portland, Oregon, USA" \
  --limit 25 \
  --budget-usd 1

Run with reviews:

APIFY_TOKEN='apify_api_xxx' \
python3 scripts/google_maps_scraper_actor.py quick-search \
  --query "dentist" \
  --location "Austin, Texas, USA" \
  --limit 20 \
  --reviews 10 \
  --reviews-sort newest \
  --budget-usd 1

Run with website contacts:

APIFY_TOKEN='apify_api_xxx' \
python3 scripts/google_maps_scraper_actor.py quick-search \
  --query "roofing contractor" \
  --location "Denver, Colorado, USA" \
  --limit 50 \
  --with-contacts \
  --only-with-website \
  --budget-usd 2

Run a custom payload:

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

Recommended Inputs

Local business discovery

{
  "searchStringsArray": ["bike repair shop"],
  "locationQuery": "Portland, Oregon, USA",
  "maxCrawledPlacesPerSearch": 100,
  "language": "en"
}

Exact URLs

{
  "startUrls": [
    {
      "url": "https://www.google.com/maps/search/restaurants+near+New+York,+NY"
    }
  ],
  "maxCrawledPlacesPerSearch": 100,
  "language": "en"
}

Place IDs

{
  "placeIds": ["ChIJN1t_tDeuEmsRUsoyG83frY4"],
  "maxCrawledPlacesPerSearch": 1,
  "scrapePlaceDetailPage": true
}

Add-on Fields

• scrapePlaceDetailPage: extra place details.
• scrapeCompanyContacts: website contact enrichment.
• maxReviews: reviews per place.
• reviewsStartDate: optional YYYY-MM-DD review date filter.
• reviewsSort: newest, mostRelevant, highestRanking, or lowestRanking.
• reviewsFilterString: keyword filter for review text.
• reviewsOrigin: all or google.
• scrapeReviewsPersonalData: include reviewer profile data when allowed.
• maxImages: additional image URLs per place.

Output Contract

The runner returns JSON with:

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

Rows are actor dataset items. Common fields include:

Core identity:

• title
• subTitle
• description
• price
• categoryName
• categories
• rank
• isAdvertisement

Address and geography:

• address
• neighborhood
• street
• city
• state
• postalCode
• countryCode
• location
• locatedIn
• floor
• plusCode

Contacts and web presence:

• website
• phone
• phoneUnformatted
• emails
• additionalPhones
• facebooks
• instagrams
• linkedIns
• twitters
• youtubes
• tiktoks

Ratings, reviews, and media:

• totalScore
• reviewsCount
• reviewsDistribution
• reviews
• reviewsScraped
• reviewsFetchStatus
• reviewsFetchMethod
• reviewsDateFilterStatus
• imageUrl
• images
• imagesCount
• imageFetchStatus
• imageFetchMethod
• imageAuthorsStatus
• imageCategories

Details and identifiers:

• openingHours
• additionalOpeningHours
• popularTimesLiveText
• popularTimesLivePercent
• popularTimesHistogram
• menu
• servicesLink
• reserveTableUrl
• googleFoodUrl
• peopleAlsoSearch
• placesTags
• reviewsTags
• gasPrices
• hotelStars
• hotelDescription
• hotelAds
• placeId
• fid
• cid
• kgmid
• url
• searchPageUrl
• searchPageLoadedUrl
• searchString
• language
• scrapedAt
• additionalInfo

The hosted actor output page also exposes:

• dataset link: results
• run diagnostics link: summary, pointing to RUN_SUMMARY

Agent Response Rules

• If a run succeeds with zero rows, say that the actor finished but Google Maps returned no matching places for the requested input.
• If add-on fields are missing, explain that they are best-effort and depend on Google Maps or the business website exposing data.
• For lead generation requests, recommend scrapeCompanyContacts plus website=withWebsite when the user needs emails.
• For large jobs, split by city, keyword, or area and use budget limits per run.
• For compliance-sensitive review workflows, turn scrapeReviewsPersonalData off unless the user explicitly needs reviewer profile fields.

References

• references/actor-input-guide.md
• references/sample_input.json
• references/troubleshooting.md