/02-apify-maps-discover

name: 02-apify-maps-discover
description: >-
  Find local-business (SMB) prospects via Google Maps using the Apify Compass
  actor. Use for Zevenue Step-2 Discovery (Vertical) when the ICP is
  Maps-addressable - laundromats, salons, HVAC, yoga studios, gyms, clinics -
  and you need a normalized list of name, domain, address, phone, rating, and
  review count ready for enrichment. Estimates cost and prompts before any run
  over $10. Requires APIFY_API_TOKEN.

Apify Maps Discovery

Turn a vertical + a place into a clean prospect list, scraped from Google Maps via the maintained **Apify Compass** actor (`compass~crawler-google-places`). We wrap the best existing actor rather than build our own scraper - Compass already handles proxies, anti-bot, and layout drift, and offers built-in email/contact enrichment. Output is the normalized Zevenue ProspectRecord schema (JSON + CSV).

Process

1. **Confirm inputs.** Need `search_term` (the vertical) and `geo` (the area). Defaults: `max_results=200`, `min_rating=4.0`. Ask only if missing/ambiguous. 2. **Estimate cost and gate.** The skill prints an estimate before calling the API. If it exceeds **$10**, it requires explicit confirmation (`--yes` or an interactive y/N). Never bypass this silently. 3. **Run the actor.** Calls the Compass sync endpoint with the built input (`searchStringsArray`, `locationQuery`, `maxCrawledPlacesPerSearch`, `placeMinimumStars`). Add enrichment only when asked (see flags). 4. **Normalize.** Each raw place is mapped to the shared 15-field ProspectRecord so it's comparable with the Outscraper / Google Places skills. 5. **Write the run folder.** Writes `runs/<run-id>/` per `headless-gtm-shared/CONVENTIONS.md`: `records.jsonl` (the shared chain format 03+ consume - `company`, `domain`, `person`, plus the firmographic fields), `tracker.json`, `meta.json` (count + spend estimate), `prospects.json` (all 15 ProspectRecord fields), and `records.csv` for humans. Report the row count and path; downstream skills read `runs/<run-id>/records.jsonl` (e.g. 05's `collect --records`).

Usage

# install deps once (use a venv - system Python is externally-managed)
pip install -r ../headless-gtm-shared/requirements.txt
export APIFY_API_TOKEN=...        # console.apify.com → Settings → Integrations

python discover.py \
  --search-term "yoga studios" \
  --geo "California" \
  --max-results 200 \
  --min-rating 4.0 \
  [--include-emails] [--with-review-dates] \
  [--out DIR] [--estimate-only] [--yes]

Inputs

| Flag | Maps to | Default | |---|---|---| | `--search-term` | actor `searchStringsArray` | required | | `--geo` | actor `locationQuery` | required | | `--max-results` | `maxCrawledPlacesPerSearch` | 200 | | `--min-rating` | `placeMinimumStars` | 4.0 | | `--include-emails` | `scrapeContacts` (+$2/1K) | off | | `--with-review-dates` | `scrapePlaceDetailPage` (extra cost) | off | | `--estimate-only` | print cost, no API call | - | | `--yes` | skip the >$10 prompt | - |

Output (normalized ProspectRecord)

`name, domain, website, phone, full_address, city, region, rating, reviews_count, latitude, longitude, place_id, category, last_review_date, source` → see [../headless-gtm-shared/schema.py](../headless-gtm-shared/schema.py).

Cost

| Mode | Flags | Est. price | |---|---|---| | Discovery | (default) | ~$2.10 / 1K | | Discovery + emails | `--include-emails` | ~$4.10 / 1K | | Typical 2K-record run | either | **$4–8** |

`last_review_date` is **off by default** - it needs Compass's per-place detail page (`--with-review-dates`), which adds cost and latency. The cheap default pull leaves it blank. Edit the cost constants at the top of `discover.py` if your account pricing differs from the doc's $2.10/1K figure.

What good output looks like

• Every row has at least `name` + (`domain` or `phone`) - usable for outreach.
• `domain` is a bare host (no scheme/www) so it dedups cleanly downstream.
• Closed businesses are skipped (`skipClosedPlaces`), ratings ≥ `min_rating`.
• Row count is in the ballpark of what the geo realistically contains - a tiny

count usually means the `geo` was too narrow or the term too specific.

Scope boundaries (what this skill does NOT do)

• **Not** directory-only businesses with no Maps listing → use the extraction

skill.

• **Not** tech-stack-defined ICPs (e.g. "stores on Shopify") → signal layer.
• **Not** qualitative web-observable ICPs → separate ICP discovery.
• **Not** email validation or company firmographics → downstream enrichment /

validation skills.

• Outscraper is kept proprietary for client work; **Compass is the public/

distributable Maps tool** chosen here. Google Places was rejected (60-result per-query cap + Enterprise-tier cost for contact fields).

Reference

Deeper detail lives in the `reference/` folder - load the file you need:

• [reference/compass-actor.md](reference/compass-actor.md) - actor ID, sync &

async endpoints, the full input schema (every field + type), raw output fields, and limits.

• [reference/output-schema.md](reference/output-schema.md) - the normalized

15-field ProspectRecord, the raw→normalized field map, domain-extraction and dedup-key rules, and JSON/CSV samples.

• [reference/cost-model.md](reference/cost-model.md) - pricing per mode, how the

$10 gate is computed, worked cost examples, and how to edit the constants.

• [reference/verticals-and-geo.md](reference/verticals-and-geo.md) - recommended

`search_term` phrasings per Zevenue vertical, `geo` formatting, and how to size `max_results` / `min_rating`.

• [reference/examples.md](reference/examples.md) - copy-paste recipes for common

jobs (quick test, full 2K list with emails, multi-city, estimate-only dry run).

• [reference/troubleshooting.md](reference/troubleshooting.md) - empty results,

auth/token errors, timeouts, rate limits, the 300s sync cap, and field-name caveats.