# 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."
Google Maps Extractor — für Sie bereits ausgeführt
Kein Scraper, keine Proxys, keine CAPTCHAs. Wir extrahieren lokale Unternehmenseinträge aus Google Maps und öffentlichen Quellen, prüfen sie und aktualisieren sie jeden Monat. Kostenlos ansehen, in Sekunden exportieren.
101 Mio.Unternehmen
53,2 Mio.E-Mail-Adressen
50Abgedeckte Länder
Monatlich aktualisiert
Zuletzt aktualisiert 09.07.2026
Jedes Feld, das wir aus einem Eintrag extrahieren
Ein fertiger Datensatz, sofort nutzbar. Kein Parsen, kein Aufräumen.
Drei Schritte, nichts zu installieren
Suchen & filtern
Kategorie und Region wählen — Land, Bundesland, Kreis oder Stadt. Nach E-Mail, Telefon oder Website filtern.
Kostenlos ansehen
Zahlen und Beispielergebnisse prüfen, bevor Sie etwas ausgeben. Ohne Credits, ohne Karte.
Exportieren
CSV mit E-Mails herunterladen — oder dieselben Daten per API oder MCP abrufen.
Warum keinen eigenen Scraper betreiben?
Ein „kostenloser“ Scraper ist nie kostenlos: Er kostet Proxys, Aufräumarbeit und Ihren Nachmittag.
Der ehrliche Unterschied zu einem „Live“-Scraper
Jeder Scraper ist im großen Maßstab eine Datenbank. Extraktion läuft überall nach Zeitplan — der Unterschied ist, ob der Anbieter es sagt.
Wir sagen es: Jedes Land in der Datenbank zeigt öffentlich sein letztes Extraktionsdatum.
Wiederkommen kostet nur die Differenz: Prüfen Sie einen früheren Export auf frische Daten und exportieren Sie nur die neuen Datensätze — dieselbe Liste kaufen Sie nie zweimal (Abo-Tarife).
Unsere Aktualisierungsdaten ansehen →Wer damit arbeitet
Leadgen-Agenturen & Freelancer
Wiederholbare Exporte pro Kunde und Markt, mit planbarer Credit-Ökonomie.
Vertriebs- & Outbound-Teams
Gebietslisten nach Stadt, Kreis oder Region — gefiltert auf Einträge mit geprüften Kontaktfeldern.
Gründer & Unternehmer
Vom Zielmarkt zur nutzbaren CSV in unter drei Minuten, ohne Setup.
Entwickler & KI-Agenten
Dieselbe Datenbank über REST-API und MCP — Suche kostenlos, Export programmatisch.
Preise
Suchen und Ansehen ist kostenlos. Exporte verbrauchen Credits — ein Credit pro Kontakt — mit Tarifen ab 49 $/Monat.
Preise ansehen →