93 lines
3.6 KiB
Markdown
93 lines
3.6 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` for its one-time setup.
|
|
|
|
### Connect the Maps worker
|
|
|
|
1. Open port `8081` in a browser on your private network.
|
|
2. Use the worker's admin screen to create an API key for this local app.
|
|
3. Put that key in `.env` as `GMAPS_API_KEY=...`.
|
|
4. Restart the app with `docker compose up -d --build` and reload ProspectOS.
|
|
|
|
The app calls `/api/v1/scrape` to queue a job and `/api/v1/jobs/{id}` to poll
|
|
it. Jobs are deliberately asynchronous because a Maps scrape can take several
|
|
minutes. 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_KEY` | empty | API key created in the Maps worker admin UI |
|
|
| `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 old 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.
|