Maps Experience agent tools

Maps Experience agent tools (formerly Maps Grounding Lite) is a Google Maps Platform service with Model Context Protocol (MCP) support to ground your AI applications with trusted geospatial data from Google Maps. The MCP server provides tools that let LLMs access places, weather, and routes data. Other tools resolve location names and Google Maps URLs to Place IDs. You can try Maps Experience agent tools by enabling it in any tool that supports MCP servers.

Maps Experience agent tools is one product with two SKUs: Essentials and Pro. Every request is billed under Essentials unless it uses a Pro option. Pro options add extended place details, more places per search, more intermediate stops per route, and routing with live traffic. During Restricted GA, Pro options are available only to projects on the Pro allowlist. Both SKUs use the same MCP server, tools, and credentials. For details, see Essentials and Pro.

Tools

Maps Experience agent tools allow LLMs to access the following Google Maps capabilities:

  • Search places: Request information about places and get AI-generated summaries. The response also includes Place IDs, coordinates, and Google Maps links for each place in the summary. You can use the Place IDs and coordinates with other Google Maps Platform APIs to show places on a map. With Pro, you can request extended place details, such as insights from reviews, and up to 10 places per request.
  • Lookup weather: Request information about weather and return current conditions, hourly forecasts, and daily forecasts.

  • Compute routes: Request a route between an origin and a destination, optionally through intermediate stops, and return the route's distance and duration. With Pro, routes can account for live traffic conditions and include more intermediate stops.

  • Resolve names and Resolve Maps URLs: Resolve location names, addresses, and Google Maps URLs to Place IDs. For more information, see Resolution API.

After you enable the MCP server, LLMs can call its tools to get grounding information for these data types. The LLM can use this information for context. However, its final response may not include the exact information that the MCP server returned. You should verify the accuracy of the generated response.

Essentials and Pro

Essentials and Pro are two SKUs of the same product, not separate products or plans. A request is billed under Pro when it uses a Pro option. Every other request is billed under Essentials. Pro options are ordinary fields in the tool request, so an LLM can use them on your behalf. An agent can also use both SKUs in the same conversation. For example, an agent might use Essentials to find coffee shops near a landmark. It might then use Pro to answer a follow-up question about their signature drinks and seating. There is no separate MCP server, endpoint, or credential for Pro.

Compare Essentials, Pro, and Grounding with Google Maps

Grounding with Google Maps is a separate product. It's built into Gemini models in the Gemini API, Google AI Studio, and Gemini Enterprise Agent Platform. The model decides when to query Google Maps and returns grounded answers with citations. Choose Grounding with Google Maps when you build on Gemini and want the model to handle grounding. Choose Maps Experience agent tools for other models or agent frameworks, or for direct control of each tool call.

Maps Experience agent tools Grounding with Google Maps
Essentials SKU
(formerly Maps Grounding Lite)		 Pro SKU
How requests are billed Each tool request that doesn't use a Pro option Each tool request that uses a Pro option: include_extended_details, a page_size above 5, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, or more than 10 intermediate waypoints Each Google Maps query or grounded prompt, depending on the platform and model
Models and platforms Any model or agent framework that supports MCP. One MCP server, one set of tools, and the same credentials for both SKUs Gemini models in the Gemini API, Google AI Studio, and Gemini Enterprise Agent Platform
What the tools return Core facts: place details for up to 5 places per search, route distance and duration without live traffic, and current weather and forecasts Everything in Essentials, plus extended place details (such as insights from reviews), up to 10 places per search, routes with live traffic, and up to 25 intermediate waypoints Place details and insights from reviews, and route information with live traffic
Example requests Factual and logistical questions: finding stores or businesses, opening hours, addresses, and distance or travel time estimates Subjective or broad questions: atmosphere, signature dishes, visitor tips, comparisons of 6 to 10 places, and travel times in current traffic Conversational search, itinerary planning, and local discovery in Gemini
Places UI Kit visualizations Included at no additional cost with the agentic data visualization token (Preview) Billed separately
Free usage per month 10,000 requests 5,000 requests Depends on the platform and model. For example, in the Gemini API, Gemini 3 and newer models include 5,000 free search queries per month. After that, search queries cost $14 per 1,000.
Pay-as-you-go price $7.00 per 1,000 requests, with volume discounts $14.00 per 1,000 requests. Contact sales for volume pricing.
Subscribe to save Included in the Essentials and Pro plans Not included Not available
Get started One setup for both SKUs: see Configure LLMs to use the MCP server. During Restricted GA, Pro options also require a project on the Pro allowlist. Gemini API or Agent Platform

