Agentic data visualization token

The agentic data visualization token lets your agentic app display Places UI Kit elements for the places in a Maps Experience agent tools (formerly Maps Grounding Lite) response at no additional cost. Each successful call to the search_places 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 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 Places UI Kit Query
PlaceDetailsCompactElement Places UI Kit Query
AdvancedPlaceDetailsElement Places UI Kit Pro (Advanced)
AdvancedPlaceDetailsCompactElement Places UI Kit Pro (Advanced)
AdvancedPlaceListElement Places UI Kit Pro (Advanced)

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 and Get started with Places UI Kit.
  • 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 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 (Experimental), its agent and web client handle these steps for you.

Get the token from the tool response

The search_places tool returns the token in the contentToken field. In the result of an MCP tools/call request, this field is in structuredContent. The tool response is similar to the following:

{
  "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 the search_places tool more than once, send each token to your client app.

For example, if you use the Agent Development Kit (ADK) for Python, you can save each token in an after-tool callback:

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.

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:

// The token and place IDs come from the search_places tool 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 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.

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 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 or Places UI Kit Pro (Advanced) SKU.

For prices, see the Main pricing table and the India pricing table.

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, including the service-specific terms. The attribution requirements for Maps Experience agent tools also apply.