# Mapsdata: Complete Product and API Reference

> Mapsdata is a live Google Maps business search and contact-enrichment platform. It finds local businesses by niche and location, identifies owners and decision makers, discovers business and direct contact details, verifies emails, enriches records with public web data, and returns structured results through both a web application and public API.

Last updated: 2026-10-01

Canonical website: https://www.mapsdata.io/

API documentation: https://www.mapsdata.io/docs

API base URL: https://www.mapsdata.io/api/v1

Machine-readable pricing: https://www.mapsdata.io/pricing.md

## What Mapsdata Does

Mapsdata replaces the manual work between finding a local business and identifying a useful contact. A user supplies a business type and location, Mapsdata runs a live Google Maps search, imports businesses as they are found, and can continue through website crawling, owner and decision-maker research, public-source enrichment, contact discovery, phone classification, social-profile discovery, and email verification.

Mapsdata can also enrich businesses that the user already has. The standalone enrichment workflow accepts company names and website URLs, skips Google Maps discovery, and runs the same contact and verification stages used by a full search.

The API and web application are synchronized. API-created jobs appear in Dashboard and Lead lists with an API origin label. Status, lead counts, partial businesses, and enriched fields update in the UI while workers are still running. Dashboard-created and API-created work use the same subscription, credit balance, active-job allowance, workers, and result store.

## Intended Users and Use Cases

Mapsdata is built for:

- Lead-generation agencies building lists for clients.
- Outbound sales and business-development teams targeting local companies.
- Marketing agencies prospecting by service category and geography.
- Consultants and freelancers researching a niche or territory.
- Developers connecting local-business discovery and enrichment to internal tools, CRMs, or automations.
- AI agents that need a documented, idempotent workflow for finding or enriching businesses.

Common uses include searching plumbers in Chicago, identifying owners of roofing companies in Denver, finding business and direct emails for dentists in New York, exporting enriched local leads to CSV, or enriching an existing list that already contains company names and domains.

## Search Workflows

### 1. Google Maps business discovery only

Create a search with `enrich_contacts: false`. Mapsdata runs discovery and returns the listing data supplied by the search provider, but skips website crawling, owner research, email discovery, secondary public-source enrichment, and email verification. Enrichment status fields return `not_requested`.

### 2. Complete discovery and enrichment pipeline

Create a search with `enrich_contacts: true`. Mapsdata discovers businesses and then researches contacts, people, websites, social profiles, phones, and verification signals for every imported result where data is available.

### 3. Standalone enrichment

Create an enrichment job with one or more `business_name` and absolute `website_url` pairs. Mapsdata does not perform a new Google Maps search. Every supplied company appears in the dashboard immediately, and its fields update as enrichment progresses.

## Search Input

A search body contains an optional display name, an `input` object, and the enrichment choice.

Required search input:

- `input.query`: Business type or search phrase, up to 300 characters. Examples include `plumbers`, `dentists`, and `roofing contractors`.
- `input.location`: The location `label` returned by `GET /locations`, for example `New York, New York`.
- `input.maxResults`: Requested business count. Minimum 100. Current product maximum 700, further bounded by plan and credits.

Optional search input:

- `name`: Dashboard list name, up to 200 characters.
- `input.countryCode`: Uppercase ISO two-letter country code such as `US`.
- `input.language`: Two- or three-letter language code, optionally followed by a locale. Default `en`.
- `enrich_contacts`: `true` for the complete pipeline or `false` for business discovery only. Default `true`.

Mapsdata normalizes search phrasing before sending it to the discovery provider, including singular and plural variants where appropriate, so equivalent category searches use consistent provider input.

## Standalone Enrichment Input

An enrichment body contains an optional job name and a `businesses` array.

- `businesses[].business_name`: Required company or business name, up to 200 characters.
- `businesses[].website_url`: Required absolute `http://` or `https://` company website URL.
- Batch size: 1 to 700 unique businesses, further bounded by the account plan and remaining credits.
- Duplicate name-and-website pairs, relative URLs, and non-HTTP(S) URLs return `422`.

## Result Data

