Gemini — Grounding with Google Maps (tools[].googleMaps)
Status: DOCUMENTED + LIVE_VERIFIED (2026-09-18 run — see "Live verification" section at the end)
Sources:
- https://ai.google.dev/gemini-api/docs/generate-content/maps-grounding · https://ai.google.dev/gemini-api/docs/maps-grounding
- https://ai.google.dev/api/generate-content (#GoogleMaps #RetrievalConfig #LatLng #Maps #PlaceAnswerSources #ReviewSnippet #GroundingMetadata)
- https://ai.google.dev/gemini-api/docs/pricing · https://ai.google.dev/gemini-api/docs/changelog (GA 2025-10; Gemini 3 support 2025-12; GMP Contextual View shutdown 2026-06-15)
Last verified: 2026-09-18 (docs only)
1. Request
| Field | Type | Notes |
|---|---|---|
tools[].googleMaps |
object | {} enables Maps grounding (off by default) |
tools[].googleMaps.enableWidget |
bool | return groundingMetadata.googleMapsWidgetContextToken for the PlacesContextElement widget (the experimental "GMP Contextual View" fixed interface shuts down 2026-06-15) |
toolConfig.retrievalConfig.latLng.latitude/longitude |
number | user location (WGS84); local queries ("near me") use it, specific queries mostly don't |
toolConfig.retrievalConfig.languageCode |
BCP-47 |
Interactions API: {"type":"google_maps"}.
2. Response
| Field | Notes |
|---|---|
groundingMetadata.groundingChunks[].maps |
{uri (maps.google.com/?cid=...), title, placeId ("places/ChIJ..."), text, placeAnswerSources{reviewSnippets[{reviewId, googleMapsUri, title}]}} |
groundingMetadata.groundingSupports[] |
segment{startIndex,endIndex,text} + groundingChunkIndices[] |
groundingMetadata.webSearchQueries[] |
Maps queries issued |
groundingMetadata.googleMapsWidgetContextToken |
only when enableWidget=true |
with includeServerSideToolInvocations |
toolCall{toolType:GOOGLE_MAPS,args:{queries[]}}, toolResponse{response:{places, google_maps_widget_context_token}} |
3. Pricing & limits (docs are inconsistent — DOCUMENTATION_INCOMPLETE)
| Source | Statement |
|---|---|
| Pricing page, tools table | Free tier 500 RPD (not for Pro). Paid: 1,500 RPD free (Flash/Flash-Lite), 10,000 RPD free (Pro), then $25 / 1,000 grounded prompts |
| Pricing page, Gemini 3 model tables | 5,000 prompts / month free (shared across Gemini 3), then $14 / 1,000 search queries |
| Maps guide | $25 / 1K grounded prompts; free tier up to 500 requests/day; a request counts only when the prompt returns ≥1 Maps-grounded result; multiple Maps queries in one request count as one request; quota aligns with the model's rate limits |
Limitations: text only (no multimodal in/out), globally available, off by default, not in the Live API, not combinable with File Search, gemini-3-pro-preview page says "Not supported".
4. Supported models
Guide table: gemini-3.8-flash, 3.7-flash, 3.6-flash, 3.5-flash, 3.5-flash-lite, 3.1-pro-preview, 3.1-flash-lite, 3-flash-preview, 2.5-pro, 2.5-flash, 2.5-flash-lite. Model pages add gemini-3.1-flash-lite-preview, gemini-robotics-er-2-preview (and the retired gemini-2.0-flash). Combination with Google Search: Gemini 3.5 Flash and later; with function calling: Gemini 3 (Preview).
5. Service usage requirements (mandatory)
| Requirement | Detail |
|---|---|
| Inform users | say Google Maps sources are used |
| Show sources | sources must immediately follow the grounded content and be viewable within one interaction; collapsible allowed |
| Link previews | for every groundingChunks[].maps and placeAnswerSources.reviewSnippets[]: show the title, link uri/googleMapsUri, attribute to Google Maps |
| Text attribution | "Google Maps" unmodified (no case change, wrapping, translation; translate="no"); Roboto or sans-serif, weight 400, 12–16sp, white/#1F1F1F/#5E5E5E with 4.5:1 contrast |
| Caching | placeId and reviewId may be cached/stored/exported |
| Prohibited | high-risk uses incl. emergency response; distribution in Google Maps Platform Prohibited Territories |
6. Examples
curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash-lite:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" -H "Content-Type: application/json" \
-d '{"contents":[{"parts":[{"text":"Coffee shops near here? One line."}]}],
"tools":[{"googleMaps":{}}],
"toolConfig":{"retrievalConfig":{"latLng":{"latitude":45.5017,"longitude":-73.5673}}}}'r = client.models.generate_content(model="gemini-3.5-flash-lite", contents="Coffee shops near here?",
config=types.GenerateContentConfig(tools=[types.Tool(google_maps=types.GoogleMaps())],
tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(lat_lng=types.LatLng(latitude=45.5017, longitude=-73.5673)))))const r = await ai.models.generateContent({ model: 'gemini-3.5-flash-lite', contents: 'Coffee shops near here?',
config: { tools: [{ googleMaps: {} }], toolConfig: { retrievalConfig: { latLng: { latitude: 45.5017, longitude: -73.5673 } } } } });Live verification (2026-09-18)
LIVE_VERIFIED on gemini-3.5-flash-lite (tmp-live/gemini-tools/e_google_maps.json): tools:[{"googleMaps":{}}] + toolConfig.retrievalConfig.latLng{latitude:43.6532, longitude:-79.3832} → HTTP 200, groundingMetadata keys webSearchQueries, groundingChunks, groundingSupports; each chunk is {maps:{uri:"https://maps.google.com/maps?cid=…", title, text (address/rating/hours markdown), placeId:"ChIJ…"}}. With googleMaps.enableWidget:true (e2_google_maps_widget.json) the response had no googleMapsWidgetContextToken on this model. No 429 — Maps grounding worked on the same key that is blocked for Search grounding. Example examples/gemini/tools/google-maps/maps_grounding.py, test tests/gemini/test_tools.py::test_google_maps_grounding.