These options work the same way with either SKU: travel modes, departure and arrival times, alternative routes, route polylines, weather lookups, and the Resolution API. They don't change which SKU a request is billed under.

What's billed under the Pro SKU

Tool Capability Essentials Pro
Search places Places per request Up to 5 6 to 10 (page_size from 6 to 10)
Extended place details in search summaries (insights from reviews, menu highlights, atmosphere, how busy a place is, visitor tips, and distance or travel time for proximity queries) Not available Available with include_extended_details
Compute routes Routing preference Doesn't account for live traffic Accounts for live traffic, or real-time transit data for transit routes, with ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL
Intermediate waypoints per route Up to 10 11 to 25 (more than 10 intermediate_waypoints)
Lookup weather and Resolution API No Pro options. All requests are billed under the Essentials SKU.

For the request options that enable each capability, see Search places and Compute routes.

Pro options during Restricted GA

During Restricted GA, Pro options are available only to Google Cloud projects on the Pro allowlist. Contact sales to request access. Once a project is on the allowlist, every API key and OAuth client in it can use Pro options.

If your project isn't on the allowlist yet, requests that use Pro options are handled as follows:

  • Search places: include_extended_details is ignored, and the response contains at most 5 places, even if you set page_size higher. The request is billed under the Essentials SKU.
  • Compute routes: ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL is treated as ROUTING_PREFERENCE_TRAFFIC_UNAWARE, and the request is billed under the Essentials SKU. A request with more than 10 intermediate waypoints returns an INVALID_ARGUMENT error.

To check whether your project is on the allowlist, send a search_places request with page_size set to 10. Use a broad query, such as restaurants in Chicago. A project on the allowlist can return more than 5 places, billed under the Pro SKU. Other projects return at most 5 places.

Control Pro usage

Pro options are off by default. An LLM sets them when the user's request calls for them and the tool schema or your instructions allow it. The tool schema describes page_size values up to 5 and at most 10 intermediate waypoints. Models therefore use the higher Pro limits only when your instructions ask for them. To manage costs:

  • Tell the model when Pro options are appropriate. For example: "Set include_extended_details only when the user asks about reviews, menus, or atmosphere." Or: "Use ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL only when the user asks for a current travel time."
  • To keep an agent on the Essentials SKU, instruct the model never to use a Pro option. The Pro options are include_extended_details, page_size above 5, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, and more than 10 intermediate waypoints. If your MCP client can restrict tool arguments, you can also block those values in its tool configuration.
  • Monitor your usage in your billing reports and set budget alerts.

Resolution API

Maps Experience agent tools provides the Resolution API. It resolves free-form location text and URLs to structured Google Maps place identifiers. The Resolution API is available as REST methods and as tools on the MCP server:

  • Resolve names (REST, MCP): Resolve a batch of location names or addresses to specific place entities on Google Maps. This is useful for grounding unstructured user queries into stable Place IDs.
  • Resolve Maps URLs (REST, MCP): Resolve a batch of Google Maps URLs to specific place entities. Supported formats include standard place URLs and shortened URLs.

You can use the returned Place IDs with other Google Maps Platform APIs. Each response also includes a link that saves the resolved places as a list in Google Maps.

For more information, see Maps Tools Resolution API.

Try the sample app (Open in a new tab)

Billing and quotas

How you are billed

With the Google Maps Platform pay-as-you-go pricing model, usage of Maps Experience agent tools is calculated for each request. Each request represents one billing event. Usage is tracked for each product SKU. Your bill shows a line item for each SKU in addition to your total charges. See the Reporting overview for more.

Each Search places, Compute routes, or Lookup weather request is billed under exactly one SKU, Essentials or Pro. A request that uses any Pro option is billed under the Pro SKU. It's never billed under both SKUs, and the number of Pro options doesn't change the charge. The following options determine the SKU:

Tool Essentials Pro
search_places Any request without a Pro option: page_size of 5 or fewer, and include_extended_details unset or false include_extended_details set to true, or page_size from 6 to 10
compute_routes Any request without a Pro option: routing_preference unset or ROUTING_PREFERENCE_TRAFFIC_UNAWARE, and 10 or fewer intermediate waypoints, with any travel mode routing_preference set to ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, or 11 to 25 intermediate waypoints
lookup_weather Every request —