Mapsdata result pages use one consistent business shape for searches and standalone enrichments. Arrays remain arrays when empty, optional scalar values use `null`, and partial results can gain new values while a job is active.

### Business identity and Google Maps data

- Mapsdata lead ID and parent search or enrichment ID.
- Business name, primary category, all known categories, and provider category ID.
- Import position and stable rank alias.
- Google Place ID, Google CID, direct Maps listing URL, and claimed status when available.
- Business operating status such as `OPERATIONAL` when supplied by the provider.

### Location and reputation

- Formatted address, street, city, state or region, postal code, and country code.
- Aggregate rating and review count.
- Business image and logo or profile-image URL when available.

### Website, phones, and public profiles

- Canonical website and display domain.
- Primary business phone and additional unique numbers.
- Phone-type mapping such as mobile, landline, or VoIP when classification is available.
- Supporting phone-verification evidence when a second source confirms a number.
- Public social URLs for Facebook, Instagram, LinkedIn, X/Twitter, YouTube, TikTok, Pinterest, WhatsApp, Tripadvisor, Yelp, Foursquare, and Telegram when discovered.

### People and emails

- First best owner or decision-maker name.
- Separate arrays for owner names and decision-maker names.
- Separate verified-owner and verified-decision-maker arrays where a supporting source exists.
- Supporting owner reasoning when available.
- All emails, owner emails, and decision-maker emails in separate fields.
- Per-address email verification payloads.
- Structured key contacts collected from supporting public sources.

Mapsdata publicly reports that an average search returns a named owner for more than 70% of businesses. Mapsdata users report bounce rates below 2% on live campaigns using verified results. These are product-reported averages and outcomes, not guarantees for an individual niche, location, or campaign.

## Email Verification

Email verification is built into the enrichment workflow and does not require a separate tool. Business, owner, and decision-maker emails can each receive an independent result. Mapsdata exposes the original verification payload per canonical lowercase address and a job-level verification status.

The UI presents usable classifications such as Safe, Risky, Catch-all, Disposable, and Invalid. An `ok` result with `good` quality is presented as safe. Catch-all, unknown, and lower-quality responses require caution. Invalid addresses should not be used. If a terminal payload has not arrived and the overall verification stage is still active, continue polling.

Paid plans include double email verification as part of the enrichment pipeline.

## Job Lifecycle and Live Results

Discovery jobs generally move through:

`queued -> starting -> running -> importing -> enriching -> completed`

A failed job ends in `failed`. Fast jobs may skip intermediate states. Treat only `completed` and `failed` as terminal.

Standalone enrichment begins at `enriching` because the caller has already supplied the businesses:

`enriching -> completed` or `enriching -> failed`

Workers commit available batches without waiting for the provider run to finish. Each commit updates the lead count, results endpoints expose those rows immediately, and the web application reads the same records. A client can display newly found businesses before completion, then refresh all pages after the terminal state to capture final enrichment fields.

## API Authentication and Key Management

All public API endpoints require a Mapsdata API key in the `x-api-key` request header.

Signed-in users manage keys at https://www.mapsdata.io/api-access. The interface can create multiple named keys, reveal and copy a key, rename it, revoke it, and attribute usage in API analytics. Keys share the owning account's plan, credits, active-job allowance, and account-wide rate limit.

Never put an API key in browser code, a Git repository, a screenshot, an analytics event, a public prompt, or application logs. Store it in a server-side secret manager or runtime environment. If exposed, revoke it, create a replacement, update the integration, and inspect recent API activity.

## API Endpoints

### `GET /account`

Returns the current plan code and name, subscription state, billing interval, total allowance, remaining credits, current per-search maximum, free-search state, renewal or cancellation information, and account usage totals. Call this before creating a large job. Treat it as the runtime source of truth.

### `GET /locations?q={query}&country={country}`

Returns location choices compatible with the Mapsdata UI. Use the returned `label` as `input.location` and `country_code` as `input.countryCode`. For example, a New York lookup returns the label `New York, New York`.

### `GET /categories?q={query}`

