Core

Searches

A search runs one maps query (Google, Bing, or Apple) and extracts every matching business.

Creating a job requires an active subscription (or trial) and available credits. The job starts in pending and moves through running to completed or failed.

Create a job

POST/v1/searches

Request body

Field	Type	Description
provider	string?	Map source: "google" (default), "bing", or "apple".
keyword	string	Required. The search query, e.g. "design agencies".
location	string?	Optional location to bias the search, e.g. "New York, NY".
lang	string?	Optional language code (default "en").
options.maxResults	number?	Cap on extracted leads (default 200).
options.enrichEmail	boolean?	Enrich each lead with emails from its website (paid plans).
options.enrichSocials	boolean?	Enrich each lead with social profiles (paid plans).

Job object

Field	Type	Description
id	string	Job id — use it to poll, read leads, or export.
provider	string	Map source the job ran against: google · bing · apple.
status	string	pending · running · completed · failed · canceled.
keyword	string	The search query.
location	string \| null	The search location.
language	string	The language code used.
maxResults	number \| null	The configured result cap.
resultCount	number	Number of leads extracted (once completed).
error	string \| null	Failure reason, if the job failed.
createdAt	string	ISO 8601 timestamp.

Read & manage searches

GET/v1/searches

GET/v1/searches/:id

POST/v1/searches/:id/cancel

DELETE/v1/searches/:id

GET /v1/searches returns { "data": [ search, ... ] } — the 50 most recent. Only failed searches can be deleted.

Query parameters

Field	Type	Description
provider	string?	Source maps to keep, comma-separated: google · apple · bing. Omit for all three.

What one search produced

Both of these are scoped to a single search — they are sub-resources of it, not a namespace of their own. For everything this account owns, searches and dataset unlocks alike, use GET /v1/leads instead.

GET/v1/searches/:id/leads

Field	Type	Description
limit	number?	Page size (1–1000, default 100).
offset	number?	Rows to skip (default 0).

Returns { "data": [ lead, ... ], "total": number }. The lead object is documented on the Leads page — it is the same shape everywhere.

GET/v1/searches/:id/export

The response is the file itself, with a Content-Disposition attachment header.

Field	Type	Description
format	csv \| xlsx \| json	Output format (default csv).
leadIds	string (repeatable)	Optional. ?leadIds=a&leadIds=b to export only those leads.

cURL — download XLSX

curl "https://api.mapleads.ai/v1/searches/SEARCH_ID/export?format=xlsx" \
  -H "Authorization: Bearer mapleads_xxx" \
  -o leads.xlsx

cURL — create

curl https://api.mapleads.ai/v1/searches \
  -X POST \
  -H "Authorization: Bearer mapleads_xxx" \
  -H "Content-Type: application/json" \
  -d '{"provider":"bing","keyword":"coffee shops","location":"Brooklyn"}'

PreviousQuickstart Next Businesses