3.8 KiB
ProspectOS · Maps Scout
A small, personal-use prospect workspace. It sends one search at a time to the bundled gosom/google-maps-scraper worker, waits for its asynchronous job to finish, filters places already in the local catalogue, and presents the remaining places for human review.
The interface is intentionally focused: discovery, run progress, catalogue search, and review status. It does not send outreach, create a CRM campaign, or make an AI decision. The opportunity score is a transparent triage hint based on fields returned by Maps (for example, a missing website and a listed phone number); you make the final review decision.
Start the stack
cp .env.example .env
docker compose up -d --build
Open http://SERVER:8000 for ProspectOS. The Maps worker is available on
http://SERVER:8081 if you want to inspect its native Web UI.
How the worker connects
No Google Cloud API key is required. The bundled standard worker exposes a local REST API on the Docker network, and ProspectOS calls it directly.
The app uses /api/v1/jobs to queue a search, polls /api/v1/jobs/{id}, and
downloads /api/v1/jobs/{id}/download when the job finishes. Jobs are
deliberately asynchronous because a Maps scrape can take several minutes.
Only set GMAPS_API_MODE=saas and GMAPS_API_KEY=... if you deliberately
replace the bundled worker with gosom's optional SaaS edition.
A run that loses its worker connection is shown as failed with a specific error rather than remaining stuck forever.
Configuration
| Variable | Default | Purpose |
|---|---|---|
HOST_PORT |
8000 |
Host port for ProspectOS |
GMAPS_HOST_PORT |
8081 |
Host port for the Maps worker admin UI |
GMAPS_API_MODE |
standard |
standard for the bundled worker; saas only for the optional SaaS API |
GMAPS_API_KEY |
empty | Not required in standard mode; only used in SaaS mode |
GMAPS_REQUEST_TIMEOUT |
300 |
Per-job scraper timeout in seconds |
GMAPS_POLL_SECONDS |
2 |
Poll interval while a job is running |
DISCOVERY_BACKEND |
gmaps when GMAPS_URL is set |
Set to browser only for the bounded public-search fallback |
The app stores its catalogue in the prospect_data Docker volume. The worker
stores its own job data in gmaps_data; keep both volumes if you want to retain
history. To inspect status:
docker compose ps
docker compose logs --tail=100 app
docker compose logs --tail=100 gmaps
Local fallback mode
For a quick local smoke test without the Maps worker:
DISCOVERY_BACKEND=browser GMAPS_URL= docker compose up -d --build
This uses Playwright against public search engines, keeps the same catalogue and review UI, and does not bypass CAPTCHAs or other access controls.
Data and review behavior
Each saved place includes its name, Maps link, website (when present), root
domain, address, phone, category, rating, review count, public emails returned
by the worker when explicitly enabled, source ID, and raw result JSON. A place
with no website is still retained using a stable maps:<place_id> catalogue
key, so it can be reviewed as a potential website opportunity. Existing
websites are deduplicated by root domain.
Email extraction is off by default in the UI. If you enable it for a run, the worker may visit the public business website; expect a longer run and review the resulting provenance before using any contact information.
Tests
python3 -m py_compile api/server.py
node --check web/app.js
python3 -m unittest discover -s tests -q
This project is packaged for personal research. Public availability does not override a website's terms, robots controls, or applicable privacy law; keep searches small, use the worker only on data you are permitted to collect, and do not turn the review screen into unattended outreach.