For Essentials pricing, see the Essentials SKU details. Pro requests are billed at $14.00 per 1,000 requests after the first 5,000 requests each month. Contact sales for volume pricing.

During Restricted GA, Pro options take effect only on projects on the Pro allowlist. For details, see Pro options during Restricted GA.

See the Main pricing table and India pricing table for pricing details.

Resolution API requests (ResolveNames and ResolveMapsUrls) are billed at no charge under the Places API Text Search Essentials (IDs Only) SKU.

Usage of the Essentials SKU is also included in the Essentials and Pro Subscribe to save packages. The Pro SKU isn't included in Subscribe to save packages.

Quotas

The following quotas apply to the tools and APIs provided by Maps Experience agent tools:

  • Search places: 300 queries per minute, per project.
  • Lookup weather: 300 queries per minute, per project.
  • Compute routes: 300 queries per minute, per project.
  • Resolve names: 600 queries per minute, per project.
  • Resolve Maps URLs: 600 queries per minute, per project.

Quotas are counted per tool and are shared by the Essentials and Pro SKUs. A Pro request consumes the same quota as an Essentials request to the same tool.

Each Resolution API request counts as one query, regardless of how many items it contains.

Policies and terms of service

Maps Experience agent tools is subject to the Google Maps Platform Terms of Service, including the service-specific terms. This section describes additional usage requirements for Maps Experience agent tools, including compatible LLMs and source attribution. The requirements apply to all results, whichever SKU a request is billed under.

Requirements for Compatible LLMs

You may only use Maps Experience agent tools with an LLM that is compliant with the Google Maps Platform Terms of Service.

For example, you are responsible for ensuring that Google Maps Content is not cached by, stored by, or used to improve the LLM that you choose to use. Before using Maps Experience agent tools, you will need to review the Terms of Service for any model you intend to use with Maps Experience agent tools. You must not use Maps Experience agent tools with any models that use the data input into the model for any model training or improvement. You are responsible for ensuring that your use of the model fully complies with the restrictions on Google Maps Content in the Google Maps Platform Terms of Service, including the service specific terms.

Attribution requirements for Google Maps sources

Each tool response from Maps Experience agent tools includes sources. When you present results from Maps Experience agent tools, you must include the associated Google Maps sources and meet the following requirements:

  • The Google Maps sources must immediately follow the generated content that the sources support. This generated content is also referred to as Grounded Output.
  • The Google Maps sources must be viewable within one user interaction.

Sources for the Search places tool

The search_places tool places field provides sources that support the summary. For places, the following metadata is returned:

  • place (resource name)
  • id
  • location
  • googleMapsLinks

For each place, you must generate a link preview that meets these requirements:

These requirements also apply to summaries that include extended place details from Pro, such as insights from reviews. The summary cites each place with a zero-based index, for example [0], that maps to an entry in places. Each place also includes googleMapsLinks.reviewsUrl, which links to the place's reviews on Google Maps. Users can follow it to see the reviews behind an insight.

Voice-first interfaces

If your app presents Maps Experience agent tools results by voice, you must also meet the requirements for voice-first interfaces. In summary:

  • Sourcing: Display the Google Maps sources in a companion UI that shows a verbatim historical record of the voice conversation.
  • Active disclosure: At the time of interaction, tell users that AI-generated content may include information from Google Maps. Also tell them that detailed sources are available in the companion UI. You can do this on the screen or by voice.
  • Persistent disclosure: Keep a persistent explanation, for example in a voice settings menu, that AI-generated content may include Google Maps content.
  • User inquiries: Accurately answer users' questions about the content's source, and direct them to the companion UI for details.

Configure LLMs to use the MCP server

To use Maps Experience agent tools, you need a Google Cloud project with the Maps Experience agent tools API service enabled. You also need an API key or an OAuth client ID. Then, you can configure LLMs to access the MCP server. The MCP server uses Streamable HTTP transport.

Enable Maps Experience agent tools on your Google Cloud project

To enable the API on your project:

  1. In the Google Cloud Console, choose the project you want to use for Maps Experience agent tools.
  2. Enable billing for the project in the Google Cloud Console.
  3. Enable Maps Experience agent tools in the Google Cloud Console API Library.

Authenticate using an API key

You can use an existing API key with Maps Experience agent tools or create a new one. Either way, enable the Maps Experience agent tools API service on both the Google Cloud project and the key.

