# 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."
Extrator do Google Maps — já executado para si
Sem scraper para executar, sem proxies, sem CAPTCHAs. Extraímos fichas de empresas locais do Google Maps e de fontes públicas, verificamos e atualizamos todos os meses. Pré-visualize grátis, exporte em segundos.
101 MEmpresas
53,2 MEndereços de email
50Países cobertos
Atualizado todos os meses
Última atualização 09/07/2026
Cada campo que extraímos de uma ficha
Um registo pronto a usar. Nada para tratar, nada para limpar.
Três passos, nada para instalar
Pesquise e filtre
Escolha categoria e região — país, estado, município ou cidade. Filtre por email, telefone ou site.
Pré-visualize grátis
Veja volumes e resultados de amostra antes de gastar qualquer coisa. Sem créditos, sem cartão.
Exporte
Baixe um CSV com emails — ou acesse os mesmos dados via API ou MCP.
Por que não rodar seu próprio scraper?
Um scraper «grátis» nunca é grátis: custa proxies, limpeza e a sua tarde.
A diferença honesta de um scraper «ao vivo»
Em grande escala, todo scraper é um banco de dados. A extração roda por cronograma em todo lugar — a diferença é o fornecedor contar ou não.
Nós contamos: cada país do banco mostra publicamente a data da última extração.
Voltar custa só a diferença: verifique dados novos numa exportação antiga e reexporte apenas as fichas novas — nunca compra a mesma lista duas vezes (planos com assinatura).
Ver nossas datas de atualização →Quem usa
Agências de prospeção e freelancers
Exportações repetíveis por cliente e mercado, com economia de créditos previsível.
Times de vendas e outbound
Listas por cidade, município ou estado — filtradas para fichas com contatos verificados.
Fundadores e empreendedores
Do mercado-alvo a um CSV utilizável em menos de três minutos, sem configuração.
Desenvolvedores e agentes de IA
A mesma base via API REST e MCP — pesquisa grátis, exportação programática.
Preços
Pesquisar e pré-visualizar é grátis. As exportações usam créditos — um crédito por contacto — com planos a partir de 49 US$/mês.
Ver preços →