# 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."
Extractor de Google Maps — ya ejecutado para ti
Sin scraper que ejecutar, sin proxies, sin CAPTCHAs. Extraemos fichas de negocios locales de Google Maps y fuentes públicas, las verificamos y las actualizamos cada mes. Previsualiza gratis, exporta en segundos.
101 MEmpresas
53,2 MDirecciones de email
50Países cubiertos
Actualizado cada mes
Última actualización 9 jul 2026
Cada campo que extraemos de una ficha
Un registro listo para usar. Nada que procesar, nada que limpiar.
Tres pasos, nada que instalar
Busca y filtra
Elige categoría y zona — país, región, provincia o ciudad. Filtra por email, teléfono o sitio web.
Previsualiza gratis
Consulta volúmenes y resultados de muestra antes de gastar nada. Sin créditos, sin tarjeta.
Exporta
Descarga un CSV con emails — o accede a los mismos datos por API o MCP.
¿Por qué no ejecutar tu propio scraper?
Un scraper «gratis» nunca lo es: cuesta proxies, limpieza y toda tu tarde.
La diferencia honesta con un scraper «en vivo»
A gran escala, todo scraper es una base de datos. La extracción corre por calendario en todas partes — la diferencia es si el proveedor lo dice.
Nosotros lo decimos: cada país de la base muestra públicamente su última fecha de extracción.
Volver solo cuesta la diferencia: comprueba si hay datos nuevos en un export pasado y re-exporta solo las fichas nuevas — nunca compras dos veces la misma lista (planes con suscripción).
Ver nuestras fechas de actualización →Quién lo usa
Agencias de prospección y freelances
Exportaciones repetibles por cliente y mercado, con economía de créditos predecible.
Equipos de ventas y outbound
Listas por ciudad, provincia o región — filtradas a fichas con contactos verificados.
Fundadores y emprendedores
Del mercado objetivo a un CSV utilizable en menos de tres minutos, sin configuración.
Desarrolladores y agentes de IA
La misma base vía API REST y MCP — búsqueda gratis, exportación programática.
Precios
Buscar y previsualizar es gratis. Las exportaciones usan créditos — un crédito por contacto — con planes desde 49 $/mes.
Ver precios →