DocumentationAPI Reference
Searches

Create a search

Starts one asynchronous maps search. The job begins in pending; poll the returned job URL until it reaches completed or failed. Creating a job requires an active subscription or trial, and available credits. Requires the searches:write scope when called with a scoped key.

POST/v1/searches

Starts one asynchronous maps search. The job begins in pending; poll the returned job URL until it reaches completed or failed. Creating a job requires an active subscription or trial, and available credits. Requires the searches:write scope when called with a scoped key.

Authorization

AuthorizationBearer <token>

Pass Authorization: Bearer mapleads_xxx.

In: header

Request Body

application/json

Maps query and extraction options.

TypeScript Definitions

Use the request body type in TypeScript.

provider?string

Map source to search.

Default"google"

Value in

  • "google"
  • "bing"
  • "apple"
keyword*string

Business category or search query.

Length1 <= length <= 200
location?|

Optional city, region, address, or postal-code hint.

Lengthlength <= 200
country?|

Optional two-letter country code.

Match^[A-Za-z]{2}$
lang?string

Language code used for the maps query.

Length2 <= length <= 10
Default"en"
options?
conversationId?string

Links this search to an assistant conversation you own. Optional, and only meaningful to the MapLeads dashboard — API integrations can ignore it. A conversation id belonging to another account is rejected.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/searches" \  -H "Content-Type: application/json" \  -d '{    "provider": "google",    "keyword": "design agencies",    "location": "New York, NY",    "country": "US",    "lang": "en",    "options": {      "maxResults": 100,      "enrichEmail": true,      "enrichSocials": true    }  }'
{  "id": "018f275d-5475-7dc8-bd84-4f319efab001",  "provider": "google",  "status": "pending",  "keyword": "design agencies",  "location": "New York, NY",  "language": "en",  "maxResults": 100,  "resultCount": 0,  "error": null,  "createdAt": "2026-08-01T10:00:00Z",  "progress": {    "phase": "searching",    "found": 0,    "processed": 0,    "failed": 0  }}

List searches GET

Returns up to the 50 most recent searches owned by the authenticated user. Requires the `searches:read` scope when called with a scoped key.

Get a search GET

Returns the current job state and customer-facing progress counters. Requires the `searches:read` scope when called with a scoped key.