Metadata-Version: 2.4
Name: mapscopex
Version: 0.1.3
Summary: Search Google Maps listings and extract business website emails.
Author-email: Rohan Dahal <rohandahal5@yahoo.com>
Project-URL: Homepage, https://github.com/rohdahal/geoprobe
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: playwright>=1.40
Requires-Dist: requests>=2.31

# mapscopex

`mapscopex` searches Google Maps for businesses and attempts to extract email addresses from their websites.

## Install

```bash
pip install mapscopex
```

## Public API

```python
from mapscopex import collect_searchprobe, searchprobe
```

- `searchprobe(keyword, location, max_items=None)` streams cumulative results as they are found.
- `collect_searchprobe(keyword, location, max_items=None)` waits for the scrape to finish and returns the final list once.

## Usage

### Streaming search

```python
from mapscopex import searchprobe

for results_so_far in searchprobe(
    keyword="lawyers and law firm",
    location="Houston, TX",
    max_items=None,
):
    print(results_so_far[-1])
```

`searchprobe()` yields the cumulative result set each time a new business is found.

`max_items=None` searches until Google Maps stops yielding new businesses.

### Collect final results

```python
from mapscopex import collect_searchprobe

results = collect_searchprobe(
    keyword="lawyers and law firm",
    location="Houston, TX",
    max_items=None,
)
```

`collect_searchprobe()` waits for the search to finish and returns the final list once.

## Output Shape

Each result is a dictionary with these keys:

```python
{
    "name": str,
    "phone": str,
    "website": str,
    "emails": list[str],
}
```

`searchprobe()` yields a list of these dictionaries after each new business is added. `collect_searchprobe()` returns the final list once the scraper stops.

## Release Notes

The current package version is `0.1.3`. That is a reasonable initial public releases while the API is still settling.
