> ## Documentation Index
> Fetch the complete documentation index at: https://developer.salesforge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search local businesses on Google Maps

> Asynchronous. Starts a Google Maps search within radiusKm of the lat/lng coordinates and returns 202 with the job; poll GET /maps-discovery/jobs/{jobID} or pass webhookURL, then page through GET /maps-discovery/jobs/{jobID}/results. Send lat and lng: an omitted value is read as 0, which is a valid coordinate.

Send keywords, categories, or both; at least one is required. keywords are searched as typed and every place Google returns for them is kept. categories restrict the results to those Google Maps categories (GET /maps-discovery/filters/categories). Without keywords, a category that is not a Google Maps category is searched as a keyword; with keywords it is rejected with 400. foundCount is at most limit and can be lower when the area has fewer matching places.

Consumes credits: your account's maps discovery price per business found. The job reserves the price for limit businesses and settles for the businesses actually found.

Idempotency-Key: a job with the same key in your account is returned as is, whatever the request body as long as it is valid, for as long as that job exists; a request that is rejected frees its key. A repeat does not count against the concurrent jobs limit, but it is still subject to the rate limit and can get 429; retry it with the same key.

Webhook: POST with JSON body when the job ends, 2xx = delivered. Delivery is tried up to 3 times on 5xx, 429 or network errors, each attempt waiting up to 8 seconds for a response; there is no later redelivery, so poll GET /maps-discovery/jobs/{jobID} if you miss it. Redirects are not followed. Every attempt carries an X-Webhook-Delivery-Id header equal to jobID. webhookURL must be a public http or https URL with a domain name, not an IP address, or the request fails with 400; use https. Payload: jobID (string), status (completed|failed|no_results), foundCount (int), limit (int), consumedCredits (number), error (string, present on failed and no_results).

The search creates a list named "Public API: Local Businesses" in the app.



## OpenAPI

````yaml https://api.leadsforge.ai/public/swagger/doc.json post /maps-discovery/search
openapi: 3.1.0
info:
  description: >-
    Search B2B leads, find their work emails, phone numbers and LinkedIn
    profiles, and discover lookalike companies, company page followers and local
    businesses.


    Authenticate every request with your API key in the `Authorization` header:
    the raw key, no `Bearer` prefix. Create the key in the Leadsforge app under
    Settings -> API & MCP.


    Paid operations consume credits from your account balance, and each
    operation says whether it is paid. Long-running operations are asynchronous:
    they return a job that you poll (or receive by webhook) and then page
    through its results.


    Errors return a JSON body with a human-readable `message` and, except for an
    unknown path (404), a stable `code`. Program against `code`. A JSON body
    with a field the operation does not accept is rejected with 400 bad_request,
    listing the unknown fields in data.validations. A request still running when
    the server timeout is reached is cut off with 503 and an empty body.
  license:
    name: Proprietary
    url: https://www.leadsforge.ai/terms
  termsOfService: https://www.leadsforge.ai/terms
  title: Leadsforge API
  version: '1.0'
servers:
  - url: https://api.leadsforge.ai/public/v1
security: []
tags:
  - description: Your account's credit balance.
    name: Balance
  - description: >-
      Find people by role, seniority, company, location and other filters.
      Searches and counts are free up to a monthly allowance, then each one
      costs credits; finding contact details is charged separately.
    name: Search
  - description: >-
      Accepted values for the controlled filters of POST /search and POST
      /search/count, and a resolver for location strings. All free.
    name: Search filters
  - description: >-
      Find work emails, phone numbers and LinkedIn profiles. Asynchronous jobs
      take up to 500 people; synchronous calls take one person and answer in the
      same response.
    name: Enrichment
  - description: >-
      Find companies similar to the domains you give. Previews are free up to a
      monthly allowance, then each one costs credits; the search consumes
      credits per company returned.
    name: Lookalikes
  - description: >-
      Find the people who follow a LinkedIn company page. Asynchronous jobs that
      consume credits per follower collected.
    name: Company followers
  - description: >-
      Find local businesses in an area you choose, then find their owners'
      emails and phone numbers. Both steps are asynchronous jobs that consume
      credits.
    name: Maps discovery
  - description: Scrape LinkedIn Sales Navigator searches.
    name: salesnav
externalDocs:
  description: Leadsforge API guides
  url: >-
    https://developer.salesforge.ai/leadsforge-api/concepts/search-and-enrichment