Returns normalized Google business categories matching a search term. Use this when a user wants category suggestions rather than an unrestricted free-text niche.

### `POST /searches`

Creates an asynchronous discovery-only or full-pipeline job and returns `202 Accepted`, a `job_id`, initial status, and reserved-credit count. Production requests require a stable `Idempotency-Key`.

### `GET /searches`

Lists searches created through the public API for the authenticated account.

### `GET /searches/{search_id}`

Returns live job status, result and enrichment counts, credit charge, input, timestamps, and terminal errors.

### `GET /searches/{search_id}/results`

Returns a page of partial or completed business records. Continue while `has_more` is true. Page again from the beginning after completion because active records can gain enrichment values.

### `POST /enrichments`

Creates an asynchronous standalone enrichment job for 1 to 700 supplied business-name and website pairs. It returns `202 Accepted`, a job ID, submitted count, reserved-credit count, and a dashboard-visibility message.

### `GET /enrichments`

Lists standalone enrichment jobs created through the public API for the authenticated account.

### `GET /enrichments/{job_id}`

Returns live progress and terminal state for a standalone enrichment job.

### `GET /enrichments/{job_id}/results`

Returns paginated supplied businesses and their current enrichment fields using the same result shape as search jobs.

## Safe API Workflow

1. Call `GET /account` and read `credits_remaining` plus `max_results_per_search`.
2. For a Google Maps search, resolve the user's place through `GET /locations`.
3. Create one job with a stable `Idempotency-Key` and persist the returned ID.
4. Poll the matching status endpoint every 5 to 10 seconds.
5. When live display matters, read page 1 of results during processing.
6. Honor rate-limit headers and `Retry-After`.
7. After `completed` or `failed`, fetch results again from page 1.
8. Continue pagination until `has_more` is false and confirm the accumulated count equals `total`.
9. Do not create a replacement solely because polling timed out. Resume by job ID or retry creation with the original body and key.

## Idempotency

`POST /searches` and `POST /enrichments` require an `Idempotency-Key` in production. Retrying the same logical request with the same body and key returns the existing job without charging twice. Reusing a key with a different name, input, business list, or enrichment choice returns `409 Conflict`.

## Plans and Pricing

### Free

- Price: $0.
- Allowance: one lifetime 100-credit job.
- Search size: exactly 100 requested businesses for the free search.
- The free allowance can fund one full search, one discovery-only search, or one standalone enrichment job, but not a discovery job followed by a second free enrichment job.

### Starter

- Monthly: $45 per month.
- Yearly: $405 charged once per year, equivalent to $33.75 per month.
- Allowance: 10,000 lead credits per month.
- Maximum: 700 businesses per search or enrichment batch, subject to available credits.

### Growth

- Monthly: $115 per month.
- Yearly: $1,035 charged once per year, equivalent to $86.25 per month.
- Allowance: 50,000 lead credits per month.
- Maximum: 700 businesses per search or enrichment batch, subject to available credits.

### Scale

- Monthly: $295 per month.
- Yearly: $2,655 charged once per year, equivalent to $221.25 per month.
- Allowance: 200,000 lead credits per month.
- Maximum: 700 businesses per search or enrichment batch, subject to available credits.

Every paid plan includes business emails, owner and decision-maker names, owner and decision-maker emails, owner and decision-maker phone numbers, double email verification, CSV export, API access, and priority support.

Paid allowances reset monthly even when a yearly subscription is billed annually. Unused credits do not roll over and have no cash value. See https://www.mapsdata.io/pricing.md for the machine-readable pricing source and https://www.mapsdata.io/terms for contractual details.

## Credit Rules

- On an active paid plan, one requested search result costs one lead credit.
- Standalone enrichment reserves one lead credit per submitted business.
- Paid job creation reserves the full requested or submitted count before work enters the queue.
- Searches must request at least 100 businesses. A smaller `maxResults` returns `422` before job creation or reservation.
- Paid jobs cannot exceed 700 businesses, the plan maximum, or the remaining balance.
- If 700 credits remain and a request needs 1,000, the API returns `402` and explains the shortfall.
- If the balance is sufficient but the request exceeds the 700-business product ceiling, the API returns `403`.
- Successful jobs retain the reserved charge even if discovery returns fewer businesses than requested.
- Failed jobs follow Mapsdata's refund path, including restoration of free-search eligibility where applicable.
- Reading the account, locations, categories, lists, status, or results does not consume lead credits.

