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

# Search Maps

> Retrieve map search results including coordinates and metadata.

## Description

This endpoint performs a Google Maps search using the provided query and optional parameters. It returns information about places matching the search criteria.

## Endpoint

```
POST https://app.dumplingai.com/api/v1/search-maps
```

## Headers

* **Content-Type:** `application/json`
* **Authorization:** Bearer `<API_KEY>` (required)

## Request Body

```json theme={null}
{
  "query": "string", // Required. The search query for Google Maps.
  "gpsPositionZoom": "string", // Optional.
  "placeId": "string", // Optional. Google Maps Place ID for a specific location.
  "cid": "string", // Optional. Google Maps CID (Client ID) for a specific location.
  "language": "string", // Optional. Language code for the search results (e.g., "en" for English).
  "page": "number" // Optional. Page number for paginated results.
}
```

## Responses

### Success (200)

Returns the search results from Google Maps.

```json theme={null}
{
  "searchParameters": {
    "q": "string",
    "type": "string",
    "engine": "string"
  },
  "ll": "string", // Optional. Returned if gpsPosition was provided.
  "places": [
    {
      "position": "number",
      "title": "string",
      "address": "string",
      "latitude": "number",
      "longitude": "number",
      "type": "string", // Optional
      "types": ["string"], // Optional
      "website": "string", // Optional
      "openingHours": {
        // Optional
        "day": "string"
      },
      "thumbnailUrl": "string", // Optional
      "cid": "string",
      "fid": "string", // Optional
      "placeId": "string" // Optional
    }
  ]
}
```

* **Content-Type:** application/json
* **X-RateLimit-Limit:** The rate limit for the user.
* **X-RateLimit-Remaining:** The remaining number of requests for the user.

### Bad Request (400)

Returned if the request is invalid.

```json theme={null}
{
  "error": "query parameter is required"
}
```

### Unauthorized (401)

Returned if the API key is invalid or missing.

```json theme={null}
{
  "error": "Invalid or missing Authorization header"
}
```

### Internal Server Error (500)

Returned if there's an error during the search process.

```json theme={null}
{
  "error": "Failed to perform maps search: [error message]"
}
```

## Example Request

```bash theme={null}
curl -X POST https://app.dumplingai.com/api/v1/search-maps \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "query": "coffee shops in New York",
  "language": "en"
}'
```

## Notes

* This endpoint uses 100 credits per page of results.
* The `gpsPositionZoom` parameter should be provided in the format @latitude,longitude,zoom. For example:@40.6973709,-74.1444871,11z.
  * You can find a search area by going to Google Maps, dragging around the map to your desired location, and then looking at the URL to get the coordinates. The zoom level, while optional, is recommended for higher precision. It ranges from 3z (completely zoomed out) to 21z (completely zoomed in). Setting the search area with this parameter only applies to search queries with q, not when you look up by placeId or cid.
  * This parameter is required if using pagination.
* If `placeId` or `cid` is provided, the search will focus on that specific location.
* The `language` parameter can be used to specify the desired language for the search results.
* Usage is recorded with detailed parameters for each request.
* Events may be logged for analytics purposes if enabled.

## Rate Limiting

Rate limit headers (`X-RateLimit-Limit` and `X-RateLimit-Remaining`) are included in the response to indicate the user's current rate limit status.


## OpenAPI

````yaml POST /api/v1/search-maps
openapi: 3.0.3
info:
  title: DumplingAI API
  version: 1.0.0
  description: >
    REST API for DumplingAI's content intelligence and automation platform.

    All endpoints are grouped under `/api/v1`; most are secured via Bearer API
    keys unless an operation explicitly sets `security: []`.
servers:
  - url: https://app.dumplingai.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: YouTube
    description: Access metadata, search results, and transcripts from YouTube.
  - name: TikTok
    description: Retrieve TikTok profile, video, follower, and transcript data.
  - name: LinkedIn
    description: Programmatically fetch LinkedIn company and profile data.
  - name: Search
    description: Search-orientated endpoints spanning web, news, maps, and autocomplete.
  - name: Google
    description: Integrations with Google business listings and location data.
  - name: Scraping
    description: Webpage capture, crawling, and structured content extraction utilities.
  - name: Documents
    description: Document processing, conversion, and metadata utilities.
  - name: AI
    description: DumplingAI agent and knowledge base endpoints.
  - name: Developer Tools
    description: Utilities for executing sandboxed code via API.
paths:
  /api/v1/search-maps:
    post:
      tags:
        - Search
      summary: Search maps
      description: Retrieve map search results including coordinates and metadata.
      operationId: searchMaps
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MapsSearchRequest'
            examples:
              default:
                value:
                  query: dumpling restaurants
                  gpsPositionZoom: '@40.7128,-74.0060,13z'
                  language: en
      responses:
        '200':
          description: Map search results returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MapsSearchResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    MapsSearchRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
        gpsPositionZoom:
          type: string
          description: Combined latitude,longitude,zoom string forwarded as `ll`.
        placeId:
          type: string
        cid:
          type: string
        language:
          type: string
        page:
          type: integer
          minimum: 1
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    MapsSearchResponse:
      type: object
      properties:
        searchParameters:
          type: object
          properties:
            q:
              type: string
            type:
              type: string
            engine:
              type: string
          required:
            - q
            - type
            - engine
          additionalProperties: true
        ll:
          type: string
          nullable: true
        places:
          type: array
          items:
            $ref: '#/components/schemas/MapsPlaceResult'
      required:
        - searchParameters
        - places
      additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable description of what went wrong.
      required:
        - error
    RequestSource:
      type: string
      description: Optional identifier describing where the API request originated.
      enum:
        - API
        - WEB
        - MAKE_DOT_COM
        - ZAPIER
        - N8N
        - PLAYGROUND
        - DEFAULT_AUTOMATION
        - AGENT_PREVIEW
        - AGENT_LIVE
        - AUTOPILOT
        - STUDIO
    MapsPlaceResult:
      type: object
      properties:
        position:
          type: integer
        title:
          type: string
        address:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        type:
          type: string
          nullable: true
        types:
          type: array
          items:
            type: string
        website:
          type: string
          format: uri
          nullable: true
        openingHours:
          type: object
          additionalProperties:
            type: string
        thumbnailUrl:
          type: string
          format: uri
          nullable: true
        cid:
          type: string
        fid:
          type: string
          nullable: true
        placeId:
          type: string
          nullable: true
      required:
        - position
        - title
        - address
        - latitude
        - longitude
        - cid
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````