---
title: "Start a Maps Discovery search"
method: POST
path: "/v1/maps-discovery/search"
tags: ["maps-discovery"]
---

# Start a Maps Discovery search

`POST /v1/maps-discovery/search`

## Request

- Base URL: `https://api.leadsforge.ai`
- URL: `https://api.leadsforge.ai/v1/maps-discovery/search`
- Auth: API key in header `Authorization`

Reserves credits and submits an async Google Maps search for the configured radius and categories (OR-combined).

## Request body

- StartMapsSearchRequest
  - `categories` string[], required: Categories are OR-combined: a business matching any of them is returned. `min=1` on the slice rejects an empty array: go-playground's `required` only checks for a non-nil slice, so a present-but-empty `"categories": []` would otherwise slip through to the domain validation and surface as a 500 instead of a 400. `max=100` bounds the count so an unbounded OR list cannot balloon the async job / provider query - generous enough that a real customer never hits it.
  - `language` string
  - `lat` number: Lat / Lng omit the `required` validator on purpose: go-playground's `required` treats zero as missing, which would 400 valid searches on the equator (lat=0) or the Greenwich meridian (lng=0, e.g. London). The min/max bounds still reject out-of-range values.
  - `limit` integer, required
  - `listID` string: ListID re-searches into an existing maps discovery list (new search job, same list). Empty creates a fresh list, returned as listID so the search appears in the sidebar.
  - `lng` number
  - `radiusKm` number, required

## Response `200`

OK

- StartMapsSearchResponse
  - `limitRequested` integer
  - `listID` string
  - `maxCostCredits` number
  - `requestID` string
  - `unitPriceCredits` number

## Other responses

- `400`: Bad Request
- `402`: Insufficient credits
- `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)