maps-discovery

Search local businesses on Google Maps

Starts an async Google Maps search for businesses of the given categories within radiusKm of the coordinates. Credits are reserved for the limit (maps discovery price per business) and settled for the businesses actually found. Supports idempotency via the Idempotency-Key header (a repeat with the same key returns the existing job) and webhook notifications via webhookURL (POST with JSON body on completion or failure, retried up to 10 times with exponential backoff, 2xx = success). Webhook payload: jobID (string), status (completed|failed|no_results), foundCount (int), limit (int), consumedCredits (number), error (string, failure only). The search creates a list named "Public API: Local Businesses" in the app.

post/maps-discovery/search

Request

  • Base URL: https://api.leadsforge.ai
  • URL: https://api.leadsforge.ai/maps-discovery/search
  • Auth: ApiKeyAuth (a scheme the document does not define)

Headers

Idempotency-Keystring

Idempotency key - if a job with this key already exists for this account, the existing job is returned as-is, use a new key to start a new search

Request body

categoriesstring[] required

Categories are OR-combined. Recommended values: GET /maps-discovery/filters/categories; free text is accepted too.

clientRequestIDstring
languagestring
latnumber
limitinteger required
lngnumber
radiusKmnumber required
webhookURLstring

Example request

{
  "categories": [
    "Dentist",
    "Dental Clinic"
  ],
  "clientRequestID": "req_12345",
  "language": "en",
  "lat": 40.758,
  "limit": 200,
  "lng": -73.9855,
  "radiusKm": 5,
  "webhookURL": "https://example.com/webhooks/maps-search"
}

Response

Job created

categoriesstring[]
clientRequestIDstring
completedAtstring
consumedCreditsnumber
createdAtstring
errorstring
foundCountinteger
jobIDstring
languagestring
latnumber
limitinteger
lngnumber
radiusKmnumber
reservedCreditsnumber
resultsURLstring
status'in_progress' | 'completed' | 'failed' | 'no_results'
statusURLstring
updatedAtstring
webhookURLstring

Example response

{
  "categories": [
    "Dentist",
    "Dental Clinic"
  ],
  "clientRequestID": "req_12345",
  "completedAt": "2026-09-13T12:05:00Z",
  "consumedCredits": 143,
  "createdAt": "2026-09-13T12:00:00Z",
  "foundCount": 143,
  "jobID": "5f1c2e3a-0b1d-4c2e-9f3a-1b2c3d4e5f60",
  "language": "en",
  "lat": 40.758,
  "limit": 200,
  "lng": -73.9855,
  "radiusKm": 5,
  "reservedCredits": 200,
  "resultsURL": "/public/v1/maps-discovery/jobs/5f1c2e3a-0b1d-4c2e-9f3a-1b2c3d4e5f60/results",
  "status": "in_progress",
  "statusURL": "/public/v1/maps-discovery/jobs/5f1c2e3a-0b1d-4c2e-9f3a-1b2c3d4e5f60",
  "updatedAt": "2026-09-13T12:01:00Z",
  "webhookURL": "https://example.com/webhooks/maps-search"
}

Changes

No recorded changes to this operation across all 1 revision of this API.