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](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#essentials-and-pro);
what the response contains; and how requests are billed. For the full schemas,
see the
[`search_places` MCP reference](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/mcp/search_places.md.txt)
and the
[`searchText` REST reference](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/rest/v1/TopLevel/searchText.md.txt).

## 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](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#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](https://developers.google.com/maps/ai/maps-experience-agent-tools/search-places.md.txt#pro-options). 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](https://developers.google.com/maps/ai/maps-experience-agent-tools/search-places.md.txt#extended_place_details). This is a [Pro option](https://developers.google.com/maps/ai/maps-experience-agent-tools/search-places.md.txt#pro-options). Defaults to `false`. |

### Pro options

Two options select the
[Maps Grounding Pro SKU](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#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](https://developers.google.com/maps/ai/maps-experience-agent-tools/search-places.md.txt#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_bias` center, 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.

> [!NOTE]
> **Note:** Summaries that include insights from reviews are subject to the [attribution requirements](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#attribution_requirements_for_google_maps_sources) for Google Maps sources. Each place in the response includes `googleMapsLinks.reviewsUrl`, which links to the place's reviews on Google Maps.

### Example

The following MCP request asks for up to 8 places with extended details. It's
billed under the Pro SKU:

```json
{
  "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:

```bash
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 in `places`.
- `places[]`: The places mentioned in the summary. Each place includes:
  - `place`: The resource name of the place, in the format `places/{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](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#attribution_requirements_for_google_maps_sources).
- `contentToken`: An [agentic data visualization token](https://developers.google.com/maps/ai/agentic-data-visualization-token.md.txt) (Preview) that lets you display the places in the response with [Places UI Kit](https://developers.google.com/maps/documentation/javascript/places-ui-kit/overview.md.txt) 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](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/mcp/search_places.md.txt).

## 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](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#grounding-lite-ess-sku).
- A request that uses a Pro option is billed under the [Maps Grounding Pro SKU](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#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](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#compare).

If you display the places from a `search_places` response with Places UI Kit,
you can use the
[agentic data visualization token](https://developers.google.com/maps/ai/agentic-data-visualization-token.md.txt)
(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](https://developers.google.com/maps/billing-and-pricing/pricing.md.txt#places-pricing) and the
[India pricing table](https://developers.google.com/maps/billing-and-pricing/pricing-india.md.txt#places-pricing).