Maps Experience agent tools (formerly Maps Grounding Lite) is a Google Maps Platform service with Model Context Protocol (MCP) and REST support to ground your AI applications with trusted geospatial data from Google Maps. Its tools let LLMs access places, weather, air quality, pollen, and routes data. Other tools resolve location names and Google Maps URLs to place IDs. You can try Maps Experience agent tools by enabling its MCP server in any tool that supports MCP servers. You can also call each tool as a REST method. For details, see [Call the tools with REST](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#rest). 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 places searches along a route, extended place details, more places per search, more intermediate stops per route, routing with live traffic, pollen forecasts, and historical air quality. Both SKUs use the same tools, MCP server, REST methods, and credentials. For details, see [Essentials and Pro](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#essentials-and-pro). ## Tools Maps Experience agent tools lets LLMs access the following Google Maps capabilities: - [**Search places**](https://developers.google.com/maps/ai/maps-experience-agent-tools/search-places.md.txt): Request information about places and get AI-generated summaries. The response also includes place IDs, latitude/longitude coordinates, and Google Maps links for each place in the summary. You can use the place IDs and latitude/longitude coordinates with other Google Maps Platform APIs to show places on a map. To display these places with Places UI Kit at no additional cost, use the [agentic data visualization token](https://developers.google.com/maps/ai/agentic-data-visualization-token.md.txt) (Preview). With Pro, you can request extended place details, such as insights from reviews, and up to 10 places per request. - [**Search along route**](https://developers.google.com/maps/ai/maps-experience-agent-tools/search-along-route.md.txt): Find places along a travel route---specified using a `retrieval_token` from `compute_routes`, `route_endpoints`, or an `encoded_polyline`---and get an AI-generated summary, place details, detour distance and travel time, and an [agentic data visualization token](https://developers.google.com/maps/ai/agentic-data-visualization-token.md.txt) (Preview). Every `search_along_route` request is billed under the Pro SKU. - [**Lookup weather**](https://developers.google.com/maps/ai/maps-experience-agent-tools/lookup-weather.md.txt): Request environmental conditions for a location, including weather (current conditions, 24-hour hourly history, and up to 10-day hourly and daily forecasts) and current or up to 4-day forecast air quality. With Pro, you can also request up to 5-day daily pollen forecasts (with plant species details) and up to 30 days of hourly air quality history. - [**Compute routes**](https://developers.google.com/maps/ai/maps-experience-agent-tools/compute-routes.md.txt): Request a route between an origin and a destination, optionally through intermediate stops, and return the route's distance, duration, and a `retrievalToken` for `DRIVE` routes that you can pass to `search_along_route`. With Pro, routes can account for live traffic conditions and include more intermediate stops. > [!NOTE] > **Note:** Maps Experience agent tools doesn't provide step-by-step directions or navigation information. Routes computed without Pro options don't account for live traffic. - [**Resolve names**](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/mcp/resolve_names.md.txt) and [**Resolve Maps URLs**](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/mcp/resolve_maps_urls.md.txt): Resolve location names, addresses, and Google Maps URLs to place IDs. For more information, see [Resolution API](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#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 might not include the exact information that the MCP server returned. 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's no separate MCP server, endpoint, or credential for Pro. ### Compare Essentials, Pro, and Grounding with Google Maps [Grounding with Google Maps](https://ai.google.dev/gemini-api/docs/maps-grounding) is a separate product. It's built into Gemini models in the Gemini API, Google AI Studio, and [Gemini Enterprise Agent Platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/grounding/grounding-with-google-maps). 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. The following table compares the Essentials SKU, the Pro SKU, and Grounding with Google Maps: | | Maps Experience agent tools || Grounding with Google Maps | | | Essentials SKU (formerly Maps Grounding Lite) | Pro SKU | Grounding with Google Maps | | How requests are billed | Each tool request that doesn't use a Pro option | Every `search_along_route` request, or any request to another tool that uses a Pro option. See [What's billed under the Pro SKU](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#what-pro-adds). | Each Google Maps query or grounded prompt, depending on the platform and model | | Models and platforms | Any model or agent framework that supports MCP or can call REST APIs. 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, current weather and forecasts (plus 24-hour hourly weather history), and current or forecast air quality | Everything in Essentials, plus places along a route with detour time and distance, extended place details (such as insights from reviews), up to 10 places per search, routes with live traffic, up to 25 intermediate waypoints, pollen forecasts, and up to 30 days of historical air quality | 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, distance or travel time estimates, current weather, 10-day weather forecasts, and current or 4-day air quality forecasts | Subjective, broad, or specialized questions: places along a route, atmosphere, signature dishes, visitor tips, comparisons of 6 to 10 places, travel times in current traffic, pollen and allergy forecasts, and air quality history over the past 30 days | Conversational search, itinerary planning, and local discovery in Gemini | | Places UI Kit visualizations | Included at no additional cost with the [agentic data visualization token](https://developers.google.com/maps/ai/agentic-data-visualization-token.md.txt) (Preview) || Billed separately | | Monthly usage at no charge | 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 search queries per month at no charge. 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, with volume discounts | Depends on the platform and model. For example, in the Gemini API, Gemini 3 and newer models include 5,000 search queries per month at no charge. After that, search queries cost $14 per 1,000. | | Subscribe to save | Included in the Essentials and Pro plans | Included in the Pro plan | Not available | | Get started | One setup for both SKUs: see [Configure LLMs to use the MCP server](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#configure_llms_to_use_the_mcp_server) or [Call the tools with REST](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#rest). || [Gemini API](https://ai.google.dev/gemini-api/docs/maps-grounding) or [Agent Platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/grounding/grounding-with-google-maps) | |---|---|---|---| These options work the same way with either SKU: travel modes, departure and arrival times, alternative routes, route polylines, weather lookups, current and forecast air quality lookups (including pollutant concentrations and local AQI scales), weather unit systems, and the Resolution API. They don't change which SKU a request is billed under. ### What's billed under the Pro SKU The following table summarizes which capabilities are included in Essentials and which capabilities require the Pro SKU: | Tool | Capability | Essentials | Pro | | [Search places](https://developers.google.com/maps/ai/maps-experience-agent-tools/search-places.md.txt) | Places per request | Up to 5 | 6 to 10 (`page_size` from 6 to 10) | | [Search places](https://developers.google.com/maps/ai/maps-experience-agent-tools/search-places.md.txt) | |---|---|---|---| | 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` | | Intermediate waypoints per route | Up to 10 | 11 to 25 (more than 10 `intermediate_waypoints`) | | Air quality | Current conditions, today's full-day hourly results, and hourly forecasts up to 4 days (`AIR_QUALITY` in `capabilities`) | Historical air quality up to 30 days in the past (`AIR_QUALITY` in `capabilities` with a `date` before today or a past `hour` in the location's time zone), when returned in the response | | Pollen | Not available | Daily pollen forecasts up to 5 days and plant species details (`POLLEN` in `capabilities`), when returned in the response | For the request options that enable each capability, see [Search places](https://developers.google.com/maps/ai/maps-experience-agent-tools/search-places.md.txt), [Search along route](https://developers.google.com/maps/ai/maps-experience-agent-tools/search-along-route.md.txt), [Compute routes](https://developers.google.com/maps/ai/maps-experience-agent-tools/compute-routes.md.txt), and [Lookup weather](https://developers.google.com/maps/ai/maps-experience-agent-tools/lookup-weather.md.txt). ### Control Pro usage Pro options are off by default on `search_places`, `compute_routes`, and `lookup_weather`. An LLM sets them---or calls `search_along_route`---when the user's request calls for them and the tool description or your instructions allow it. The tool descriptions tell the model which options cost more and when to use them: a `page_size` above 5, extended place details, more than 10 intermediate waypoints, traffic-aware routing, and `search_along_route`. If you call the tools with REST, your code sets every option. 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." Or: "Call `search_along_route` only when the user asks for places along a route." Or: "Include `POLLEN`, or `AIR_QUALITY` with a past `date` or `hour`, only when the user asks about pollen, allergies, or historical air quality." - To keep an agent on the Essentials SKU, instruct the model never to call `search_along_route` or use a Pro option. The Pro options are `include_extended_details`, `page_size` above 5, `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`, more than 10 intermediate waypoints, `POLLEN` in `capabilities`, and a past `date` or `hour` with `AIR_QUALITY` in `capabilities`. If your MCP client can restrict tools or tool arguments, you can also block `search_along_route` and those argument values in its tool configuration. - Monitor the [Maps Grounding Pro SKU](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#grounding-pro-sku) in your [billing reports](https://developers.google.com/maps/reporting-and-monitoring/reporting.md.txt) and set [budget alerts](https://cloud.google.com/billing/docs/how-to/budgets). ## 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](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/rest/v1/TopLevel/resolveNames.md.txt), [MCP](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/mcp/resolve_names.md.txt)): Resolve a batch of location names or addresses to specific place entities on Google Maps. This tool helps ground unstructured user queries into stable place IDs. - **Resolve Maps URLs** ([REST](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/rest/v1/TopLevel/resolveMapsUrls.md.txt), [MCP](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/mcp/resolve_maps_urls.md.txt)): 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](https://developers.google.com/maps/ai/maps-experience-agent-tools/resolution-api.md.txt). ## Try the sample app [(Open in a new tab)](https://grounding-lite-app-302254163709.us-central1.run.app/) ## 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](https://developers.google.com/maps/billing/gmp-billing#skus). Your bill shows a line item for each SKU in addition to your total charges. See the [Reporting overview](https://developers.google.com/maps/billing/understanding-cost-of-use#reporting-overview) for more information. Each Search places, Search along route, Compute routes, or Lookup weather request, through the MCP server or with REST, is billed under one SKU: [Maps Grounding Essentials](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#grounding-lite-ess-sku) or [Maps Grounding Pro](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#grounding-pro-sku). Every `search_along_route` request and any request that uses a Pro option is billed under the Pro SKU. A request is never billed under both SKUs, and the number of Pro options in a request doesn't change the charge. For the capabilities and options that determine the SKU for each tool, see [What's billed under the Pro SKU](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#what-pro-adds). [Maps Grounding Essentials](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#grounding-lite-ess-sku) requests are billed at $7.00 per 1,000 requests after the first 10,000 requests each month. [Maps Grounding Pro](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#grounding-pro-sku) requests are billed at $14.00 per 1,000 requests after the first 5,000 requests each month. Both SKUs have volume discounts at higher monthly usage. See the [Main pricing table](https://developers.google.com/maps/billing-and-pricing/pricing.md.txt#places-pricing) and [India pricing table](https://developers.google.com/maps/billing-and-pricing/pricing-india.md.txt#places-pricing) for pricing details. Resolution API requests (`ResolveNames` and `ResolveMapsUrls`) are billed at no charge under the [Places API Text Search Essentials (IDs Only)](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#places_text-search-id-only-ess-sku) SKU. If you display the places from a `search_places` or `search_along_route` 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. Usage of the Essentials SKU is included in the Essentials and Pro [Subscribe to save](https://mapsplatform.google.com/pricing/#subscribe-to-save) plans. Usage of the Pro SKU is included in the Pro plan. ### Quotas The following quotas apply to the tools and APIs provided by Maps Experience agent tools: - **Search places**: 300 queries per minute for each project. - **Search along route**: 300 queries per minute for each project. - **Lookup weather**: 300 queries per minute for each project. - **Compute routes**: 300 queries per minute for each project. - **Resolve names**: 600 queries per minute for each project. - **Resolve Maps URLs**: 600 queries per minute for each project. Quotas are counted for each 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](https://cloud.google.com/maps-platform/terms), including the [service-specific terms](https://cloud.google.com/maps-platform/terms/maps-service-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 and Search along route tools The `search_places` tool `places` field and the `search_along_route` tool `results[].place` field provide sources that support the `summary`. For each place, the following metadata is returned: - `place` (resource name) - `id` - `location` - `googleMapsLinks` - `attribution` For each place, you must generate a link preview that meets these requirements: - Attribute each source to Google Maps, following the [Maps Experience agent tools text attribution guidelines](https://developers.google.com/maps/ai/maps-experience-agent-tools/attribution.md.txt). - Link to the source using `googleMapsLinks.placeUrl` from the response. 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, such as `[0]`, that maps to an entry in `places` or `results`. 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](https://developers.google.com/maps/ai/maps-experience-agent-tools/attribution.md.txt#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](https://console.developers.google.com/), choose the project you want to use for Maps Experience agent tools. 2. Enable billing for the project in the [Google Cloud Console](https://console.developers.google.com/billing/enable). 3. Enable Maps Experience agent tools in the [Google Cloud Console API Library](https://console.developers.google.com/apis/library/mapstools.googleapis.com). ### 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](https://console.cloud.google.com/marketplace/product/google/mapstools.googleapis.com) on both the Google Cloud project and the key. > [!NOTE] > **Note:** For testing and prototyping, you can also use the [Maps Demo Key](https://developers.google.com/maps/demo-key.md.txt) at no cost, without a billing account. To authenticate using an API key: 1. Create or configure an API key by following the steps in [Getting started with Google Maps Platform](https://developers.google.com/maps/get-started#api-key). 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. > [!NOTE] > **Note:** When you create or configure an API key, limit its use by applying the appropriate restrictions. For more information, see [Restrict your API > keys](https://developers.google.com/maps/api-security-best-practices#restricting-api-keys). ### 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](https://console.developers.google.com/), 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](https://developers.google.com/identity/protocols/oauth2). ### 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](https://docs.cloud.google.com/mcp/configure-mcp-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](https://github.com/google-gemini/gemini-cli). For more details, see the [MCP servers with the Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md). 1. After you install the Gemini CLI, run `gemini mcp add` to configure the MCP server: ```bash 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, run the `/mcp list` command: ```bash > /mcp list Configured MCP servers: maps-experience-agent-tools-mcp - Ready (6 tools) Tools: - compute_routes - lookup_weather - resolve_maps_urls - resolve_names - search_along_route - search_places ``` 3. Start asking Maps-related questions with the CLI. For example, try "Recommend some restaurants in Mountain View", which calls the `search_places` tool on your behalf. > [!NOTE] > **Note:** To use OAuth with a Gemini CLI extension, see the [Gemini > CLI](https://docs.cloud.google.com/mcp/configure-mcp-ai-application#gemini-cli) section of the MCP on Google Cloud documentation. #### 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)](https://adk.dev/) in Python, Java, or TypeScript. > [!NOTE] > **Note:** Ensure you have enabled Maps Experience agent tools and obtained an API key. ### Python You can find a complete implementation of this example on GitHub in the [adk-samples repository](https://github.com/google/adk-samples/tree/main/python/agents/travel-planner-google-maps-mcp). ##### 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. ```python # ./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`: ```python 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: ```bash 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: ```bash 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. ```java 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 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: ```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: "StreamableHTTPConnectionParams", url: "https://mapstools.googleapis.com/mcp", transportOptions: { requestInit: { headers: { "X-Goog-Api-Key": googleMapsApiKey, "Content-Type": "application/json", "Accept": "application/json, text/event-stream" } } } }) ], }); ``` ## Call the tools with REST Each tool in Maps Experience agent tools is also available as a REST method. Call the REST methods directly when you want to wire the tools into your own agent or application---for example, to declare your own functions for a model, choose which options the model can set, or set default values in your code. The following table lists the REST method for each tool: | Tool | REST method | |---|---| | `search_places` | [`POST https://mapstools.googleapis.com/v1:searchText`](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/rest/v1/TopLevel/searchText.md.txt) | | `search_along_route` | [`POST https://mapstools.googleapis.com/v1:searchAlongRoute`](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/rest/v1/TopLevel/searchAlongRoute.md.txt) | | `lookup_weather` | [`POST https://mapstools.googleapis.com/v1:lookupWeather`](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/rest/v1/TopLevel/lookupWeather.md.txt) | | `compute_routes` | [`POST https://mapstools.googleapis.com/v1:computeRoutes`](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/rest/v1/TopLevel/computeRoutes.md.txt) | | `resolve_names` | [`POST https://mapstools.googleapis.com/v1:resolveNames`](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/rest/v1/TopLevel/resolveNames.md.txt) | | `resolve_maps_urls` | [`POST https://mapstools.googleapis.com/v1:resolveMapsUrls`](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/rest/v1/TopLevel/resolveMapsUrls.md.txt) | A REST request takes the same options as the corresponding tool and returns the same response. In REST request and response bodies, field names use lower camel case---for example, `textQuery` instead of `text_query`. REST requests are billed under the same SKUs, follow the same rules for Pro options, and count toward the same quotas as MCP tool calls. To authenticate, use the same Google Cloud project and credentials as for the MCP server. For setup steps, see [Configure LLMs to use the MCP server](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#configure_llms_to_use_the_mcp_server). Pass an API key in the `X-Goog-Api-Key` header, or pass an OAuth access token with the `https://www.googleapis.com/auth/maps-platform.mapstools` scope in the `Authorization` header. The following example calls the `searchText` method: ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "X-Goog-Api-Key: API_KEY" \ -d '{ "textQuery": "coffee shops near Golden Gate Park" }' \ "https://mapstools.googleapis.com/v1:searchText" ``` Replace `API_KEY` with your API key. The response contains the same `summary`, `places`, and `contentToken` fields as a `search_places` tool result. Each tool's guide shows a REST version of its example. ## Sharing feedback To share feedback about Maps Experience agent tools, use the following forms: - [Report a bug](https://issuetracker.google.com/issues/new?component=1939139&template=2210898) - [Submit a feature request](https://issuetracker.google.com/issues/new?component=1939139&template=2210768) - [Provide feedback](https://docs.google.com/forms/d/e/1FAIpQLSe72eobSaaE2UGgvC7edpeRWRjD3AZvDDYrRQDbhyoNVGWcTw/viewform)