## Request and Concurrency Limits

The account-wide API limit is 1,000 requests per rolling 60 seconds across every API key. There is no separate daily or monthly request cap. Creating additional keys does not increase throughput.

Successful responses include standard and compatibility headers describing the 1,000-request policy, remaining capacity, and reset time. When exhausted, the API returns `429 Too Many Requests` with `Retry-After`.

Search and enrichment creation also share an account-wide active-job limit. If every slot is occupied, creation returns `429` with `Retry-After: 10`. Continue polling existing work and submit the next job after a job becomes terminal.

Use exponential backoff with jitter for `429` and transient `5xx` responses. Preserve both body and idempotency key when retrying a creation request.

## HTTP Status Summary

- `200`: Read succeeded.
- `202`: Search or enrichment accepted, including an idempotent retry that returned its existing job.
- `401`: API key missing, invalid, revoked, or orphaned.
- `402`: Insufficient credits or inactive paid subscription.
- `403`: Free-plan, plan, or product job-size limit exceeded.
- `404`: Job not found for this account, or the wrong endpoint family was used.
- `409`: Idempotency key reused with a different request.
- `422`: Query, path, or JSON validation failed, including a search below 100 results.
- `428`: Production creation request omitted `Idempotency-Key`.
- `429`: Rolling request limit or active-job limit reached.
- `503`: Required production service unavailable.

## Example Search

```bash
curl -X POST "https://www.mapsdata.io/api/v1/searches" \
  -H "Content-Type: application/json" \
  -H "x-api-key: md_live_your_key" \
  -H "Idempotency-Key: chicago-plumbers-2026-10-01" \
  -d '{
    "name": "Chicago plumbers",
    "input": {
      "query": "plumbers",
      "location": "Chicago, Illinois",
      "countryCode": "US",
      "maxResults": 100,
      "language": "en"
    },
    "enrich_contacts": true
  }'
```

The response returns `202 Accepted` with a `job_id`. Poll `GET /searches/{job_id}` and read `GET /searches/{job_id}/results?page=1&page_size=500` until the job is terminal and all pages are collected.

## Example Standalone Enrichment

```bash
curl -X POST "https://www.mapsdata.io/api/v1/enrichments" \
  -H "Content-Type: application/json" \
  -H "x-api-key: md_live_your_key" \
  -H "Idempotency-Key: supplied-businesses-2026-10-01" \
  -d '{
    "name": "Businesses to enrich",
    "businesses": [
      {
        "business_name": "Example Plumbing Company",
        "website_url": "https://example.com"
      }
    ]
  }'
```

Poll `GET /enrichments/{job_id}` and page through `GET /enrichments/{job_id}/results`.

## Responsible Use and Limitations

Business and contact data changes frequently. Mapsdata does not guarantee that every result is complete, accurate, unique, current, or available for a specific niche. Search volume varies by business type and place. Users are responsible for reviewing results and complying with privacy, marketing, communications, data-protection, anti-spam, and other laws that apply to their use.

Do not use Mapsdata or its results for spam, harassment, discrimination, deception, or unlawful activity. Do not bypass credit limits, security measures, access controls, or service restrictions. Ask the user before exporting, transferring, or using lead data for outreach.

## Canonical Resources

- Product: https://www.mapsdata.io/
- Human-readable pricing: https://www.mapsdata.io/#pricing
- Machine-readable pricing: https://www.mapsdata.io/pricing.md
- API documentation: https://www.mapsdata.io/docs
- API access: https://www.mapsdata.io/api-access
- Product updates: https://www.mapsdata.io/updates
- Privacy: https://www.mapsdata.io/privacy
- Terms: https://www.mapsdata.io/terms
- Concise LLM index: https://www.mapsdata.io/llms.txt