Repository Public
1Grounding with Google Maps connects the generative capabilities of Gemini with2the rich, factual, and up-to-date data of Google Maps. This feature enables3developers to easily incorporate location-aware functionality into their4applications. When a user query has a context related to Maps data, the Gemini5model leverages Google Maps to provide factually accurate and fresh answers that6are relevant to the user's specified location or general area.78- **Accurate, location-aware responses:** Leverage Google Maps' extensive and current data for geographically specific queries.9- **Enhanced personalization:** Tailor recommendations and information based on user-provided locations.1011## Get started1213This example demonstrates how to integrate Grounding with Google Maps into your14application to provide accurate, location-aware responses to user queries. The15prompt asks for local recommendations with an optional user location, enabling16the Gemini model to use Google Maps data.1718### Python1920 # This will only work for SDK newer than 2.0.021 from google import genai2223 client = genai.Client()2425 interaction = client.interactions.create(26 model="gemini-3.8-flash",27 input="What are the best Italian restaurants within a 15-minute walk from here?",28 tools=[{29 "type": "google_maps",30 "latitude": 34.050481,31 "longitude": -118.24852632 }]33 )3435 # Print the model's text response and annotations36 for step in interaction.steps:37 if step.type == "model_output":38 for content_block in step.content:39 if content_block.type == "text":40 print(content_block.text)41 if content_block.annotations:42 print("\nSources:")43 for annotation in content_block.annotations:44 if annotation.type == "place_citation":45 print(f" - {annotation.name}: {annotation.url}")4647### JavaScript4849 // This will only work for SDK newer than 2.0.050 import { GoogleGenAI } from "@google/genai";5152 const ai = new GoogleGenAI({});5354 async function main() {55 const interaction = await ai.interactions.create({56 model: "gemini-3.8-flash",57 input: "What are the best Italian restaurants within a 15-minute walk from here?",58 tools: [{59 type: "google_maps",60 latitude: 34.050481,61 longitude: -118.24852662 }]63 });6465 // Print the model's text response and annotations66 for (const step of interaction.steps) {67 if (step.type === 'model_output') {68 for (const contentBlock of step.content) {69 if (contentBlock.type === 'text') {70 console.log(contentBlock.text);71 if (contentBlock.annotations) {72 console.log("\nSources:");73 for (const annotation of contentBlock.annotations) {74 if (annotation.type === 'place_citation') {75 console.log(` - {annotation.name}: {annotation.url}`);76 }77 }78 }79 }80 }81 }82 }83 }8485 main();8687### Java8889 import com.google.genai.Client;90 import com.google.genai.gaos.models.interactions.Annotation;91 import com.google.genai.gaos.models.interactions.Content;92 import com.google.genai.gaos.models.interactions.CreateModelInteraction;93 import com.google.genai.gaos.models.interactions.GoogleMaps;94 import com.google.genai.gaos.models.interactions.Interaction;95 import com.google.genai.gaos.models.interactions.InteractionsInput;96 import com.google.genai.gaos.models.interactions.Model;97 import com.google.genai.gaos.models.interactions.ModelOutputStep;98 import com.google.genai.gaos.models.interactions.PlaceCitation;99 import com.google.genai.gaos.models.interactions.Step;100 import com.google.genai.gaos.models.interactions.TextContent;101 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;102 import java.util.Arrays;103104 Client client = new Client();105106 CreateModelInteraction params =107 CreateModelInteraction.builder()108 .model(Model.of("gemini-3.8-flash"))109 .input(110 InteractionsInput.of(111 "What are the best Italian restaurants within a 15-minute walk from here?"))112 .tools(113 Arrays.asList(114 GoogleMaps.builder().latitude(34.050481).longitude(-118.248526).build()))115 .build();116117 Interaction interaction =118 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();119120 // Print the model's text response and annotations121 if (interaction.steps().isPresent()) {122 for (Step step : interaction.steps().get()) {123 if (step instanceof ModelOutputStep) {124 ModelOutputStep outputStep = (ModelOutputStep) step;125 if (outputStep.content().isPresent()) {126 for (Content contentBlock : outputStep.content().get()) {127 if (contentBlock instanceof TextContent) {128 TextContent textContent = (TextContent) contentBlock;129 System.out.println(textContent.text().orElse(""));130 if (textContent.annotations().isPresent()131 && !textContent.annotations().get().isEmpty()) {132 System.out.println("\nSources:");133 for (Annotation annotation : textContent.annotations().get()) {134 if (annotation instanceof PlaceCitation) {135 PlaceCitation citation = (PlaceCitation) annotation;136 System.out.printf(137 " - %s: %s%n", citation.name().orElse(""), citation.url().orElse(""));138 }139 }140 }141 }142 }143 }144 }145 }146 }147148### REST149150 # Specifies the API revision to avoid breaking changes when they become default151 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \152 -H "x-goog-api-key: $GEMINI_API_KEY" \153 -H 'Content-Type: application/json' \154 -d '{155 "model": "gemini-3.8-flash",156 "input": "What are the best Italian restaurants within a 15-minute walk from here?",157 "tools": [{158 "type": "google_maps",159 "latitude": 34.050481,160 "longitude": -118.248526161 }]162 }'163164## How Grounding with Google Maps works165166Grounding with Google Maps integrates the Gemini API with the Google Geo167ecosystem by using the Maps API as a grounding source. When a user's query168contains geographical context, the Gemini model can invoke the Grounding with169Google Maps tool. The model can then generate responses grounded in Google Maps170data relevant to the provided location.171172The process typically involves:1731741. **User query:** A user submits a query to your application, potentially including geographical context (e.g., "coffee shops near me," "museums in San Francisco").1752. **Tool invocation:** The Gemini model, recognizing the geographical intent, invokes the Grounding with Google Maps tool. This tool can optionally be provided with the user's `latitude` and `longitude`. The tool is a textual search tool and behaves similarly to searching on Maps, in that local queries ("near me") will use the coordinates, while specific or non-local queries are unlikely to be influenced by the explicit location.1763. **Data retrieval:** The Grounding with Google Maps service queries Google Maps for relevant information (e.g., places, reviews, photos, addresses, opening hours).1774. **Grounded generation:** The retrieved Maps data is used to inform the Gemini model's response, ensuring factual accuracy and relevance.1785. **Response \& annotations:** The model returns a text response with inline annotations linking to Google Maps sources, allowing developers to display citations.179180## Why and when to use Grounding with Google Maps181182Grounding with Google Maps is ideal for applications that require accurate,183up-to-date, and location-specific information. It enhances the user experience184by providing relevant and personalized content backed by Google Maps' extensive185database of over 250 million places worldwide.186187You should use Grounding with Google Maps when your application needs to:188189- Provide complete and accurate responses to geo-specific questions.190- Build conversational trip planners and local guides.191- Recommend points of interest based on location and user preferences like restaurants or shops.192- Create location-aware experiences for social, retail, or food delivery services.193194Grounding with Google Maps excels in use cases where proximity and current195factual data are critical, such as finding the "best coffee shop near me" or196getting directions.197198## Use cases199200Grounding with Google Maps supports a variety of location-aware use cases.201202### Handling place-specific questions203204Ask detailed questions about a specific place to get answers based on Google205user reviews and other Maps data.206207### Python208209 # This will only work for SDK newer than 2.0.0210 from google import genai211212 client = genai.Client()213214 interaction = client.interactions.create(215 model="gemini-3.8-flash",216 input="Is there a cafe near the corner of 1st and Main that has outdoor seating?",217 tools=[{218 "type": "google_maps",219 "latitude": 34.050481,220 "longitude": -118.248526221 }]222 )223224 for step in interaction.steps:225 if step.type == "model_output":226 for content_block in step.content:227 if content_block.type == "text":228 print(content_block.text)229 if content_block.annotations:230 print("\nSources:")231 for annotation in content_block.annotations:232 if annotation.type == "place_citation":233 print(f" - {annotation.name}: {annotation.url}")234235### JavaScript236237 // This will only work for SDK newer than 2.0.0238 import { GoogleGenAI } from "@google/genai";239240 const ai = new GoogleGenAI({});241242 async function main() {243 const interaction = await ai.interactions.create({244 model: "gemini-3.8-flash",245 input: "Is there a cafe near the corner of 1st and Main that has outdoor seating?",246 tools: [{247 type: "google_maps",248 latitude: 34.050481,249 longitude: -118.248526250 }]251 });252253 for (const step of interaction.steps) {254 if (step.type === 'model_output') {255 for (const contentBlock of step.content) {256 if (contentBlock.type === 'text') {257 console.log(contentBlock.text);258 if (contentBlock.annotations) {259 console.log("\nSources:");260 for (const annotation of contentBlock.annotations) {261 if (annotation.type === 'place_citation') {262 console.log(` - ${annotation.name}: ${annotation.url}`);263 }264 }265 }266 }267 }268 }269 }270 }271272 main();273274### Java275276 import com.google.genai.Client;277 import com.google.genai.gaos.models.interactions.Annotation;278 import com.google.genai.gaos.models.interactions.Content;279 import com.google.genai.gaos.models.interactions.CreateModelInteraction;280 import com.google.genai.gaos.models.interactions.GoogleMaps;281 import com.google.genai.gaos.models.interactions.Interaction;282 import com.google.genai.gaos.models.interactions.InteractionsInput;283 import com.google.genai.gaos.models.interactions.Model;284 import com.google.genai.gaos.models.interactions.ModelOutputStep;285 import com.google.genai.gaos.models.interactions.PlaceCitation;286 import com.google.genai.gaos.models.interactions.Step;287 import com.google.genai.gaos.models.interactions.TextContent;288 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;289 import java.util.Arrays;290291 Client client = new Client();292293 CreateModelInteraction params =294 CreateModelInteraction.builder()295 .model(Model.of("gemini-3.8-flash"))296 .input(297 InteractionsInput.of(298 "Is there a cafe near the corner of 1st and Main that has outdoor seating?"))299 .tools(300 Arrays.asList(301 GoogleMaps.builder().latitude(34.050481).longitude(-118.248526).build()))302 .build();303304 Interaction interaction =305 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();306307 if (interaction.steps().isPresent()) {308 for (Step step : interaction.steps().get()) {309 if (step instanceof ModelOutputStep) {310 ModelOutputStep outputStep = (ModelOutputStep) step;311 if (outputStep.content().isPresent()) {312 for (Content contentBlock : outputStep.content().get()) {313 if (contentBlock instanceof TextContent) {314 TextContent textContent = (TextContent) contentBlock;315 System.out.println(textContent.text().orElse(""));316 if (textContent.annotations().isPresent()317 && !textContent.annotations().get().isEmpty()) {318 System.out.println("\nSources:");319 for (Annotation annotation : textContent.annotations().get()) {320 if (annotation instanceof PlaceCitation) {321 PlaceCitation citation = (PlaceCitation) annotation;322 System.out.printf(323 " - %s: %s%n", citation.name().orElse(""), citation.url().orElse(""));324 }325 }326 }327 }328 }329 }330 }331 }332 }333334### Providing location-based personalization335336Get recommendations tailored to a user's preferences and a specific geographical337area.338339### Python340341 # This will only work for SDK newer than 2.0.0342 from google import genai343344 client = genai.Client()345346 interaction = client.interactions.create(347 model="gemini-3.8-flash",348 input="Which family-friendly restaurants near here have the best playground reviews?",349 tools=[{350 "type": "google_maps",351 "latitude": 30.2672,352 "longitude": -97.7431353 }]354 )355356 for step in interaction.steps:357 if step.type == "model_output":358 for content_block in step.content:359 if content_block.type == "text":360 print(content_block.text)361 if content_block.annotations:362 print("\nSources:")363 for annotation in content_block.annotations:364 if annotation.type == "place_citation":365 print(f" - {annotation.name}: {annotation.url}")366367### JavaScript368369 // This will only work for SDK newer than 2.0.0370 import { GoogleGenAI } from "@google/genai";371372 const ai = new GoogleGenAI({});373374 async function main() {375 const interaction = await ai.interactions.create({376 model: "gemini-3.8-flash",377 input: "Which family-friendly restaurants near here have the best playground reviews?",378 tools: [{379 type: "google_maps",380 latitude: 30.2672,381 longitude: -97.7431382 }]383 });384385 for (const step of interaction.steps) {386 if (step.type === 'model_output') {387 for (const contentBlock of step.content) {388 if (contentBlock.type === 'text') {389 console.log(contentBlock.text);390 if (contentBlock.annotations) {391 console.log("\nSources:");392 for (const annotation of contentBlock.annotations) {393 if (annotation.type === 'place_citation') {394 console.log(` - ${annotation.name}: ${annotation.url}`);395 }396 }397 }398 }399 }400 }401 }402 }403404 main();405406### Java407408 import com.google.genai.Client;409 import com.google.genai.gaos.models.interactions.Annotation;410 import com.google.genai.gaos.models.interactions.Content;411 import com.google.genai.gaos.models.interactions.CreateModelInteraction;412 import com.google.genai.gaos.models.interactions.GoogleMaps;413 import com.google.genai.gaos.models.interactions.Interaction;414 import com.google.genai.gaos.models.interactions.InteractionsInput;415 import com.google.genai.gaos.models.interactions.Model;416 import com.google.genai.gaos.models.interactions.ModelOutputStep;417 import com.google.genai.gaos.models.interactions.PlaceCitation;418 import com.google.genai.gaos.models.interactions.Step;419 import com.google.genai.gaos.models.interactions.TextContent;420 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;421 import java.util.Arrays;422423 Client client = new Client();424425 CreateModelInteraction params =426 CreateModelInteraction.builder()427 .model(Model.of("gemini-3.8-flash"))428 .input(429 InteractionsInput.of(430 "Which family-friendly restaurants near here have the best playground reviews?"))431 .tools(432 Arrays.asList(GoogleMaps.builder().latitude(30.2672).longitude(-97.7431).build()))433 .build();434435 Interaction interaction =436 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();437438 if (interaction.steps().isPresent()) {439 for (Step step : interaction.steps().get()) {440 if (step instanceof ModelOutputStep) {441 ModelOutputStep outputStep = (ModelOutputStep) step;442 if (outputStep.content().isPresent()) {443 for (Content contentBlock : outputStep.content().get()) {444 if (contentBlock instanceof TextContent) {445 TextContent textContent = (TextContent) contentBlock;446 System.out.println(textContent.text().orElse(""));447 if (textContent.annotations().isPresent()448 && !textContent.annotations().get().isEmpty()) {449 System.out.println("\nSources:");450 for (Annotation annotation : textContent.annotations().get()) {451 if (annotation instanceof PlaceCitation) {452 PlaceCitation citation = (PlaceCitation) annotation;453 System.out.printf(454 " - %s: %s%n", citation.name().orElse(""), citation.url().orElse(""));455 }456 }457 }458 }459 }460 }461 }462 }463 }464465### Assisting with itinerary planning466467Generate multi-day plans with directions and information about various468locations, perfect for travel applications.469470### Python471472 # This will only work for SDK newer than 2.0.0473 from google import genai474475 client = genai.Client()476477 prompt = "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner."478479 interaction = client.interactions.create(480 model="gemini-3.8-flash",481 input=prompt,482 tools=[{483 "type": "google_maps",484 "latitude": 37.78193,485 "longitude": -122.40476486 }]487 )488 # ... code to process response489490### JavaScript491492 // This will only work for SDK newer than 2.0.0493 import { GoogleGenAI } from "@google/genai";494495 const ai = new GoogleGenAI({});496497 async function main() {498 const interaction = await ai.interactions.create({499 model: "gemini-3.8-flash",500 input: "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner.",501 tools: [{502 type: "google_maps",503 latitude: 37.78193,504 longitude: -122.40476505 }]506 });507 }508509 main();510511### Java512513 import com.google.genai.Client;514 import com.google.genai.gaos.models.interactions.CreateModelInteraction;515 import com.google.genai.gaos.models.interactions.GoogleMaps;516 import com.google.genai.gaos.models.interactions.Interaction;517 import com.google.genai.gaos.models.interactions.InteractionsInput;518 import com.google.genai.gaos.models.interactions.Model;519 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;520 import java.util.Arrays;521522 Client client = new Client();523524 String prompt =525 "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner.";526527 CreateModelInteraction params =528 CreateModelInteraction.builder()529 .model(Model.of("gemini-3.8-flash"))530 .input(InteractionsInput.of(prompt))531 .tools(532 Arrays.asList(GoogleMaps.builder().latitude(37.78193).longitude(-122.40476).build()))533 .build();534535 Interaction interaction =536 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();537538 // ... code to process response539 System.out.println(interaction.outputText().orElse(""));540541### REST542543 # Specifies the API revision to avoid breaking changes when they become default544 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \545 -H "x-goog-api-key: $GEMINI_API_KEY" \546 -H 'Content-Type: application/json' \547 -d '{548 "model": "gemini-3.8-flash",549 "input": "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner.",550 "tools": [{551 "type": "google_maps",552 "latitude": 37.78193,553 "longitude": -122.40476554 }]555 }'556557## Service usage requirements558559This section describes the service usage requirements for Grounding with Google560Maps.561562### Inform the user about the use of Google Maps sources563564With each Google Maps Grounded result, you'll receive source annotations on565the `model_output` step's content blocks that support each response. The following metadata is566returned:567568- source url569- name570571When presenting results from Grounding with Google Maps, you must specify the572associated Google Maps sources, and inform your users of the following:573574- The Google Maps sources must immediately follow the generated content that the sources support. This generated content is also referred to as Google Maps Grounded Result.575- The Google Maps sources must be viewable within one user interaction.576577### Display Google Maps sources with Google Maps links578579For each source annotation, a link preview must580be generated following these requirements:581582- Attribute each source to Google Maps following the Google Maps text [attribution guidelines](https://ai.google.dev/gemini-api/docs/maps-grounding#maps-attribution-guidelines).583- Display the source name provided in the response.584- Link to the source using the `url` from the annotation.585586### Google Maps text attribution guidelines587588When you attribute sources to Google Maps in text, follow these guidelines:589590- Don't modify the text Google Maps in any way:591 - Don't change the capitalization of Google Maps.592 - Don't wrap Google Maps onto multiple lines.593 - Don't localize Google Maps into another language.594 - Prevent browsers from translating Google Maps by using the HTML attribute translate="no".595596For more information about some of our Google Maps data providers and their597license terms, see the [Google Maps and Google Earth legal notices](https://www.google.com/help/legalnotices_maps/).598599## Best practices600601- **Provide user location:** For the most relevant and personalized responses, always include the `latitude` and `longitude` in your `google_maps` tool configuration when the user's location is known.602- **Inform End-Users:** Clearly inform your end-users that Google Maps data is being used to answer their queries, especially when the tool is enabled.603- **Toggle Off When Not Needed:** Grounding with Google Maps is off by default. Only enable it (`"tools": [{"type": "google_maps"}]`) when a query has a clear geographical context, to optimize performance and cost.604605## Limitations606607- Grounding with Google Maps currently only supports English language prompts and responses.608- The tool may not be available in all regions.609- Results may vary based on location accuracy and available Maps data.610- **Geographical Scope:** Grounding with Google Maps is globally available.611- **Default State:** The Grounding with Google Maps tool is off by default. You must explicitly enable it in your API requests.612613## Pricing and rate limits614615Grounding with Google Maps pricing differs depending on the model generation:616617- **Gemini 3 models:** Your project is billed for each **search query** that the model decides to execute. A single **search prompt** (your API request to the model) might result in the model executing multiple search queries to find the necessary information. Each of these queries counts as a billable use of the tool.618- **Gemini 2.5 and older models:** Your project is billed per **search prompt**. A request is only billed if the prompt successfully returns at least one Google Maps grounded result, regardless of how many individual search queries the model performed internally to get that result.619620For detailed pricing information, see the [Gemini API pricing page](https://ai.google.dev/gemini-api/docs/pricing).621622## Supported models623624The following models support Grounding with Google Maps:625626| Model | Grounding with Google Maps |627|---|---|628| [Gemini 3.8 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.8-flash) | ✔️ |629| [Gemini 3.7 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.7-flash) | ✔️ |630| [Gemini 3.6 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.6-flash) | ✔️ |631| [Gemini 3.5 Flash-Lite](https://ai.google.dev/gemini-api/docs/models/gemini-3.5-flash-lite) | ✔️ |632| [Gemini 3.5 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.5-flash) | ✔️ |633| [Gemini 3.1 Pro Preview](https://ai.google.dev/gemini-api/docs/models/gemini-3.1-pro-preview) | ✔️ |634| [Gemini 3.1 Flash-Lite](https://ai.google.dev/gemini-api/docs/models/gemini-3.1-flash-lite) | ✔️ |635| [Gemini 3 Flash Preview](https://ai.google.dev/gemini-api/docs/models/gemini-3-flash-preview) | ✔️ |636| [Gemini 2.5 Pro](https://ai.google.dev/gemini-api/docs/models/gemini-2.5-pro) | ✔️ |637| [Gemini 2.5 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-2.5-flash) | ✔️ |638| [Gemini 2.5 Flash-Lite](https://ai.google.dev/gemini-api/docs/models/gemini-2.5-flash-lite) | ✔️ |639640## Supported tool combinations641642You can use Grounding with Google Maps with other built-in tools like643[Grounding with Google Search](https://ai.google.dev/gemini-api/docs/google-search) (supported on644Gemini 3.5 Flash and later models) to power more complex use cases. Gemini 3645models also support combining these built-in tools with custom tools (function646calling). Learn more on the647[tool combinations](https://ai.google.dev/gemini-api/docs/tool-combination) page.648649## What's next650651- Learn about other [available tools](https://ai.google.dev/gemini-api/docs/tools).652- To learn more about responsible AI best practices and Gemini API's safety filters, see [the Safety settings guide](https://ai.google.dev/gemini-api/docs/safety-settings).