paths:
  /maps-discovery/search:
    post:
      tags:
        - Maps discovery
      summary: Search local businesses on Google Maps
      description: >-
        Asynchronous. Starts a Google Maps search within radiusKm of the lat/lng
        coordinates and returns 202 with the job; poll GET
        /maps-discovery/jobs/{jobID} or pass webhookURL, then page through GET
        /maps-discovery/jobs/{jobID}/results. Send lat and lng: an omitted value
        is read as 0, which is a valid coordinate.


        Send keywords, categories, or both; at least one is required. keywords
        are searched as typed and every place Google returns for them is kept.
        categories restrict the results to those Google Maps categories (GET
        /maps-discovery/filters/categories). Without keywords, a category that
        is not a Google Maps category is searched as a keyword; with keywords it
        is rejected with 400. foundCount is at most limit and can be lower when
        the area has fewer matching places.


        Consumes credits: your account's maps discovery price per business
        found. The job reserves the price for limit businesses and settles for
        the businesses actually found.


        Idempotency-Key: a job with the same key in your account is returned as
        is, whatever the request body as long as it is valid, for as long as
        that job exists; a request that is rejected frees its key. A repeat does
        not count against the concurrent jobs limit, but it is still subject to
        the rate limit and can get 429; retry it with the same key.


        Webhook: POST with JSON body when the job ends, 2xx = delivered.
        Delivery is tried up to 3 times on 5xx, 429 or network errors, each
        attempt waiting up to 8 seconds for a response; there is no later
        redelivery, so poll GET /maps-discovery/jobs/{jobID} if you miss it.
        Redirects are not followed. Every attempt carries an
        X-Webhook-Delivery-Id header equal to jobID. webhookURL must be a public
        http or https URL with a domain name, not an IP address, or the request
        fails with 400; use https. Payload: jobID (string), status
        (completed|failed|no_results), foundCount (int), limit (int),
        consumedCredits (number), error (string, present on failed and
        no_results).


        The search creates a list named "Public API: Local Businesses" in the
        app.
      operationId: startMapsSearch
      parameters:
        - description: >-
            Idempotency key - if a job with this key already exists in your
            account, the existing job is returned as is; use a new key to start
            a new job
          in: header
          name: Idempotency-Key
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartMapsDiscoverySearchRequest'
              description: Search request
              summary: body
        description: Search request
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MapsSearchJobResponse'
          description: Job created
          headers:
            Location:
              description: Path of the new job, same as statusURL
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: 'bad_request: the body or a parameter is invalid'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            missing_api_key, invalid_api_key, or unauthorized when your account
            is blocked
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            insufficient_credits: the balance does not cover the credits this
            request reserves
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            account_frozen: credit spending is paused for your account; contact
            support
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            rate_limited: too many requests (retry later; Retry-After is set
            when known), or your account already runs its maximum number of
            concurrent searches, including searches started in the app
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: 'internal: unexpected server error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    StartMapsDiscoverySearchRequest:
      properties:
        categories:
          description: >-
            Categories restrict results to Google Maps categories (GET
            /maps-discovery/filters/categories). Without keywords, a value that
            is not a Google category is searched as a keyword; with keywords it
            is rejected with 400.
          example:
            - dentist
            - dental clinic
          items:
            type: string
          maxItems: 100
          type: array
          uniqueItems: false
        clientRequestID:
          example: req_12345
          maxLength: 128
          type: string
        keywords:
          description: >-
            Keywords are free-text Google Maps searches; every place Google
            returns for them is kept. At least one keyword or category is
            required.
          example:
            - emergency plumber
          items:
            type: string
          maxItems: 100
          type: array
          uniqueItems: false
        language:
          example: en
          maxLength: 10
          type: string
        lat:
          description: >-
            Lat is the latitude of the search center. Send it explicitly: an
            omitted value is read as 0.
          example: 40.758
          maximum: 90
          minimum: -90
          type: number
        limit:
          example: 200
          maximum: 5000
          minimum: 1
          type: integer
        lng:
          description: >-
            Lng is the longitude of the search center. Send it explicitly: an
            omitted value is read as 0.
          example: -73.9855
          maximum: 180
          minimum: -180
          type: number
        radiusKm:
          description: >-
            RadiusKm is the search radius in kilometres, greater than 0 and at
            most 500.
          example: 5
          maximum: 500
          type: number
        webhookURL:
          example: https://example.com/webhooks/maps-search
          type: string
      required:
        - limit
        - radiusKm
      type: object
    MapsSearchJobResponse:
      properties:
        categories:
          example:
            - dentist
            - dental clinic
          items:
            type: string
          type: array
          uniqueItems: false
        clientRequestID:
          example: req_12345
          type: string
        completedAt:
          type: string
        consumedCredits:
          type: number
        createdAt:
          example: '2026-09-13T12:00:00Z'
          type: string
        error:
          description: Error is set on failed and no_results jobs.
          type: string
        foundCount:
          example: 143
          type: integer
        jobID:
          example: 5f1c2e3a-0b1d-4c2e-9f3a-1b2c3d4e5f60
          type: string
        keywords:
          example:
            - emergency plumber
          items:
            type: string
          type: array
          uniqueItems: false
        language:
          example: en
          type: string
        lat:
          example: 40.758
          type: number
        limit:
          example: 200
          type: integer
        lng:
          example: -73.9855
          type: number
        radiusKm:
          example: 5
          type: number
        reservedCredits:
          type: number
        resultsURL:
          example: >-
            /public/v1/maps-discovery/jobs/5f1c2e3a-0b1d-4c2e-9f3a-1b2c3d4e5f60/results
          type: string
        status:
          enum:
            - in_progress
            - completed
            - failed
            - no_results
          example: in_progress
          type: string
        statusURL:
          example: /public/v1/maps-discovery/jobs/5f1c2e3a-0b1d-4c2e-9f3a-1b2c3d4e5f60
          type: string
        updatedAt:
          example: '2026-09-13T12:01:00Z'
          type: string
        webhookURL:
          example: https://example.com/webhooks/maps-search
          type: string
      type: object
    ApiError:
      properties:
        code:
          description: >-
            Code is the stable, machine-readable error code; each endpoint lists
            the codes it returns.
          type: string
        data:
          description: >-
            Data carries details for some errors; on validation errors it is
            {"validations": ["..."]}, one message per

            invalid field.
        message:
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: >-
        Your API key, sent as is (no `Bearer` prefix). Create it in the
        Leadsforge app under Settings -> API & MCP.
      in: header
      name: Authorization
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.