# SphereScout — Google Maps Extractor Skill
Find local businesses by category and geography, preview market size for free, then export verified business contacts from SphereScout's Google Maps-derived database.
## API Key
Ask the user for their SphereScout API key before browsing private previews or exporting. Store it as `SPHERESCOUT_API_KEY` and send it as:
```http
Authorization: Token $SPHERESCOUT_API_KEY
```
Users can create an API key at https://www.spherescout.io/dashboard.
## Compatibility
This skill works with any AI agent that can read Markdown instructions and make authenticated HTTP requests, including Claude, Codex, Cursor, Windsurf, Hermes, Claw, ChatGPT tool workflows, LangChain or LlamaIndex agents, and custom Python or Node agents.
## Workflow
1. Resolve the category with `GET /api/categories/?q=<category>&limit=20`. Translate non-English category words to English first. Use `match_rank`, `matched_field`, and `matched_value` to choose or clarify. Do not load the full catalog unless the filtered search returns no useful match.
2. Resolve the country with `GET /api/locations/countries/` or a known ISO alpha-2 code.
3. Resolve a city, region, or county with `GET /api/locations/search/?q=<place>&country=<alpha2>`. Use the returned `use_param` when present, and prefer the broadest returned location that still matches the user's named place so the preview does not miss nearby records.
4. Preview with `GET /api/companies/`. This returns counts plus samples and does not expose email addresses.
5. Ask for explicit confirmation before `GET /api/download-csv/`. Exports deduct credits.
6. Poll `GET /api/download-status/<search_id>/` until complete, then fetch `GET /api/download-completed-csv/<search_id>/`.
## Category Lookup
Use the filtered category endpoint first:
1. Translate the user's category term to English before searching. SphereScout category names are indexed in English, but the API also searches localized names when present.
2. Call `GET /api/categories/?q=<term>&limit=20`.
3. Prefer the lowest `match_rank`. Use `matched_field` and `matched_value` to explain or disambiguate the match.
4. If an exact match also has many related matches, treat the exact match as an umbrella category: use that `id`, but tell the user they can narrow if they want.
5. If there is no match, retry with a broader synonym. Example: retry `roofer` as `roofing`.
6. If the term is ambiguous after a retry, ask one short clarification question.
7. Only call unfiltered `GET /api/categories/` as a fallback for unusual cases, and do not paste the full catalog into the conversation.
Language notes:
- French `entrepreneur` usually means contractor; search for `contractor`.
- French `artisan` is too broad; ask for the trade, such as plumber, electrician, roofer, carpenter, or painter.
## Request Map
- Base URL: `https://api.spherescout.io`
- Category: `category_id` in the skill maps to API query param `category`.
- Country: `country` maps to API query param `countries`, e.g. `countries=FR`.
- Locations: `state_id` maps to `level1_location`; `city_id` maps to `level2_location`; `district_id` maps to `level3_location`.
- Filters: `has_email=true` maps to `email=true`; `has_phone=true` maps to `phone_number=true`; `has_website=true` maps to `website=true`; `main_activity_only=true` maps to `main_activity_only=true`.
- Export format: pass `export_format=csv` or `export_format=excel`.
## Location Lookup
Use the highest useful geography, not the narrowest row:
Typical levels:
- `level1`: state, region, province, or equivalent.
- `level2`: county, department, metropolitan area, or equivalent parent area.
- `level3`: city, commune, town, district, arrondissement, postal zone, or neighborhood-like child area.
1. Call `GET /api/locations/search/?q=<place>&country=<alpha2>`.
2. If a result includes `use_param`, use that parameter and ID. If it only includes `type`, map `level1` to `level1_location`, `level2` to `level2_location`, and `level3` to `level3_location`.
3. If the API returns both a parent geography and smaller districts/postal zones/arrondissements for the same place, choose the parent geography to maximize coverage.
4. Do not choose a broader parent if it changes the user's intended place, such as a county with the same name as a city.
5. Use a smaller `level3_location` only when the user explicitly asks for that city, district, arrondissement, postal zone, or neighborhood.
6. If multiple different places share the same name and the user did not provide enough state/region/context, do not preview with the first result. Ask one short clarification question first, for example: "Which Austin do you mean, Austin, Texas?"
7. When the user gives context such as "Austin, Texas", choose the matching city/metro result. Do not choose a same-name county/state if that changes the intended place.
## Preview Example
```http
GET /api/companies/?paginate=true&page=1&page_size=10&category=<category_id>&countries=FR&level3_location=<lyon_id>&email=true
Authorization: Token $SPHERESCOUT_API_KEY
```
## Export Example
```http
GET /api/download-csv/?export_format=csv&category=<category_id>&countries=FR&level3_location=<lyon_id>&email=true
Authorization: Token $SPHERESCOUT_API_KEY
```
## Resolution Example
User asks: `Find plumbers in Lyon with emails.`
1. Search `GET /api/categories/?q=plumber&limit=20`; use the returned `id` for the best exact match.
2. Search locations with `GET /api/locations/search/?q=Lyon&country=FR`; choose the Lyon result and map its returned parameter, for example `level3_location=<lyon_id>`.
3. Preview:
```http
GET /api/companies/?paginate=true&page=1&page_size=10&category=<plumber_category_id>&countries=FR&level3_location=<lyon_id>&email=true
Authorization: Token $SPHERESCOUT_API_KEY
```
Show the count before offering an export.
## US Resolution Example
User asks: `Find dentists in Los Angeles with phone numbers.`
1. Search `GET /api/categories/?q=dentist&limit=20`; use the exact `Dentist` match.
2. Search locations with `GET /api/locations/search/?q=Los%20Angeles&country=US`; if the user means Los Angeles county/metro, use the parent result such as `level2_location=<los_angeles_county_id>`; if they mean the city only, use `level3_location=<los_angeles_city_id>`.
3. Preview:
```http
GET /api/companies/?paginate=true&page=1&page_size=10&category=<dentist_category_id>&countries=US&level2_location=<los_angeles_county_id>&phone_number=true
Authorization: Token $SPHERESCOUT_API_KEY
```
## Field Guidance
- Use `has_email=true` when the user needs outreach-ready records.
- Use `has_phone=true` or `has_website=true` only when the user asks for those fields.
- Use `main_activity_only=true` for strict category matching.
- Prefer the highest useful location level to maximize coverage, then narrow only when the user asks for a specific district, postal zone, arrondissement, or neighborhood.
## Export Rule
Never export before showing the preview count and asking the user to confirm the credit spend.
## Example Prompts
- "Find plumbers in Lyon with emails."
- "Find dentists in Los Angeles with phone numbers."
- "How many dentists are available in France?"
- "Export Italian restaurants in Austin with websites to CSV."
- "Build a county-level prospect list for roofers in California."
Estrattore Google Maps — già eseguito per te
Nessuno scraper da avviare, niente proxy, niente CAPTCHA. Estraiamo le schede delle attività locali da Google Maps e da fonti pubbliche, le verifichiamo e le aggiorniamo ogni mese. Anteprima gratuita, esportazione in pochi secondi.
101 MlnAziende
53,2 MlnIndirizzi email
50Paesi coperti
Aggiornato ogni mese
Ultimo aggiornamento 9 lug 2026
Ogni campo che estraiamo da una scheda
Un record pronto all'uso. Niente da analizzare, niente da pulire.
Tre passaggi, niente da installare
Cerca e filtra
Scegli categoria e zona — paese, regione, provincia o città. Filtra per email, telefono o sito web.
Anteprima gratuita
Controlla volumi e risultati di esempio prima di spendere. Senza crediti, senza carta.
Esporta
Scarica un CSV con le email — o accedi agli stessi dati via API o MCP.
Perché non usare un tuo scraper?
Uno scraper «gratuito» non lo è mai: costa proxy, pulizia e il tuo pomeriggio.
La differenza onesta da uno scraper «live»
Su larga scala ogni scraper è un database. L'estrazione gira ovunque secondo un calendario — la differenza è se il fornitore lo dice.
Noi lo diciamo: ogni paese del database mostra pubblicamente la data dell'ultima estrazione.
Tornare costa solo la differenza: verifica i dati nuovi di un'esportazione passata e riesporta solo le schede nuove — non compri mai due volte la stessa lista (piani in abbonamento).
Vedi le nostre date di aggiornamento →Chi lo usa
Agenzie di lead generation e freelance
Export ripetibili per cliente e mercato, con economia dei crediti prevedibile.
Team commerciali e outbound
Liste per città, provincia o regione — filtrate su schede con contatti verificati.
Founder e imprenditori
Dal mercato target a un CSV utilizzabile in meno di tre minuti, senza configurazione.
Sviluppatori e agenti IA
Lo stesso database via API REST e MCP — ricerca gratuita, esportazione programmatica.
Prezzi
Cercare e vedere l'anteprima è gratis. Le esportazioni usano crediti — un credito per contatto — con piani da 49 $/mese.
Vedi i prezzi →