# 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 — already run for you
No scraper to run, no proxies, no CAPTCHAs. We extract local business listings from Google Maps and public sources, verify them, and refresh them every month. Preview free, export in seconds.
101MBusinesses
53.2MEmail Addresses
50Countries Covered
Refreshed monthly
Last updated Jul 9, 2026
Every field we extract from a listing
One extracted record, ready to use. No parsing, no cleanup.
Three steps, nothing to install
Search & filter
Pick a category and a location — country, state, county, or city. Filter by has-email, has-phone, has-website.
Preview free
See counts and sample results before spending anything. No credits, no card.
Export
Download a CSV with emails — or pull the same data through the API or MCP.
Why not run a scraper yourself?
A “free” scraper isn't free. It costs proxies, cleanup passes, and your afternoon.
The honest difference from a “live” scraper
Every scraper at scale is a database. Extraction runs on a schedule everywhere — the difference is whether the vendor tells you.
We tell you. Every country in the database shows its latest extraction date, publicly.
Coming back costs only the difference: check any past export for fresh data and re-export just the new records — you never buy the same list twice (subscription plans).
See our refresh dates →Who uses this
Lead-gen agencies & freelancers
Repeatable exports per client and per market, with predictable credit economics.
Sales & outbound teams
Territory lists by city, county, or state — filtered to records with verified contact fields.
Founders & entrepreneurs
From target market to usable CSV in under three minutes, no setup.
Developers & AI agents
The same dataset over REST API and MCP — search free, export programmatically.
Pricing
Searching and previewing is free. Exports use credits — one credit per contact — with plans from $49/month.
See pricing →