# Mapsdata

> Mapsdata turns live Google Maps business searches into outreach-ready local lead lists with business details, owner and decision-maker names, business and direct emails, phone intelligence, social profiles, website data, built-in email verification, CSV export, and API access.

Mapsdata is designed for agencies, lead-generation teams, outbound sales teams, consultants, and developers that need current local-business data rather than a static contact database. Searches started through the API and web app use the same jobs, credits, workers, dashboard, and result store.

## Best Use

Use Mapsdata to find businesses by niche and location, research the people behind those businesses, verify contact data, export structured leads, enrich an existing company list from business names and websites, or automate the workflow through an API or AI agent.

## Product

- [Homepage](https://www.mapsdata.io/): Product overview, enrichment capabilities, data-quality details, comparisons, pricing, reviews, and frequently asked questions.
- [Pricing](https://www.mapsdata.io/#pricing): Monthly and yearly paid plans with monthly lead-credit allowances.
- [Machine-readable pricing](https://www.mapsdata.io/pricing.md): Exact prices, allowances, included features, billing rules, API limits, and credit behavior.
- [Search](https://www.mapsdata.io/search): Run a Google Maps business search by business type and location after signing in.
- [Dashboard](https://www.mapsdata.io/dashboard): View searches, live status, lead counts, and completed results.
- [API access](https://www.mapsdata.io/api-access): Create, reveal, copy, rename, and revoke API keys and review API analytics.
- [Product updates](https://www.mapsdata.io/updates): Dated releases covering the public API, standalone enrichment, owner data, email verification, phone intelligence, and live lead extraction.

## Core Capabilities

- Live Google Maps business discovery by niche and location.
- Business name, category, address, website, phone, rating, review count, rank, Google Maps URL, Place ID, CID, claimed status, and other listing fields when available.
- Owner and decision-maker names kept in separate structured fields.
- Business, owner, and decision-maker emails with per-address verification data.
- Business and direct phone numbers with inferred line type and supporting verification evidence when available.
- Public social profiles across Facebook, Instagram, LinkedIn, X/Twitter, YouTube, TikTok, Pinterest, WhatsApp, Tripadvisor, Yelp, Foursquare, and Telegram.
- Website and public-source enrichment, CSV export, double email verification, API access, and priority support on paid plans.
- Live partial results: newly found businesses and enrichment updates appear before a job finishes.

## Pricing Summary

- Free: $0, with one lifetime 100-credit job and a 100-business maximum.
- Starter: 10,000 leads per month for $45 monthly or $405 yearly.
- Growth: 50,000 leads per month for $115 monthly or $1,035 yearly.
- Scale: 200,000 leads per month for $295 monthly or $2,655 yearly.
- Yearly subscriptions are billed once per year, while lead credits still reset monthly.
- Unused paid credits do not roll over. One requested or submitted business costs one lead credit on active paid plans.
- Paid searches and enrichment batches support up to 700 businesses per job, subject to the live account balance and subscription state.

## Developer Documentation

- [API quickstart](https://www.mapsdata.io/docs): Choose discovery-only search, the complete search-and-enrichment pipeline, or standalone enrichment.
- [Authentication](https://www.mapsdata.io/docs/authentication): API-key creation, storage, rotation, and error behavior.
- [Create a search](https://www.mapsdata.io/docs/endpoints/create-search): Start an asynchronous Google Maps search with optional contact enrichment.
- [Create an enrichment](https://www.mapsdata.io/docs/endpoints/create-enrichment): Enrich supplied business names and website URLs without running another Maps search.
- [Search lifecycle](https://www.mapsdata.io/docs/reference/search-lifecycle): Polling, live results, terminal states, and dashboard synchronization.
- [Data fields](https://www.mapsdata.io/docs/reference/data-fields): Business, people, email, phone, social, and verification response fields.
- [Plans and credits](https://www.mapsdata.io/docs/reference/plans-and-credits): Runtime plan limits, reservations, rejections, and refunds.
- [Errors and rate limits](https://www.mapsdata.io/docs/reference/errors-and-rate-limits): HTTP errors, retries, concurrency, and the account-wide request limit.
- [Agent skill](https://www.mapsdata.io/docs/agent-skill): Copy-ready instructions for coding agents that use the Mapsdata API.

## API Summary

Base URL: `https://www.mapsdata.io/api/v1`

All public API endpoints require an API key in the `x-api-key` header. Production creation requests also require a stable `Idempotency-Key` header.

- `GET /account` - Read plan, subscription status, credits, and the current per-search maximum.
- `GET /locations?q=...&country=...` - Resolve a UI-compatible location label.
- `GET /categories?q=...` - Look up normalized Google business categories.
- `POST /searches` - Start discovery only or the full discovery-and-enrichment pipeline.
- `GET /searches` - List searches created through the API.
- `GET /searches/{search_id}` - Read live status, counts, charges, and errors.
- `GET /searches/{search_id}/results` - Page through partial or completed business results.
- `POST /enrichments` - Enrich 1 to 700 supplied business-name and website pairs.
- `GET /enrichments` - List standalone enrichment jobs.
- `GET /enrichments/{job_id}` - Read standalone enrichment status.
- `GET /enrichments/{job_id}/results` - Page through live standalone enrichment results.

## API Behavior

- A search must request at least 100 businesses. Requests below 100 return `422` before a job is created or credits are reserved.
- Set `enrich_contacts` to `false` for Google Maps discovery only or `true` for the complete enrichment pipeline.
- Standalone enrichment accepts a `business_name` and absolute `website_url` for each company.
- API-created searches and enrichments appear in the normal Mapsdata dashboard and lead lists, including live status and partial results.
- The request limit is 1,000 requests per rolling 60 seconds across all keys on an account. There is no separate daily or monthly request cap.
- Creation endpoints are idempotent. Retry the same logical job with the same body and idempotency key.

## Agent Guidance

- Ask the user for an API key before making authenticated requests and never expose it in source code, browser code, logs, screenshots, or output.
- Call `GET /account` before a large job and stay within both `credits_remaining` and `max_results_per_search`.
- Resolve the location with `GET /locations` and send its returned `label` as `input.location`.
- Poll every 5 to 10 seconds, honor `Retry-After`, and fetch all result pages until `has_more` is false.
- Do not replace a slow job with a new one. Resume from its stored ID or repeat creation with the original idempotency key.
- Ask before exporting leads or initiating outreach. The user is responsible for lawful use of business and contact information.

## Optional

- [Expanded machine-readable reference](https://www.mapsdata.io/llms-full.txt): Complete product, pricing, API, workflow, data-field, and responsible-use context in one response.
- [Privacy policy](https://www.mapsdata.io/privacy): How Mapsdata handles account, billing, analytics, and product data.
- [Terms of service](https://www.mapsdata.io/terms): Account, subscription, credit, acceptable-use, and data-accuracy terms.