To authenticate using an API key:

  1. Create or configure an API key by following the steps in Getting started with Google Maps Platform.
  2. Pass the key to the MCP server using the X-Goog-Api-Key header. You need to specify this as a custom HTTP header in the LLM's MCP tool configuration.

Authenticate using OAuth

You can authenticate using OAuth by creating OAuth credentials and passing them to the MCP host or MCP server application.

To authenticate using OAuth:

  1. In the Google Cloud Console, choose the project you want to use for Maps Experience agent tools.
  2. In the API & Services menu, select Credentials.
  3. In the top menu, select Create credentials > OAuth client ID.
  4. If the project doesn't have a configured consent screen, click Configure consent screen and follow the on-screen instructions.
  5. In the Metrics section, click Create OAuth client.
  6. On the Create OAuth client ID screen, select an application type and enter a name for the client ID.
  7. Specify the additional details that are relevant to your application type. For example, if you are creating a web application, add authorized URIs for browser and server requests.
  8. Once your client is created, save the client ID and secret.
  9. When you configure your MCP host or MCP server application, pass your OAuth client ID and secret. You must also request the following scope: https://www.googleapis.com/auth/maps-platform.mapstools.

For more information, see Using OAuth 2.0 to Access Google APIs.

Configure LLMs to access the Maps Experience agent tools MCP server

After you enable the Maps Experience agent tools service and create credentials, you can configure LLMs to access the MCP server. Follow your LLM's MCP configuration documentation and use the MCP server URL: https://mapstools.googleapis.com/mcp

For more information, see Configure MCP in an AI application.

Configure Maps Experience agent tools with the Gemini CLI

This section provides an example of how to configure the Maps Experience agent tools MCP server using the Gemini CLI. For more details, see the MCP servers with the Gemini CLI.

  1. After you install the Gemini CLI, run gemini mcp add to configure the MCP server:

    gemini mcp add -s user -t http -H 'X-Goog-Api-Key: API_KEY' maps-experience-agent-tools-mcp https://mapstools.googleapis.com/mcp

    If the configuration was successful, you should see a confirmation that the server has been added to your user settings.

  2. To validate that the server is working correctly, run the /mcp list command:

    > /mcp list

Configured MCP servers:

maps-experience-agent-tools-mcp - Ready (5 tools)
Tools:
-   compute_routes
-   lookup_weather
-   resolve_maps_urls
-   resolve_names
-   search_places

  3. Start asking Maps related questions with the CLI. For example, try "Recommend me some restaurants in Mountain View" which should call the search_places tool on your behalf.

Configure Maps Experience agent tools with Agent Development Kit (ADK)

This section shows how to configure the MCP server with the Agent Development Kit (ADK) in Python, Java, or TypeScript.

Python

You can find a complete implementation of this example on GitHub in the adk-samples repository.

Step 1: Define your Agent with McpToolset for Maps Experience agent tools

Modify your agent.py file. Replace YOUR_GOOGLE_MAPS_API_KEY with your actual API key.

# ./adk_agent_samples/mcp_agent/agent.py
import os
from google.adk.agents.llm_agent import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# Retrieve the API key from an environment variable or directly insert it.
GOOGLE_MAPS_API_KEY = os.getenv("GOOGLE_MAPS_API_KEY")
if not GOOGLE_MAPS_API_KEY:
    GOOGLE_MAPS_API_KEY = "YOUR_GOOGLE_MAPS_API_KEY_HERE"

if GOOGLE_MAPS_API_KEY == "YOUR_GOOGLE_MAPS_API_KEY_HERE":
    print("WARNING: GOOGLE_MAPS_API_KEY is not set.")

root_agent = Agent(
    model='gemini-flash-latest',
    name='travel_planner_agent',
    description='A helpful assistant for planning travel routes.',
    tools=[
        McpToolset(
            connection_params=StreamableHTTPConnectionParams(
                url="https://mapstools.googleapis.com/mcp",
                headers={
                    "X-Goog-Api-Key": GOOGLE_MAPS_API_KEY,
                    "Content-Type": "application/json",
                    "Accept": "application/json, text/event-stream"
                }
            )
        )
    ]
)
Step 2: Ensure __init__.py Exists

Ensure you have an __init__.py in the same directory as your agent.py:

