Google Maps Local Business Opportunity Finder

Generate qualified local business leads for web agencies, SEO consultants and sales teams. Search Google Maps by niche and location, find businesses with clear digital gaps, and prioritize outreach using explainable scores.

Discovers local businesses from Google Maps searches or direct place URLs and scores each one for website, SEO, reputation and outreach opportunity using a deterministic formula.

Input

Field	Type	Default	Notes
searchQueries	string[]	[]	Categories/keywords. Combined with every location.
locations	string[]	[]	One task is created per query × location. Requires searchQueries.
startUrls	array	[]	Google Maps search URLs or direct place URLs ({ "url": "..." } or a bare string). requestsFromUrl is rejected.
maxResultsPerSearch	integer	20	Cap per search task.
maxTotalResults	integer	100	Global cap on unique businesses emitted.
includeClosedBusinesses	boolean	false	When false, permanently/temporarily closed places are dropped; their status is still reported when true.
language	string	"en"	hl hint passed to Google Maps.
requestTimeoutSecs	integer	30	Per-request timeout for Maps and website fetches.
enrichFromWebsite	boolean	true	Enables the SSRF-guarded website crawl.
maxWebsitePagesPerBusiness	integer	2	Homepage + N−1 same-origin secondary pages.
websiteConcurrency	integer	5	Parallel website fetches.
respectRobotsTxt	boolean	true	Skip pages disallowed by the site's robots.txt.
maxWebsiteBytes	integer	1500000	Hard byte ceiling per website page.

Every input field changes behaviour; there are no inert options.

Output

One dataset item per unique business — see .actor/dataset_schema.json for the full contract. Highlights:

• placeId — a real ChIJ… Place ID or 0x…:0x… CID only when present in the source. URL slugs never become a Place ID; the value is null otherwise.
• identityKey — deterministic name + address + rounded geo (or Place ID, or name + phone). The source URL is deliberately excluded so the same business found via different URLs merges while the same name at another address stays separate.
• matchedSearches — every search input that produced the business; unioned on merge.
• businessStatus — OPERATIONAL | CLOSED_TEMPORARILY | CLOSED_PERMANENTLY | UNKNOWN.
• websiteEnrichment — requested / attempted / status (ok | skipped | failed | not-requested) / reason, plus HTTPS, mobile viewport, title, meta description, and only literally present emails, phones and social profiles. No email guessing.
• opportunityScore, leadPriorityScore (0–100), opportunityGrade (A–F), opportunityReasons, recommendedPitch, scoreBreakdown.

The run writes a SUMMARY record to the default key-value store with search / dedupe / website counters and failuresByReason.

Scoring

opportunityScore is a weighted average of 0–1 signals: no website (w3), insecure website (w2), no mobile viewport (w2), missing meta description (w1), weak reputation vs. a 3.0–4.8 benchmark (w2), low review count (w2). Missing data lowers a signal — it never fabricates an opportunity. leadPriorityScore blends the opportunity with reachability (phone/website/email/social) and review volume. Grades use the shared 80/65/50/35 bands.

Safety

• Google Maps host allow-list; non-Maps hosts and non-http(s) URLs are rejected with an actionable ConfigError.
• Website fetches go through the shared safeFetch: http/https only, DNS checked against private/loopback/link-local/CGNAT/metadata ranges on every hop, manual redirects with a cap + loop detection, content-type allow-list, real byte ceiling, AbortController timeout always cleared in finally.
• robots.txt is honoured for website pages when respectRobotsTxt is on.
• Only same-origin secondary pages are crawled.
• No CAPTCHA solving, no login, no private endpoints.

Known limitations

• Google frequently serves a consent / verification interstitial to datacenter IPs. The Maps parser (parseMapsResponse) is defensive: structural drift or an interstitial yields zero results and a warning, never a crash. For reliable volume, run behind a residential proxy / unblocker or feed startUrls from a dedicated Google Maps scraper. The scoring, dedupe, safety and contract layers are fully implemented and fixture-tested regardless.
• categoryName is only populated when the payload exposes it.

Commands

npm ci                 # from the monorepo root
npm run check  -w google-maps-local-business-opportunity-finder
npm run smoke  -w google-maps-local-business-opportunity-finder   # offline
npx apify validate-schema

Deployment

This Actor is not deployed. apify push is intentionally not run here — the lead engineer performs deployment.