API

MapsData API

Last updated: September 2, 2026

The MapsData API lets you submit a scrape, track it, and download the result from your own code. It is a small, deliberately boring JSON API: nine endpoints, bearer authentication, and the same validation and quota rules the dashboard uses. Anything you can start from the search form you can start from a script.

Included on the Scale plan. API keys are created in Settings once your workspace is on Scale or a custom plan. Every scrape counts against the same monthly lead allowance as the dashboard, so there is no separate API metering to reason about.

Quickstart

Three requests, start to finish. Create a key in Settings, then export it:

export MAPSDATA_KEY="mdk_live_..."

1. Check the category is scrapable

A scrape's query has to be a real Google Maps category, not free text. This is the single most common reason a submission is rejected, so it is worth one call up front.

curl -s https://mapsdata.ai/api/v1/categories/validate?name=plumber \
  -H "Authorization: Bearer $MAPSDATA_KEY"

{"valid": true, "canonical": "Plumber", "suggestions": []}

Submit the canonical spelling exactly as returned.

2. Start the scrape

curl -s -X POST https://mapsdata.ai/api/v1/jobs \
  -H "Authorization: Bearer $MAPSDATA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Plumber", "states": ["Texas"], "total_limit": 500}'

{"id": "8f2c...", "status": "queued", "progress": 0, ...}

You get 202 Accepted and a job id straight away. The scrape itself runs on our workers and takes anywhere from a few minutes to several hours. Add "dry_run": true to run every validation and quota check and see the resolved plan without creating a job or spending anything.

3. Poll, then download

curl -s https://mapsdata.ai/api/v1/jobs/8f2c... \
  -H "Authorization: Bearer $MAPSDATA_KEY"

{"id": "8f2c...", "status": "completed", "progress": 100,
 "lead_count": 480, "email_count": 151,
 "downloads": {"csv": true, "xlsx": true, ...}}

Once status is completed, ask for a link. It is a short-lived signed URL, returned as JSON rather than a redirect:

curl -s "https://mapsdata.ai/api/v1/jobs/8f2c.../download?format=csv" \
  -H "Authorization: Bearer $MAPSDATA_KEY"

{"url": "https://...", "expires_at": "...", "filename": "Plumber.csv"}

The link expires in fifteen minutes. Request a new one rather than storing it. We also email you when a scrape finishes, so polling is a convenience, not the only way to find out.

Endpoints

Method	Path	What it does
GET	`/api/v1/categories`	Search the Google Maps category list
GET	`/api/v1/categories/validate`	Resolve one term to its canonical spelling
GET	`/api/v1/regions`	Valid region names for a country
GET	`/api/v1/clients`	Client labels this key may file scrapes under
GET	`/api/v1/usage`	This cycle's allowance and per-scrape ceiling
POST	`/api/v1/jobs`	Submit a scrape
GET	`/api/v1/jobs`	List scrapes, newest first
GET	`/api/v1/jobs/{id}`	One scrape's current state
POST	`/api/v1/jobs/{id}/cancel`	Cancel a queued or running scrape
GET	`/api/v1/jobs/{id}/download`	A short-lived signed download link

The machine-readable contract is at https://mapsdata.ai/api/v1/openapi.json. It is an OpenAPI 3.1 document covering exactly these paths and nothing else, so you can generate a client from it.

Conventions

Base URL is https://mapsdata.ai/api/v1. Everything is HTTPS.
Authentication is Authorization: Bearer <key> on every request. See authentication.
Bodies are JSON. Unknown fields are rejected rather than ignored, so a typo in a field name is a loud error instead of a silent no-op.
Errors all share one envelope with a stable code. See errors and rate limits.
Times are ISO 8601 with an offset.

Where to go next

Authentication: creating keys, scopes, and keeping them safe.
Submitting a scrape: categories, regions, limits, and safe retries.
Polling and lifecycle: how long scrapes take and how to watch one sensibly.
Errors and rate limits: the full code table and what to do about each.
Connect an AI agent: use MapsData from Claude, Cursor or another assistant over MCP.

Try it on your own market

Create a free MapsData account and get 500 Google Maps leads with emails every month. No card needed.

Get 500 free leads a month