The search_places tool lets an LLM find places on Google Maps from a natural
language query. The tool returns an AI-generated summary of the matching places.
For each place that the summary cites, it also returns the place ID,
latitude/longitude coordinates, Google Maps links, and attribution.
You can call search_places through the MCP server or as the searchText REST
method. This page describes the request options, including the
Pro options;
what the response contains; and how requests are billed. For the full schemas,
see the
search_places MCP reference
and the
searchText REST reference.
Request options
The LLM sets these options when it calls the tool, based on the user's request and the tool description. You can influence which options the model uses with your own instructions; see Control Pro usage.
The following table describes the request options for search_places:
| Option | Description |
|---|---|
text_query |
Required. The search query—for example, coffee shops near Golden Gate Park. The query must contain enough location information to be unambiguous, or the request must include location_bias. |
location_bias |
A circle (center and optional radius_meters, up to 50,000 meters) to bias results toward. If text_query names an explicit location, that location is used instead. |
language_code |
The language of the summary—for example, en or ja. Defaults to English. |
region_code |
The CLDR region code of the user—for example, US. Affects region-specific place names and can affect results based on applicable law. |
page_size |
The maximum number of places to return. The default is 5. Values from 6 to 10 are a Pro option. Values above 10 return an INVALID_ARGUMENT error. The service might return fewer places than requested. |
include_extended_details |
When true, the summary includes extended place details. This is a Pro option. Defaults to false. |
Pro options
Two options select the Maps Grounding Pro SKU. A request that uses either or both is billed under the Pro SKU:
| Pro option | When to use it |
|---|---|
include_extended_details set to true |
The user's request needs extended place details, such as insights from reviews, menu highlights, atmosphere, or visitor tips. |
page_size from 6 to 10 |
The user wants to compare more than 5 places. |
Requests that use neither option, including requests with a page_size from 1
to 5, are billed under the Essentials SKU.
Extended place details
Set include_extended_details to true when the user's request needs
qualitative insights, real-time conditions, or specialized attributes, such as:
- What reviewers say: review-based insights, customer sentiment, and feedback.
- Specific offerings: menu items, dishes, food specialties, beverages, or business highlights.
- Atmosphere: interior decor, aesthetic, ambience, or mood.
- Practical visitor tips: whether to book ahead, walk-in policies, wait times, how busy the place is, parking, and facilities.
- Proximity: distance or travel time from the query location, or the
location_biascenter, when the user asks what's nearby or closest.
The insights in a summary depend on the query and on the data available for each place. Not every type of insight appears in every response.
Leave it false (the default) for standard searches: cuisines or store types,
addresses, contact information, opening hours, and standard amenities. Requests
with extended details take longer to complete.
Extended details don't change the structure of the response. Without them, the
summary describes each place in a sentence or two. With them, each place gets a
longer description that draws on more Google Maps data, including insights from
reviews. The structured places entries are the same for both SKUs.
Example
The following MCP request asks for up to 8 places with extended details. It's billed under the Pro SKU:
{
"method": "tools/call",
"params": {
"name": "search_places",
"arguments": {
"text_query": "date night Italian restaurants in Chicago",
"page_size": 8,
"include_extended_details": true
}
},
"jsonrpc": "2.0",
"id": 1
}
The following example sends the same request to the searchText REST method:
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
"textQuery": "date night Italian restaurants in Chicago",
"pageSize": 8,
"includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchText"
Replace API_KEY with your API key.
Without extended details, the summary describes each place in a sentence or two:
Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$) A neighborhood trattoria known for handmade pasta and a long wine list.
With extended details, the summary adds what reviewers highlight and practical tips:
Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$) A candlelit, intimate dining room that reviewers describe as romantic but loud on weekends. Standout dishes include the tagliatelle al ragù, the burrata, and the tiramisu. Reservations are recommended; walk-ins can expect a 30–45 minute wait on Friday and Saturday evenings, and street parking is limited.
Response
The response contains the following fields:
summary: A natural language summary of the search results. It might contain zero-based citations, such as[0], that map to entries inplaces.places[]: The places mentioned in the summary. Each place includes:place: The resource name of the place, in the formatplaces/{id}.id: The place ID. You can use it with other Google Maps Platform APIs, such as to show the place on a map.location: The latitude/longitude coordinates of the place.googleMapsLinks: Google Maps links for the place (placeUrl), directions (directionsUrl), reviews (reviewsUrl), photos (photosUrl), and writing a review (writeAReviewUrl).attribution: The attribution that you must show with the place. See Attribution requirements.
contentToken: An agentic data visualization token (Preview) that lets you display the places in the response with Places UI Kit at no additional cost. Returned when the response includes at least one place.
The response has the same structure for both SKUs and for MCP and REST. For
field details, see the
search_places reference.
Billing and quotas
Each search_places request is one billable event:
- A request that doesn't use any Pro options is billed under the Maps Grounding Essentials SKU.
- A request that uses a Pro option is billed under the Maps Grounding Pro SKU. Using both options in one request doesn't change the charge. For Pro pricing, see Compare Essentials, Pro, and Grounding with Google Maps.
If you display the places from a search_places response with Places UI Kit,
you can use the
agentic data visualization token
(Preview) so that those Places UI Kit requests aren't billed.
The search_places quota is 300 queries per minute for each project, shared by
both SKUs. For pricing, see the
Main pricing table and the
India pricing table.