97 lines
3.8 KiB
Markdown
97 lines
3.8 KiB
Markdown
# ProspectOS · Maps Scout
|
|
|
|
A small, personal-use prospect workspace. It sends one search at a time to
|
|
the bundled [gosom/google-maps-scraper](https://github.com/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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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.
|