from . import agent
Step 3: Run adk web and Interact
  1. Set Environment Variable:
    Set your Google Maps API key as an environment variable in your terminal: 
    export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
  2. Run adk web:
    Run the following command to start the ADK web interface: 
    adk web
  3. Interact in the UI:
    • Select the travel_planner_agent.
    • Try prompts like:
      • "I will be in San Francisco tomorrow. What's the weather like?"
      • "Find coffee shops near Golden Gate Park."
      • "Get directions from GooglePlex to SFO."

Java

Define an agent that initializes the McpToolset in Java. Replace YOUR_GOOGLE_MAPS_API_KEY_HERE with the actual API key you obtained if you don't use an environment variable.

package agents;

import com.google.adk.agents.LlmAgent;
import com.google.adk.runner.InMemoryRunner;
import com.google.adk.sessions.SessionKey;
import com.google.adk.tools.mcp.McpToolset;
import com.google.adk.tools.mcp.StreamableHttpServerParameters;
import com.google.genai.types.Content;
import com.google.genai.types.Part;
import java.util.HashMap;
import java.util.Map;

public class MapsAgentCreator {
    public static void main(String[] args) {
        String googleMapsApiKey = System.getenv("GOOGLE_MAPS_API_KEY");
        if (googleMapsApiKey == null || googleMapsApiKey.trim().isEmpty()) {
            googleMapsApiKey = "YOUR_GOOGLE_MAPS_API_KEY_HERE";
            if ("YOUR_GOOGLE_MAPS_API_KEY_HERE".equals(googleMapsApiKey)) {
                System.out.println("WARNING: GOOGLE_MAPS_API_KEY is not set.");
            }
        }

        Map<String, String> headers = new HashMap<>();
        headers.put("X-Goog-Api-Key", googleMapsApiKey);
        headers.put("Content-Type", "application/json");
        headers.put("Accept", "application/json, text/event-stream");

        StreamableHttpServerParameters serverParams =
                StreamableHttpServerParameters.builder("https://mapstools.googleapis.com/mcp")
                        .headers(headers)
                        .build();

        try (McpToolset toolset = new McpToolset(serverParams)) {
            LlmAgent agent = LlmAgent.builder()
                    .model("gemini-flash-latest")
                    .name("travel_planner_agent")
                    .description("A helpful assistant for planning travel routes.")
                    .tools(toolset)
                    .build();

            System.out.println("Agent created: " + agent.name());

            InMemoryRunner runner = new InMemoryRunner(agent);
            String userId = "maps-user-" + System.currentTimeMillis();
            String sessionId = "maps-session-" + System.currentTimeMillis();
            String promptText =
                    "Please give me directions to the nearest pharmacy to Madison Square Garden.";

            SessionKey sessionKey = runner.sessionService()
                    .createSession(runner.appName(), userId, null, sessionId)
                    .blockingGet()
                    .sessionKey();
            System.out.println("Session created: " + sessionId + " for user: " + userId);

            Content promptContent = Content.fromParts(Part.fromText(promptText));
            System.out.println("\nSending prompt: \"" + promptText + "\" to agent...\n");

            runner.runAsync(sessionKey, promptContent)
                    .blockingForEach(event -> {
                        System.out.println("Event received: " + event.toJson());
                    });
        } catch (Exception e) {
            System.err.println("An error occurred: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

TypeScript

Define an agent that initializes the MCPToolset in TypeScript:

import 'dotenv/config';
import {LlmAgent, MCPToolset} from "@google/adk";

const googleMapsApiKey = process.env.GOOGLE_MAPS_API_KEY;
if (!googleMapsApiKey) {
    console.warn("WARNING: GOOGLE_MAPS_API_KEY is not set.");
    throw new Error(
        'GOOGLE_MAPS_API_KEY is not provided, please run "export GOOGLE_MAPS_API_KEY=YOUR_ACTUAL_KEY" to add that.'
    );
}

export const rootAgent = new LlmAgent({
    model: "gemini-flash-latest",
    name: "travel_planner_agent",
    description: "A helpful assistant for planning travel.",
    tools: [
        new MCPToolset({
            type: "SseConnectionParams",
            url: "https://mapstools.googleapis.com/mcp",
            headers: {
                "X-Goog-Api-Key": googleMapsApiKey,
                "Content-Type": "application/json",
                "Accept": "application/json, text/event-stream"
            }
        })
    ],
});

Sharing feedback

To share feedback about Maps Experience agent tools, use the following forms: