The contextual widget is a Google Maps Pre-GA Offering that's a visual container used to support or supplement other Google Maps content. The Google Maps contextual widget lets you integrate Grounding with Google Maps into your applications to create a conversational LLM-powered chat experience. The contextual widget is rendered using the context token, googleMapsWidgetContextToken, which is returned in the Vertex AI API response and can be used to render visual content.

The contextual widget serves different functions depending on your scenario:

• It displays subjective user-generated content (UGC) in the scenario where Google Maps prompting is used for answer generation.
• It helps to enrich results with map visualizations and data when Vertex AI generates just a text response.

How the contextual widget works

The contextual widget displays a response from Grounding with Google Maps in Vertex AI, in the form of a googleMapsWidgetContextToken. Use this token to render the contextual widget, and display the response. Learn more. The event flow is as follows:

1. Call the Vertex AI API with a query grounded with Google Maps.
2. Vertex AI returns a googleMapsWidgetContextToken.
3. Render the contextual widget using the token.
4. The contextual widget displays the response from Vertex AI.

The following example shows how a context token looks when returned from the Vertex AI API.

"googleMapsWidgetContextToken": "widgetcontent/AcBXPQdpWQWbap9H-OH8sEKmOXxmEKAYvff0tvthhneMQC3VrqWCjpnPBl4-Id98FGiA_S_t8aeAeJj0T6JkWFX56Bil8oBSR0W8JH3C_RSYLbTjxKdpxc9yNn6JcZTtolIRZon9xi6WpNGuSyjcIxWu2S0hwpasNOpUlWrG1RxVCB4WD1fsz_pwR236mG36lMxevXTQ_JnfdYNuQwQ4Lc3vn...<snip>...
Ts5VJE_b3IC5eE_6wez0nh61r7foTUZpP7BXMwxR-7Wyfcj6x1v6mIWsFGr1o0p_HSAMNqWPg-aFVnkPLhAkOR6MaNZOfezTva-gxHlu7z_haFvYxcUE1qfNVQ",

Render the Google Maps contextual widget

To render and use the Google Maps contextual widget, use the alpha version of the Maps JavaScript API on the page that displays the widget. For more information, see Load the Maps JavaScript API. You must also use the API key that was enabled to load the Google Maps JavaScript API. Verify that the places library has been loaded.

The following section describes how to render the Google Maps contextual widget. Create a contextual widget by using custom HTML or with JavaScript.

Use custom HTML elements

The following section describes how to render the Google Maps contextual widget using custom HTML elements. Create a contextual widget by adding the gmp-place-contextual element to the page.

1. Add the gmp-place-contextual element to the page:

   <gmp-place-contextual id="widget"></gmp-place-contextual>

2. In any response that is grounded with Google Maps, there's a corresponding googleMapsWidgetContextToken that can be used to render the contextual widget. The following function shows how to update the context token:

   let widget = document.querySelector('#widget'); // a div that contains the widget
   widget.contextToken = contextToken;

3. Optional: Specify the list layout. Valid values include the following:
   • Compact layout: <gmp-place-contextual-list-config layout="compact">
   • Vertical layout: <gmp-place-contextual-list-config layout="vertical">

   The following example shows how to change the list layout to compact:

   <gmp-place-contextual id="widget">
     <gmp-place-contextual-list-config layout="compact">
     </gmp-place-contextual-list-config>
   </gmp-place-contextual>

4. Optional: Change the map mode. Valid values include the following:
   • 2D roadmap map: <gmp-place-contextual-map-config map-mode="roadmap">
   • 3D hybrid map: <gmp-place-contextual-map-config map-mode="hybrid">
   • No map: <gmp-place-contextual-map-config map-mode="none">
The following example shows how to change the map mode to a 2D map:

<gmp-place-contextual id="widget">
  <gmp-place-contextual-map-config map-mode="roadmap">
  </gmp-place-contextual-map-config>
</gmp-place-contextual>

Use JavaScript

The following section describes how to render the Google Maps contextual widget by programmatically creating a PlaceContextualElement and appending it to the DOM.

1. Create a contextual widget.

   let widget = document.querySelector('#widget');  // a div that contains the widget
   
   async function createWidget(contextToken) {
     await google.maps.importLibrary('places');
     const placeContextualElement = new
         google.maps.places.PlaceContextualElement({ contextToken }); // contextToken can be empty at initialization.
     widget.appendChild(placeContextualElement);
   }

2. In any response that's grounded with Google Maps, there's a corresponding googleMapsWidgetContextToken that's used to render the contextual widget. The following function shows how to update the context token:

   widget.contextToken = contextToken;

3. Optional: Specify the list layout. Valid values include the following:
   • Compact layout: google.maps.places.PlaceContextualListLayout.COMPACT
   • Vertical layout: google.maps.places.PlaceContextualListLayout.VERTICAL

The following example shows how to change the list layout to compact:

const widgetConfig = new google.maps.places.PlaceContextualListConfigElement({
  layout: google.maps.places.PlaceContextualListLayout.COMPACT
});
widget.appendChild(widgetConfig);

4. Optional: Change the map mode. Valid values include the following:
   • 2D roadmap map: google.maps.places.PlaceContextualListMapMode.ROADMAP
   • 3D hybrid map: google.maps.places.PlaceContextualListMapMode.HYBRID
   • No map: google.maps.places.PlaceContextualListMapMode.NONE

The following example shows how to change the map mode to a 2D map:

const widgetConfig = new google.maps.places.PlaceContextualListConfigElement({
  mapMode: google.maps.places.PlaceContextualListMapMode.ROADMAP
});
widget.appendChild(widgetConfig);

Prohibited territories