Metadata-Version: 2.4
Name: mapscopex
Version: 0.1.2
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

```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])
```

`max_items=None` means `mapscopex` will keep scrolling until Google Maps stops yielding new businesses.

`searchprobe()` is a stream, you can stop early and keep the partial results already received:

```python
from mapscopex import searchprobe

latest_results = []

for results_so_far in searchprobe("lawyers", "Houston, TX", max_items=None):
    latest_results = results_so_far

    if len(results_so_far) >= 3:
        break

print(latest_results)
```

If you want the collect-then-return behavior:

```python
from mapscopex import collect_searchprobe

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

## 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.2`. That is a reasonable initial public releases while the API is still settling.
