---
title: "Search local businesses on Google Maps"
method: POST
path: "/maps-discovery/search"
tags: ["maps-discovery"]
---

# Search local businesses on Google Maps

`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)

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.

## Headers

- `Idempotency-Key` string

## Request body

- StartMapsDiscoverySearchRequest
  - `categories` string[], required: Categories are OR-combined. Recommended values: GET /maps-discovery/filters/categories; free text is accepted too.
  - `clientRequestID` string
  - `language` string
  - `lat` number
  - `limit` integer, required
  - `lng` number
  - `radiusKm` number, required
  - `webhookURL` string

## Response `202`

Job created

- MapsSearchJobResponse
  - `categories` string[]
  - `clientRequestID` string
  - `completedAt` string
  - `consumedCredits` number
  - `createdAt` string
  - `error` string
  - `foundCount` integer
  - `jobID` string
  - `language` string
  - `lat` number
  - `limit` integer
  - `lng` number
  - `radiusKm` number
  - `reservedCredits` number
  - `resultsURL` string
  - `status` 'in_progress' | 'completed' | 'failed' | 'no_results'
  - `statusURL` string
  - `updatedAt` string
  - `webhookURL` string

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `402`: Insufficient credits
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/leadsforge/apis/leadsforge-api.md) - [All operations](https://skmtc.dev/leadsforge/apis/leadsforge-api/llms.txt) - [OpenAPI document](https://skmtc.dev/leadsforge/apis/leadsforge-api/revisions/b4a6596215b5?raw)