​
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 /api/v1/search-maps

​
Headers

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

​
Request Body

{
  "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.

{
  "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.

{
  "error": "query parameter is required"
}

​
Unauthorized (401)

Returned if the API key is invalid or missing.

{
  "error": "Invalid or missing Authorization header"
}

​
Internal Server Error (500)

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

{
  "error": "Failed to perform maps search: [error message]"
}

​
Example Request

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 10 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.

SearchSearch Places