Endpoints
Search Places
Description
This endpoint performs a Google Places search using the provided query and optional parameters. It returns information about places matching the search criteria.
Endpoint
POST /api/v1/search-places
Headers
- Content-Type:
application/json
- Authorization: Bearer
<API_KEY>
(required)
Request Body
{
"query": "string", // Required. The search query for Google Places.
"country": "string", // Optional. Country code for location bias (e.g., "US" for United States).
"location": "string", // Optional. Specific location to focus the search (e.g., "New York, NY").
"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 Places.
{
"searchParameters": {
"q": "string",
"gl": "string", // Optional. Country code if provided.
"type": "string",
"location": "string", // Optional. Location if provided.
"engine": "string"
},
"places": [
{
"position": "number",
"title": "string",
"address": "string",
"latitude": "number",
"longitude": "number",
"website": "string", // Optional
"cid": "string",
"rating": "number", // Optional
"ratingCount": "number", // Optional
"category": "string", // Optional
"phoneNumber": "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 places search: [error message]"
}
Example Request
curl -X POST https://app.dumplingai.com/api/v1/search-places \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"query": "pizza restaurants",
"country": "US",
"location": "Chicago, IL",
"language": "en"
}'
Notes
- This endpoint uses 3 credits per page of results.
- The
country
parameter should be a two-letter country code (e.g., “US” for United States). - The
location
parameter can be used to focus the search on a specific area. You can find a list of supported locations at GET:/api/v1/google-locations
- 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.
- Pagination details (
page
parameter) are recorded but do not affect the API call to the search service.
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.