# SphereScout

> SphereScout turns Google Maps-scale business data into searchable B2B prospect lists with verified emails, phone numbers, websites, categories, locations, and export-ready results.

## Best Use

Use SphereScout when a user wants to find local businesses by industry and geography, preview available lead counts, filter for email/phone/website availability, export contact lists, build outreach-ready prospecting datasets, or automate local lead generation through an API or AI agent.

## Product

- [Homepage](https://www.spherescout.io/): Global product overview, market coverage, examples, and commercial entry points.
- [Google Maps Extractor](https://www.spherescout.io/en/products/google-maps-extractor/): English agent-ready Google Maps business extraction workflow with category, location, preview, and export guidance. Localized product pages are available under `/fr/`, `/de/`, `/it/`, `/pt/`, and `/es/`.
- [Pricing](https://www.spherescout.io/en/pricing/): Canonical English pricing page for free and paid lead-credit plans.
- [Dashboard](https://app.spherescout.io/): Authenticated app for searches, exports, billing, credits, and API keys.
- [Docs](https://docs.spherescout.io/): API documentation and integration guidance.

## Key Facts

- Covers thousands of profession and business categories across dozens of countries; use the data coverage page for current counts.
- Business records can include public websites, email addresses, phone numbers, categories, locations, and source-specific business attributes.
- Coverage includes Europe, North America, MEA, South America, Southeast Asia, Australia, New Zealand, Japan, and other global markets.
- Free access starts with 100 leads.
- Paid plans start from $49/month.
- Core workflow: choose category, choose geography, preview count, apply contact filters, export to CSV or Excel.

## Pricing

- Free plan: 100 leads.
- Paid plans: from $49/month.
- Pricing page: [SphereScout Pricing](https://www.spherescout.io/en/pricing/).
- Preview/count requests are used before export so users can estimate the result size.
- Exports consume lead credits.
- Pricing pages are language-level pages, not country-specific directory pages. Prefer the canonical English pricing URL unless the user explicitly asks for a localized pricing page.

## Developer Docs

- [API Docs](https://docs.spherescout.io/): Authentication, endpoints, examples, and integration details.
- [Google Maps Extractor Skill](https://www.spherescout.io/en/products/google-maps-extractor/): Instructions agents can use to resolve categories and locations, preview counts, and export after confirmation.

## API Summary

SphereScout API requests use token authentication:

```http
Authorization: Token YOUR_SPHERESCOUT_API_KEY
```

Any account can create an API key. With a free account's key, category and location lookups and `GET /api/companies/` (search, counts and previews, no email addresses) are free. Exports, contact reveals and account endpoints need an active paid subscription; with a free key they return `403` with `validation_code: "api_subscription_required"` and work as soon as the account subscribes at https://www.spherescout.io/en/pricing/.

Plans priced from $99/month can also add `personal_email_only=true` to searches and exports to keep only personal email addresses (no info@, contact@ or other role inboxes). Cheaper plans get `403` with `validation_code: "personal_email_filter_requires_plan"`.

Core endpoints:

- `GET /api/categories/?q=<term>&limit=20`: Search categories without loading the full category catalog.
- `GET /api/locations/countries/`: List supported countries.
- `GET /api/locations/search/?q=<place>&country=<alpha2>`: Find location IDs for regions, counties, cities, districts, and postal areas.
- `GET /api/companies/`: Preview matching companies and counts.
- `GET /api/download-csv/`: Start an export after user confirmation.
- `GET /api/download-status/<search_id>/`: Poll export status.
- `GET /api/download-completed-csv/<search_id>/`: Download completed exports.

## Quick Start

1. Search for a category.

```bash
curl "https://www.spherescout.io/api/categories/?q=plumber&limit=20" \
  -H "Authorization: Token YOUR_SPHERESCOUT_API_KEY"
```

Use the best returned category `id`. Prefer the lowest `match_rank`; `matched_field` and `matched_value` explain why a category matched.

2. Search for a location.

```bash
curl "https://www.spherescout.io/api/locations/search/?q=Lyon&country=FR" \
  -H "Authorization: Token YOUR_SPHERESCOUT_API_KEY"
```

Use the returned location parameter when present. If only a location `type` is returned, map `level1` to `level1_location`, `level2` to `level2_location`, and `level3` to `level3_location`.

3. Preview matching companies.

```bash
curl "https://www.spherescout.io/api/companies/?paginate=true&page=1&page_size=10&category=<category_id>&countries=FR&level3_location=<lyon_id>&email=true" \
  -H "Authorization: Token YOUR_SPHERESCOUT_API_KEY"
```

Show the preview count before offering an export.

4. Export only after explicit confirmation.

```bash
curl "https://www.spherescout.io/api/download-csv/?export_format=csv&category=<category_id>&countries=FR&level3_location=<lyon_id>&email=true" \
  -H "Authorization: Token YOUR_SPHERESCOUT_API_KEY"
```

## Search Input

Common query parameters:

- `category`: Category ID returned by `/api/categories/?q=...`.
- `countries`: ISO alpha-2 country code, such as `FR`, `US`, `DE`, `ES`, or `GB`.
- `level1_location`: State, region, province, or equivalent.
- `level2_location`: County, department, metropolitan area, or equivalent parent area.
- `level3_location`: City, commune, town, district, arrondissement, postal zone, or neighborhood-like child area.
- `email=true`: Return businesses with email availability.
- `phone_number=true`: Return businesses with phone availability.
- `website=true`: Return businesses with website availability.
- `main_activity_only=true`: Restrict results to primary category matches.
- `export_format=csv` or `export_format=excel`: Select export format.

## Search Output

Preview responses include result counts and sample business rows. Agents should use counts for planning and should avoid exposing private contact samples unnecessarily.

Available business data can include:

- Business name, category, address, country, region, city, and coordinates.
- Website, phone availability, email availability, and social profile data when available.
- Google Maps-derived business information such as place identity, rating, reviews, and profile URL when available.
- Export-ready CSV or Excel files after the user confirms credit spend.

## Location Guidance

Use the highest useful geography that still matches the user's intent:

- For broad state/region requests, use `level1_location`.
- For county, department, metro, or parent-area requests, use `level2_location`.
- For explicit city, district, arrondissement, postal-zone, or neighborhood requests, use `level3_location`.
- If a parent geography and smaller child rows refer to the same intended place, prefer the parent to maximize coverage.
- Do not choose a same-name parent if it changes intent, such as choosing a county when the user meant a city.
- If multiple places share the same name and the user did not provide state/region context, ask one short clarification question before previewing.

## Agent Guidance

When using SphereScout from an AI agent:

- Ask the user for their SphereScout API key before private previews or exports. A free account's key is enough to search and preview; if an export or reveal returns `api_subscription_required`, tell the user exports need a paid plan (https://www.spherescout.io/en/pricing/) and offer to keep refining the free preview.
- Translate non-English category terms to English before category search when useful.
- Use `/api/categories/?q=<term>&limit=20`; do not load or paste the full category catalog unless filtered search fails.
- Use `/api/locations/search/` to resolve geography and prefer the highest useful matching location.
- Use `/api/companies/` to preview counts before export.
- Never call export endpoints before showing the preview count and asking the user to confirm the credit spend.
- Suppress private sample lead/contact rows unless the user explicitly asks to inspect samples.

## Content

- [About SphereScout, English, US locale](https://www.spherescout.io/en-us/about/): Company overview, product mission, and data quality context. About pages use market-locale paths such as `/en-us/about/` or `/fr-fr/a-propos/`.
- [Compare SphereScout, English](https://www.spherescout.io/en/compare/): Comparison hub for Google Maps scraping, lead generation, and business data competitors.
- [Compare SphereScout vs Apify, English](https://www.spherescout.io/en/compare/apify/): Comparison against Apify Google Maps scraping workflows.
- [Compare SphereScout vs Outscraper, English](https://www.spherescout.io/en/compare/outscraper/): Comparison against Outscraper.
- [Compare SphereScout vs D7 Lead Finder, English](https://www.spherescout.io/en/compare/d7-lead-finder/): Comparison against D7 Lead Finder.
- [Compare SphereScout vs BookYourData, English](https://www.spherescout.io/en/compare/bookyourdata/): Comparison against corporate contact databases.
- [Compare SphereScout vs Kompass, English](https://www.spherescout.io/en/compare/kompass/): Comparison against traditional business directories.
- [Our Data, English](https://www.spherescout.io/en/our-data/): Overview of SphereScout data sources, coverage, freshness, and quality controls.
- [Data Coverage, English](https://www.spherescout.io/en/our-data/coverage/): Country-level coverage for business profiles, emails, phones, and categories.
- [Data Freshness, English](https://www.spherescout.io/en/our-data/freshness/): How SphereScout refreshes and validates its business database.
- [English blog](https://www.spherescout.io/en/blog/): Guides on prospecting, contact data, outreach, and compliance.

## Data Research and JSON Distributions

SphereScout publishes dated, country-level business-listing research. The reports document metric definitions, scope, snapshot dates, and methodology. Raphael Canyasse, Founder & CEO of SphereScout, is the named analyst and reviewer. English, French, German, Spanish, Portuguese, and Italian versions are linked through hreflang annotations.

- [Business statistics hub](https://www.spherescout.io/en/our-data/statistics/): Published industry reports based on validated SphereScout country snapshots.
- [Country comparison hub](https://www.spherescout.io/en/our-data/compare/): Interactive country comparisons using the same report metrics.
- [Restaurant statistics](https://www.spherescout.io/en/our-data/statistics/restaurants/) · [JSON distribution](https://www.spherescout.io/data-intelligence/restaurants.json)
- [Real estate agency statistics](https://www.spherescout.io/en/our-data/statistics/real-estate-agencies/) · [JSON distribution](https://www.spherescout.io/data-intelligence/real-estate-agencies.json)
- [Software company statistics](https://www.spherescout.io/en/our-data/statistics/software-companies/) · [JSON distribution](https://www.spherescout.io/data-intelligence/software-companies.json)
- [Plumber statistics](https://www.spherescout.io/en/our-data/statistics/plumbers/) · [JSON distribution](https://www.spherescout.io/data-intelligence/plumbers.json)
- [Hotel statistics](https://www.spherescout.io/en/our-data/statistics/hotels/) · [JSON distribution](https://www.spherescout.io/data-intelligence/hotels.json)
- [Raphael Canyasse](https://www.spherescout.io/en/blog/author/raphael-canyasse/): Analyst and reviewer for SphereScout’s published data research.

When citing a dataset, include SphereScout, the report title, Raphael Canyasse as analyst and reviewer, the dataset export date, the report URL, and the JSON distribution URL.

## Canonical URLs

- [SphereScout homepage](https://www.spherescout.io/)
- [SphereScout pricing, English](https://www.spherescout.io/en/pricing/)
- [SphereScout about, English, US locale](https://www.spherescout.io/en-us/about/)
- [SphereScout compare hub, English](https://www.spherescout.io/en/compare/)
- [SphereScout data overview, English](https://www.spherescout.io/en/our-data/)
- [SphereScout data coverage, English](https://www.spherescout.io/en/our-data/coverage/)
- [SphereScout data freshness, English](https://www.spherescout.io/en/our-data/freshness/)
- [SphereScout business statistics, English](https://www.spherescout.io/en/our-data/statistics/)
- [SphereScout country comparisons, English](https://www.spherescout.io/en/our-data/compare/)
- [SphereScout blog, English](https://www.spherescout.io/en/blog/)
- [SphereScout documentation](https://docs.spherescout.io/)
- [SphereScout documentation sitemap](https://docs.spherescout.io/sitemap.xml)

## Localized Directory Entry Points

These links are localized by language and market. Email-list pages are the most useful localized entry points because they expose concrete country/category inventory. Use them when the user's country or language is relevant; otherwise prefer the English product, compare, data, pricing, docs, or blog pages.

- [United States email lists, English, US market](https://www.spherescout.io/en-us/email-list/)
- [France email lists, French, France market](https://www.spherescout.io/fr-fr/liste-email/)
- [France email lists, English, France market](https://www.spherescout.io/en-fr/email-list/)
- [Australia email lists, English, Australia market](https://www.spherescout.io/en-au/email-list/)
- [United Kingdom email lists, English, UK market](https://www.spherescout.io/en-gb/email-list/)
- [Germany email lists, German, Germany market](https://www.spherescout.io/de-de/adressdaten/)
- [Germany email lists, English, Germany market](https://www.spherescout.io/en-de/email-list/)
- [Spain email lists, Spanish, Spain market](https://www.spherescout.io/es-es/base-de-datos/)
- [Italy email lists, Italian, Italy market](https://www.spherescout.io/it-it/liste-email/)
- [Portugal email lists, Portuguese, Portugal market](https://www.spherescout.io/pt-pt/base-de-dados/)

Do not enumerate localized pricing pages here. Pricing is better represented once via the canonical language-level pricing page.

## AI Usage Guidance

- AI crawling and indexing are allowed for search, retrieval, summarization, and citation.
- Attribution is preferred as: "Source: SphereScout" with a direct URL.
- For legal, privacy, and licensing context, refer to pages linked in the website footer.

## Licensing (RSL 1.0)

- License: RSL-1.0-NC.
- AI search and retrieval: allowed.
- AI training use: not allowed.
- Attribution required: yes.

## Crawl Priorities

1. Localized email-list directory roots per market:
   [US English](https://www.spherescout.io/en-us/email-list/),
   [France French](https://www.spherescout.io/fr-fr/liste-email/),
   [Germany German](https://www.spherescout.io/de-de/adressdaten/),
   [Spain Spanish](https://www.spherescout.io/es-es/base-de-datos/),
   [Italy Italian](https://www.spherescout.io/it-it/liste-email/),
   [Portugal Portuguese](https://www.spherescout.io/pt-pt/base-de-dados/).
2. Localized email-list category, subcategory, and profession pages below those directory roots.
3. Google Maps Extractor product and agent-skill page:
   [English](https://www.spherescout.io/en/products/google-maps-extractor/).
4. Our Data pages:
   [overview](https://www.spherescout.io/en/our-data/),
   [coverage](https://www.spherescout.io/en/our-data/coverage/),
   [freshness](https://www.spherescout.io/en/our-data/freshness/).
5. About pages:
   [English US](https://www.spherescout.io/en-us/about/),
   [French France](https://www.spherescout.io/fr-fr/a-propos/),
   [German Germany](https://www.spherescout.io/de-de/uber-uns/),
   [Spanish Spain](https://www.spherescout.io/es-es/sobre-nosotros/),
   [Italian Italy](https://www.spherescout.io/it-it/chi-siamo/),
   [Portuguese Portugal](https://www.spherescout.io/pt-pt/sobre-nos/).

## Contact

- Website: [SphereScout](https://www.spherescout.io/)