Repository Public
1> [!NOTE]2> **Note** : This version of the page covers the new [Interactions API](https://ai.google.dev/gemini-api/docs/interactions/interactions-overview), which is currently in Beta. 3> For stable production deployments, we recommend you continue to use the `generateContent` API. You can use the toggle on this page to switch between the versions.45Grounding with Google Maps connects the generative capabilities of Gemini with6the rich, factual, and up-to-date data of Google Maps. This feature enables7developers to easily incorporate location-aware functionality into their8applications. When a user query has a context related to Maps data, the Gemini9model leverages Google Maps to provide factually accurate and fresh answers that10are relevant to the user's specified location or general area.1112- **Accurate, location-aware responses:** Leverage Google Maps' extensive and current data for geographically specific queries.13- **Enhanced personalization:** Tailor recommendations and information based on user-provided locations.1415## Get started1617This example demonstrates how to integrate Grounding with Google Maps into your18application to provide accurate, location-aware responses to user queries. The19prompt asks for local recommendations with an optional user location, enabling20the Gemini model to use Google Maps data.2122### Python2324 # This will only work for SDK newer than 2.0.025 from google import genai2627 client = genai.Client()2829 interaction = client.interactions.create(30 model="gemini-3.5-flash",31 input="What are the best Italian restaurants within a 15-minute walk from here?",32 tools=[{33 "type": "google_maps",34 "latitude": 34.050481,35 "longitude": -118.24852636 }]37 )3839 # Print the model's text response and annotations40 for step in interaction.steps:41 if step.type == "model_output":42 for content_block in step.content:43 if content_block.type == "text":44 print(content_block.text)45 if content_block.annotations:46 print("\nSources:")47 for annotation in content_block.annotations:48 if annotation.type == "place_citation":49 print(f" - {annotation.name}: {annotation.url}")5051### JavaScript5253 // This will only work for SDK newer than 2.0.054 import { GoogleGenAI } from "@google/genai";5556 const ai = new GoogleGenAI({});5758 async function main() {59 const interaction = await ai.interactions.create({60 model: "gemini-3.5-flash",61 input: "What are the best Italian restaurants within a 15-minute walk from here?",62 tools: [{63 type: "google_maps",64 latitude: 34.050481,65 longitude: -118.24852666 }]67 });6869 // Print the model's text response and annotations70 for (const step of interaction.steps) {71 if (step.type === 'model_output') {72 for (const contentBlock of step.content) {73 if (contentBlock.type === 'text') {74 console.log(contentBlock.text);75 if (contentBlock.annotations) {76 console.log("\nSources:");77 for (const annotation of contentBlock.annotations) {78 if (annotation.type === 'place_citation') {79 console.log(` - {annotation.name}: {annotation.url}`);80 }81 }82 }83 }84 }85 }86 }87 }8889 main();9091### REST9293 # Specifies the API revision to avoid breaking changes when they become default94 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \95 -H "x-goog-api-key: $GEMINI_API_KEY" \96 -H 'Content-Type: application/json' \97 -H "Api-Revision: 2026-05-20" \98 -d '{99 "model": "gemini-3.5-flash",100 "input": "What are the best Italian restaurants within a 15-minute walk from here?",101 "tools": [{102 "type": "google_maps",103 "latitude": 34.050481,104 "longitude": -118.248526105 }]106 }'107108## How Grounding with Google Maps works109110Grounding with Google Maps integrates the Gemini API with the Google Geo111ecosystem by using the Maps API as a grounding source. When a user's query112contains geographical context, the Gemini model can invoke the Grounding with113Google Maps tool. The model can then generate responses grounded in Google Maps114data relevant to the provided location.115116The process typically involves:1171181. **User query:** A user submits a query to your application, potentially including geographical context (e.g., "coffee shops near me," "museums in San Francisco").1192. **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.1203. **Data retrieval:** The Grounding with Google Maps service queries Google Maps for relevant information (e.g., places, reviews, photos, addresses, opening hours).1214. **Grounded generation:** The retrieved Maps data is used to inform the Gemini model's response, ensuring factual accuracy and relevance.1225. **Response \& annotations:** The model returns a text response with inline annotations linking to Google Maps sources, allowing developers to display citations.123124## Why and when to use Grounding with Google Maps125126Grounding with Google Maps is ideal for applications that require accurate,127up-to-date, and location-specific information. It enhances the user experience128by providing relevant and personalized content backed by Google Maps' extensive129database of over 250 million places worldwide.130131You should use Grounding with Google Maps when your application needs to:132133- Provide complete and accurate responses to geo-specific questions.134- Build conversational trip planners and local guides.135- Recommend points of interest based on location and user preferences like restaurants or shops.136- Create location-aware experiences for social, retail, or food delivery services.137138Grounding with Google Maps excels in use cases where proximity and current139factual data are critical, such as finding the "best coffee shop near me" or140getting directions.141142## Use cases143144Grounding with Google Maps supports a variety of location-aware use cases.145146### Handling place-specific questions147148Ask detailed questions about a specific place to get answers based on Google149user reviews and other Maps data.150151### Python152153 # This will only work for SDK newer than 2.0.0154 from google import genai155156 client = genai.Client()157158 interaction = client.interactions.create(159 model="gemini-3.5-flash",160 input="Is there a cafe near the corner of 1st and Main that has outdoor seating?",161 tools=[{162 "type": "google_maps",163 "latitude": 34.050481,164 "longitude": -118.248526165 }]166 )167168 for step in interaction.steps:169 if step.type == "model_output":170 for content_block in step.content:171 if content_block.type == "text":172 print(content_block.text)173 if content_block.annotations:174 print("\nSources:")175 for annotation in content_block.annotations:176 if annotation.type == "place_citation":177 print(f" - {annotation.name}: {annotation.url}")178179### JavaScript180181 // This will only work for SDK newer than 2.0.0182 import { GoogleGenAI } from "@google/genai";183184 const ai = new GoogleGenAI({});185186 async function main() {187 const interaction = await ai.interactions.create({188 model: "gemini-3.5-flash",189 input: "Is there a cafe near the corner of 1st and Main that has outdoor seating?",190 tools: [{191 type: "google_maps",192 latitude: 34.050481,193 longitude: -118.248526194 }]195 });196197 for (const step of interaction.steps) {198 if (step.type === 'model_output') {199 for (const contentBlock of step.content) {200 if (contentBlock.type === 'text') {201 console.log(contentBlock.text);202 if (contentBlock.annotations) {203 console.log("\nSources:");204 for (const annotation of contentBlock.annotations) {205 if (annotation.type === 'place_citation') {206 console.log(` - ${annotation.name}: ${annotation.url}`);207 }208 }209 }210 }211 }212 }213 }214 }215216 main();217218### Providing location-based personalization219220Get recommendations tailored to a user's preferences and a specific geographical221area.222223### Python224225 # This will only work for SDK newer than 2.0.0226 from google import genai227228 client = genai.Client()229230 interaction = client.interactions.create(231 model="gemini-3.5-flash",232 input="Which family-friendly restaurants near here have the best playground reviews?",233 tools=[{234 "type": "google_maps",235 "latitude": 30.2672,236 "longitude": -97.7431237 }]238 )239240 for step in interaction.steps:241 if step.type == "model_output":242 for content_block in step.content:243 if content_block.type == "text":244 print(content_block.text)245 if content_block.annotations:246 print("\nSources:")247 for annotation in content_block.annotations:248 if annotation.type == "place_citation":249 print(f" - {annotation.name}: {annotation.url}")250251### JavaScript252253 // This will only work for SDK newer than 2.0.0254 import { GoogleGenAI } from "@google/genai";255256 const ai = new GoogleGenAI({});257258 async function main() {259 const interaction = await ai.interactions.create({260 model: "gemini-3.5-flash",261 input: "Which family-friendly restaurants near here have the best playground reviews?",262 tools: [{263 type: "google_maps",264 latitude: 30.2672,265 longitude: -97.7431266 }]267 });268269 for (const step of interaction.steps) {270 if (step.type === 'model_output') {271 for (const contentBlock of step.content) {272 if (contentBlock.type === 'text') {273 console.log(contentBlock.text);274 if (contentBlock.annotations) {275 console.log("\nSources:");276 for (const annotation of contentBlock.annotations) {277 if (annotation.type === 'place_citation') {278 console.log(` - ${annotation.name}: ${annotation.url}`);279 }280 }281 }282 }283 }284 }285 }286 }287288 main();289290### Assisting with itinerary planning291292Generate multi-day plans with directions and information about various293locations, perfect for travel applications.294295### Python296297 # This will only work for SDK newer than 2.0.0298 from google import genai299300 client = genai.Client()301302 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."303304 interaction = client.interactions.create(305 model="gemini-3.5-flash",306 input=prompt,307 tools=[{308 "type": "google_maps",309 "latitude": 37.78193,310 "longitude": -122.40476311 }]312 )313 # ... code to process response314315### JavaScript316317 // This will only work for SDK newer than 2.0.0318 import { GoogleGenAI } from "@google/genai";319320 const ai = new GoogleGenAI({});321322 async function main() {323 const interaction = await ai.interactions.create({324 model: "gemini-3.5-flash",325 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.",326 tools: [{327 type: "google_maps",328 latitude: 37.78193,329 longitude: -122.40476330 }]331 });332 }333334 main();335336### REST337338 # Specifies the API revision to avoid breaking changes when they become default339 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \340 -H "x-goog-api-key: $GEMINI_API_KEY" \341 -H 'Content-Type: application/json' \342 -H "Api-Revision: 2026-05-20" \343 -d '{344 "model": "gemini-3.5-flash",345 "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.",346 "tools": [{347 "type": "google_maps",348 "latitude": 37.78193,349 "longitude": -122.40476350 }]351 }'352353## Service usage requirements354355This section describes the service usage requirements for Grounding with Google356Maps.357358### Inform the user about the use of Google Maps sources359360With each Google Maps Grounded result, you'll receive source annotations on361the `model_output` step's content blocks that support each response. The following metadata is362returned:363364- source url365- name366367When presenting results from Grounding with Google Maps, you must specify the368associated Google Maps sources, and inform your users of the following:369370- 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.371- The Google Maps sources must be viewable within one user interaction.372373### Display Google Maps sources with Google Maps links374375For each source annotation, a link preview must376be generated following these requirements:377378- Attribute each source to Google Maps following the Google Maps text [attribution guidelines](https://ai.google.dev/gemini-api/docs/interactions/maps-grounding#maps-attribution-guidelines).379- Display the source name provided in the response.380- Link to the source using the `url` from the annotation.381382### Google Maps text attribution guidelines383384When you attribute sources to Google Maps in text, follow these guidelines:385386- Don't modify the text Google Maps in any way:387 - Don't change the capitalization of Google Maps.388 - Don't wrap Google Maps onto multiple lines.389 - Don't localize Google Maps into another language.390 - Prevent browsers from translating Google Maps by using the HTML attribute translate="no".391392For more information about some of our Google Maps data providers and their393license terms, see the [Google Maps and Google Earth legal notices](https://www.google.com/help/legalnotices_maps/).394395## Best practices396397- **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.398- **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.399- **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.400401## Limitations402403- Grounding with Google Maps currently only supports English language prompts and responses.404- The tool may not be available in all regions.405- Results may vary based on location accuracy and available Maps data.406- **Geographical Scope:** Grounding with Google Maps is globally available.407- **Default State:** The Grounding with Google Maps tool is off by default. You must explicitly enable it in your API requests.408409## Pricing and rate limits410411Grounding with Google Maps pricing is based on queries. The current rate is412**$25 / 1K grounded prompts**. The free tier also has up to 500 requests per day413available. A request is only counted towards the quota when414a prompt successfully returns at least one Google Maps grounded result (i.e.,415results containing at least one Google Maps source). If multiple queries are416sent to Google Maps from a single request, it counts as one request towards the417rate limit.418419For detailed pricing information, see the [Gemini API pricing page](https://ai.google.dev/gemini-api/docs/pricing).420421## Supported models422423The following models support Grounding with Google Maps:424425| Model | Grounding with Google Maps |426|---|---|427| [Gemini 3.5 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.5-flash) | ✔️ |428| [Gemini 3.1 Pro Preview](https://ai.google.dev/gemini-api/docs/models/gemini-3.1-pro-preview) | ✔️ |429| [Gemini 3.1 Flash-Lite](https://ai.google.dev/gemini-api/docs/models/gemini-3.1-flash-lite) | ✔️ |430| [Gemini 3 Flash Preview](https://ai.google.dev/gemini-api/docs/models/gemini-3-flash-preview) | ✔️ |431| [Gemini 2.5 Pro](https://ai.google.dev/gemini-api/docs/models/gemini-2.5-pro) | ✔️ |432| [Gemini 2.5 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-2.5-flash) | ✔️ |433| [Gemini 2.5 Flash-Lite](https://ai.google.dev/gemini-api/docs/models/gemini-2.5-flash-lite) | ✔️ |434435## Supported tool combinations436437Gemini 3 models support combining built-in tools (like Grounding with Google438Maps) with custom tools (function calling). Learn more on the439[tool combinations](https://ai.google.dev/gemini-api/docs/interactions/tool-combination) page.440441## What's next442443- Learn about other [available tools](https://ai.google.dev/gemini-api/docs/tools).444- 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).