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 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 SDK for Android, or Places SDK for iOS, 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 or passes it on each mobile component request, 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

Maps JavaScript API

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)

Places SDK for Android

Fragment/composable function SKU
PlaceDetailsFragment Places UI Kit Query
PlaceDetailsCompactFragment Places UI Kit Query
AdvancedPlaceDetailsFragment Places UI Kit Pro (Advanced)
AdvancedPlaceDetailsCompactFragment Places UI Kit Pro (Advanced)
AdvancedPlaceListFragment Places UI Kit Pro (Advanced)
AdvancedPlaceDetails Places UI Kit Pro (Advanced)
AdvancedPlaceDetailsCompact Places UI Kit Pro (Advanced)
PlaceMarker Places UI Kit Pro (Advanced)

Places SDK for iOS

Struct SKU
PlaceDetailsView Places UI Kit Query
PlaceDetailsCompactView Places UI Kit Query
AdvancedPlaceDetailsView Places UI Kit Pro (Advanced)
AdvancedPlaceDetailsCompactView Places UI Kit Pro (Advanced)
AdvancedPlaceListView Places UI Kit Pro (Advanced)
PlaceMarker 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 for JavaScript, Android, or iOS.
  • Credentials from that project for both your Maps Experience agent tools calls and the Maps JavaScript API, Places SDK for Android, or Places SDK foriOS. 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. For mobile, use Places SDK for Android version 6.1.0 or later or Places Swift SDK (GooglePlacesSwift) version 11.4.0.

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 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):

{
  "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) 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

Maps JavaScript API

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 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 to the place IDs from one or more responses whose tokens you added.

Places SDK for Android

Pass contentTokens: Set<String> directly on each component query.

Tokens expire 10 minutes after they're issued. The SDK doesn't store tokens across requests or track expiration.

Jetpack Compose (AdvancedPlaceDetails, AdvancedPlaceDetailsCompact, PlaceMarker):

val placeRef = PlaceReference.PlaceId(
    placeId = placeId,
    contentTokens = setOf(contentToken),
)
// Or with a resource name:
// PlaceReference.ResourceName(resourceName = resourceName, contentTokens = setOf(contentToken))

Fragments (PlaceDetailsFragment, PlaceDetailsCompactFragment, AdvancedPlaceDetailsFragment, AdvancedPlaceDetailsCompactFragment):

fragment.loadWithPlaceId(placeId, setOf(contentToken))
// Or: fragment.loadWithResourceName(resourceName, setOf(contentToken))

Place List Fragment (AdvancedPlaceListFragment):

advancedPlaceListFragment.configureFromPlaceIds(placeIds, setOf(contentToken))
// Or: advancedPlaceListFragment.configureFromResourceNames(resourceNames, setOf(contentToken))

Places SDK for iOS

The SDK provides dedicated PlaceIdentifier enum cases (.placeIDWithTokens or .resourceNameWithTokens) that are passed into existing PlaceDetailsQuery(identifier:) and PlaceMarker(identifier:...) initializers.

Tokens expire 10 minutes after they're issued. The SDK doesn't store tokens across requests or track expiration.

// Place Details and Advanced Place Details (full and compact):
@State var query = PlaceDetailsQuery(
  identifier: .placeIDWithTokens(placeId, contentTokens: [contentToken])
)
// Or: .resourceNameWithTokens(resourceName, contentTokens: [contentToken])


// Advanced Place List:
@State var queries = [
  PlaceDetailsQuery(
    identifier: .placeIDWithTokens(placeId, contentTokens: [contentToken])
  )
]
// Place Marker:
PlaceMarker(
  identifier: .placeIDWithTokens(placeId, contentTokens: [contentToken]),
  markerIcon: .type,
  markerText: .rating
)

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, Places SDK for Android, or Places SDK for iOS.
  • Grounded places: Every place that the element requests is covered by at least one token included in the request. 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 or component.

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, Places SDK for Android, and Places SDK for iOS don't return an error when a token isn't valid.

Limits (Places SDK for Android and iOS only)

  • There is a maximum 100 unique tokens per request. Excess tokens are truncated with a warning log.
  • There is a maximum 2,048 UTF-8 bytes per token. Oversized tokens are dropped with a warning log and blanks or duplicates are ignored.
  • Coordinate queries (PlaceReference.Coordinates and PlaceIdentifier.coordinate) don't accept tokens.
  • On iOS AdvancedPlaceListView, if any query in the list lacks a non-empty place ID or resource name, no tokens are sent for the list.

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, or requests with invalid or expired tokens, 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.