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: ny-plumbers-2026-10-01" \
-d '{
"name": "New York plumbers",
"input": {
"query": "plumbers",
"location": "New York, New York",
"countryCode": "US",
"maxResults": 100,
"language": "en"
},
"enrich_contacts": true
}'
{
"job_id": "c15dbb36-5a56-4720-b1af-b388bcaf78dc",
"status": "queued",
"credits_reserved": 100,
"message": "Search accepted. It is visible in your Mapsdata dashboard."
}
Endpoints
Create a search
Queue a Google Maps business search and contact enrichment job.
POST
/
searches
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: ny-plumbers-2026-10-01" \
-d '{
"name": "New York plumbers",
"input": {
"query": "plumbers",
"location": "New York, New York",
"countryCode": "US",
"maxResults": 100,
"language": "en"
},
"enrich_contacts": true
}'
{
"job_id": "c15dbb36-5a56-4720-b1af-b388bcaf78dc",
"status": "queued",
"credits_reserved": 100,
"message": "Search accepted. It is visible in your Mapsdata dashboard."
}
Creates an asynchronous search backed by the same queue, workers, credit balance, and result store as the Mapsdata dashboard. The response is
With
202 Accepted.
string
required
A stable unique value for one logical search. Use a UUID or a readable key such as
ny-plumbers-2026-10-01. Required in production.string
Dashboard list name, up to 200 characters. Defaults to
{query} in {location}.object
required
Search input shared with the web app.
Show input fields
Show input fields
string
required
Business type or search phrase, up to 300 characters.
string
required
Use the
label returned by GET /locations, for example New York, New York.string
Uppercase ISO two-letter country code, for example
US.integer
default:"100"
Requested businesses. Minimum
100; current product maximum 700, further bounded by plan and available credits.string
default:"en"
Two- or three-letter language code, optionally followed by a locale.
boolean
default:"true"
Set
true for the full discovery and enrichment pipeline. Set false for Google Maps business discovery only; returned enrichment status fields are not_requested.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: ny-plumbers-2026-10-01" \
-d '{
"name": "New York plumbers",
"input": {
"query": "plumbers",
"location": "New York, New York",
"countryCode": "US",
"maxResults": 100,
"language": "en"
},
"enrich_contacts": true
}'
{
"job_id": "c15dbb36-5a56-4720-b1af-b388bcaf78dc",
"status": "queued",
"credits_reserved": 100,
"message": "Search accepted. It is visible in your Mapsdata dashboard."
}
Credits and rejection behavior
- Free accounts receive one search of up to 100 requested businesses. The free search reserves 100 credits.
- Active paid accounts reserve the requested
maxResultsimmediately. - Requests below 100 return
422before a job is created or credits are reserved. - If 700 credits remain and
maxResultsis 1,000, the API returns402and explains that only 700 remain. - A request above the plan allowance or the 700-business product ceiling returns
403. - Rejected requests create no job and deduct no credits.
- Failed jobs follow the dashboard’s refund behavior; successful searches keep the reserved charge even if fewer businesses are returned.
Choose the workflow
| Goal | Request |
|---|---|
| Search Google Maps only | POST /searches with enrich_contacts: false |
| Search and enrich every result | POST /searches with enrich_contacts: true |
| Enrich businesses you already have | POST /enrichments |
enrich_contacts: false, Mapsdata still returns business name, category, address, phone, website, rating, review count, status, and Maps identifiers when the discovery provider supplies them. It skips website crawling, people and email discovery, public-source enrichment, and email verification. The job completes directly after import.
Safe retries
Sending the same body and idempotency key returns the existing job without charging twice. Reusing the key with a different name, input, or enrichment setting returns409 Conflict.
API-created jobs appear in Dashboard and Lead lists immediately. Partial businesses are imported and shown in the UI while the job is still running.