> [!WARNING] > This product or feature is in Preview (pre-GA). Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. Pre-GA Offerings are covered by the [Google > Maps Platform Service Specific Terms](https://cloud.google.com/maps-platform/terms/maps-service-terms). For more information, see the [launch stage > descriptions](https://developers.google.com/maps/launch-stages).
> [!NOTE] > **Note:** The agentic data visualization token is supported only for web apps that use the Maps JavaScript API. Support for Places UI Kit in the Places SDK for Android and Places SDK for iOS is coming soon. The **agentic data visualization token** lets your agentic app display [Places UI Kit](https://developers.google.com/maps/documentation/javascript/places-ui-kit/overview.md.txt) elements for the places in a [Maps Experience agent tools](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt) (formerly Maps Grounding Lite) response at no additional cost. Each successful call to the `search_places` or `search_along_route` tool returns a token that identifies the places in the response, for both the Essentials and Pro SKUs. When your client app adds the token to the Maps JavaScript API, Places UI Kit requests for those places aren't billed for 10 minutes after the token is issued. ## How it works The token connects a grounded response to the place details that you display with it: 1. Your agent calls the `search_places` or `search_along_route` tool on the Maps Experience agent tools MCP server. The tool response includes the places that support the summary and a token in the `contentToken` field. 2. Your app reads the token from the tool response and sends it to your client app, along with the IDs of the places that you want to display. 3. Your client app adds the token to the Maps JavaScript API and creates Places UI Kit elements for those places. 4. Google Maps Platform validates the token with each Places UI Kit request. If the token is valid, the request isn't billed. ## Supported Places UI Kit elements The token applies to the following Places UI Kit elements in the Maps JavaScript API: | Element | SKU | |---|---| | [`PlaceDetailsElement`](https://developers.google.com/maps/documentation/javascript/reference/places-widget.md.txt#PlaceDetailsElement) | [Places UI Kit Query](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#places_ui-kit-request-ess-sku) | | [`PlaceDetailsCompactElement`](https://developers.google.com/maps/documentation/javascript/reference/places-widget.md.txt#PlaceDetailsCompactElement) | [Places UI Kit Query](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#places_ui-kit-request-ess-sku) | | [`AdvancedPlaceDetailsElement`](https://developers.google.com/maps/documentation/javascript/reference/places-widget.md.txt#AdvancedPlaceDetailsElement) | [Places UI Kit Pro (Advanced)](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#places_ui-kit_pro_sku) | | [`AdvancedPlaceDetailsCompactElement`](https://developers.google.com/maps/documentation/javascript/reference/places-widget.md.txt#AdvancedPlaceDetailsCompactElement) | [Places UI Kit Pro (Advanced)](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#places_ui-kit_pro_sku) | | [`AdvancedPlaceListElement`](https://developers.google.com/maps/documentation/javascript/reference/places-widget.md.txt#AdvancedPlaceListElement) | [Places UI Kit Pro (Advanced)](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#places_ui-kit_pro_sku) | The token doesn't apply to other requests, such as requests from the Place Search, Advanced Place Search, and Basic Place Autocomplete elements, Places API requests, and map loads. These requests are billed at standard rates. Only Maps Experience agent tools responses include the token. If you display places from a Grounding with Google Maps response with Places UI Kit, those requests are billed at standard rates. ## Before you begin Before you use the agentic data visualization token, set up the following: - A Google Cloud project with the Maps Experience agent tools API (`mapstools.googleapis.com`) and the Places UI Kit API enabled. For more information, 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) and [Get started with Places UI Kit](https://developers.google.com/maps/documentation/javascript/places-ui-kit/get-started.md.txt). - Credentials from that project for both your Maps Experience agent tools calls and the Maps JavaScript API. A token is valid only for Places UI Kit requests from the project that the token was issued to. - A client app that loads the Maps JavaScript API from the [beta channel](https://developers.google.com/maps/documentation/javascript/versions.md.txt#beta-channel) by setting `v=beta`. ## Display places from a grounded response The following sections show how to get the token from the tool response and use it in your client app. If you use the [Maps Agentic UI Toolkit](https://developers.google.com/maps/ai/agentic-ui-toolkit.md.txt) (Experimental), its agent and web client handle these steps for you. ### Get the token from the tool response The `search_places` and `search_along_route` tools return the token in the `contentToken` field. In the result of an MCP `tools/call` request, this field is in `structuredContent`. In a response from the `searchText` or `searchAlongRoute` REST method, it's a top-level field. A `search_places` response is similar to the following (a `search_along_route` response returns each place inside `results[].place`): ```json { "places": [ { "place": "places/PLACE_ID", "id": "PLACE_ID" } ], "contentToken": "CONTENT_TOKEN" } ``` This output includes the following values: - `PLACE_ID`: The place ID of a place in the response. - `CONTENT_TOKEN`: The agentic data visualization token for the places in the response. Treat the token as an opaque string, and don't modify it. If the response doesn't include any places, the response doesn't include a token. In your app code, read the token from the tool response---for example, in a tool callback in your agent framework---and send it to your client app with the place IDs. Don't rely on the LLM to repeat the token in its output, because the model might change the token. A token covers only the places in its own response. If your agent calls `search_places` or `search_along_route` more than once, send each token to your client app. For example, if you use the [Agent Development Kit (ADK)](https://adk.dev/) for Python, you can save each token in an after-tool callback: ```python from typing import Any, Optional from google.adk.tools.base_tool import BaseTool from google.adk.tools.tool_context import ToolContext def save_content_token( tool: BaseTool, args: dict[str, Any], tool_context: ToolContext, tool_response: dict[str, Any], ) -> Optional[dict[str, Any]]: """Saves the agentic data visualization token from a Maps tool response.""" structured_content = tool_response.get("structuredContent") or {} token = structured_content.get("contentToken") if token: tokens = tool_context.state.get("content_tokens", []) tool_context.state["content_tokens"] = tokens + [token] # Return None to pass the original tool response to the model. return None ``` Pass this function as the `after_tool_callback` argument when you create your agent, and then send the saved tokens to your client app with the agent's response. For complete agent definitions, see the ADK examples in [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). ### Add the token and display the places In your client app, pass an iterable (such as an array) of non-empty token strings to `Settings.getInstance().addContentTokens()` before you create Places UI Kit elements for the places. The method throws an error if you pass a single string directly or if the iterable includes an empty string. The following example adds a token, and then displays a Place Details Compact element for each place: ```javascript // The token and place IDs come from the search_places or search_along_route response. async function displayGroundedPlaces(contentToken, placeIds) { const {Settings} = await google.maps.importLibrary('core'); const { PlaceDetailsCompactElement, PlaceDetailsPlaceRequestElement, PlaceStandardContentElement, } = await google.maps.importLibrary('places'); // Add the token before you create Places UI Kit elements. Settings.getInstance().addContentTokens([contentToken]); const container = document.getElementById('agent-response'); for (const placeId of placeIds) { const placeDetails = new PlaceDetailsCompactElement(); placeDetails.append( new PlaceDetailsPlaceRequestElement({place: placeId}), new PlaceStandardContentElement(), ); container.append(placeDetails); } } ``` Tokens expire 10 minutes after they're issued. The Maps JavaScript API keeps the tokens that you add in memory for the current page and removes them automatically after they expire, so you don't need to remove expired tokens yourself. If you add tokens from more than one response, the API sends all of the stored tokens with each request from a supported element. To display multiple places in one element, set the `places` property of an [Advanced Place List element](https://developers.google.com/maps/documentation/javascript/places-ui-kit/advanced-place-list.md.txt) to the place IDs from one or more responses whose tokens you added. ## Token validation A Places UI Kit request isn't billed when all of the following conditions are met: - **Same project**: The tokens were issued to the Google Cloud project that owns the API key that you use to load the Maps JavaScript API. - **Grounded places**: Every place that the element requests is covered by at least one token that you added. An element can include places from multiple responses if you add the token from each response. - **Unexpired tokens**: For each place, the request is made within 10 minutes of when a token that covers the place was issued. - **Supported element** : The request comes from a [supported Places UI Kit element](https://developers.google.com/maps/ai/agentic-data-visualization-token.md.txt#supported-elements). Elements that you configure with a location instead of a place, such as with a `PlaceDetailsLocationRequestElement`, aren't covered. If an Advanced Place List element includes any place that isn't covered, the entire request is billed. If any condition isn't met, the element still loads, and the request is billed at the standard rate for its SKU. The Maps JavaScript API doesn't return an error when a token isn't valid. ## Billing You pay for each Maps Experience agent tools request at its standard rate. Places UI Kit requests that pass [token validation](https://developers.google.com/maps/ai/agentic-data-visualization-token.md.txt#token-validation) aren't billed, but they still count toward your Places UI Kit quota. Places UI Kit requests that don't pass token validation are billed at the standard rate for the [Places UI Kit Query](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#places_ui-kit-request-ess-sku) or [Places UI Kit Pro (Advanced)](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#places_ui-kit_pro_sku) SKU. For prices, 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). ## Usage requirements **Single-user, active-response use only**: You must use an agentic data visualization token only to display supported Places UI Kit elements to the same end user and within the immediate agentic response that generated the token. You must not share, pool, or reuse tokens across multiple end users, or use a token to display places outside that response (such as in saved lists, bookmarks, or cached directories). Your use of the agentic data visualization token 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). The [attribution requirements](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#attribution_requirements_for_google_maps_sources) for Maps Experience agent tools also apply.