gemini-google-maps-tool
A production-ready CLI and Python library for querying Gemini with Google Maps grounding, connecting the model to accurate, up-to-date Google Maps data.
Quick Start
# Install
uv tool install gemini-google-maps-tool
# Set API key
export GEMINI_API_KEY="your-api-key"
# Basic query
gemini-google-maps-tool query "Best coffee shops in Amsterdam"
# Query with location
gemini-google-maps-tool query "Italian restaurants nearby" \
--lat-lon "52.37,4.89"
# Verbose mode (progressive logging)
gemini-google-maps-tool query "Sushi restaurants" -v # INFO
gemini-google-maps-tool query "Hotels" -vv # DEBUG
gemini-google-maps-tool query "Museums" -vvv # TRACE
# Markdown output with sources
gemini-google-maps-tool query "Best museums in Paris" --text
# Shell completion
eval "$(gemini-google-maps-tool completion bash)" # or zsh/fish
# Get help
gemini-google-maps-tool --help
Table of Contents
About
What is Google Maps Grounding?
Google Maps grounding connects Gemini to Google Maps' extensive database of over 250 million places worldwide, enabling:
- Location-aware responses with accurate, up-to-date information about businesses, restaurants, and attractions
- Personalized recommendations tailored to specific geographical areas
- Automatic citation generation with structured sources (titles, URIs, place IDs)
- Seamless integration via Gemini's
generateContent endpoint—no additional infrastructure needed
Learn more: Gemini API - Google Maps Grounding Documentation
Why CLI-First Design?
This tool prioritizes agent-friendly architecture and composability, making it ideal for:
- 🤖 AI Agents (Claude Code, etc.): Structured commands and informative error messages enable effective ReAct loops (Reason + Act)
- 🔧 Automation Pipelines: JSON output to stdout and logs to stderr allow seamless piping and integration
- 🧩 Reusable Building Blocks: Commands serve as building blocks for skills, MCP servers, shell scripts, and custom workflows
- 🎯 Dual-Mode Operation: Use as both a CLI tool and importable Python library
- ✅ Production Quality: Type-safe (strict mypy), comprehensive testing (pytest), and robust error handling
Use Cases
- 📍 Location-Based Queries: Find businesses, restaurants, and services near specific locations
- 🗺️ Itinerary Planning: Generate multi-day plans with directions and place recommendations
- 🔍 Place-Specific Information: Get details about specific locations, hours, reviews, and amenities
- 📊 Data Analysis: Integrate location-aware data into analytics and research workflows
- 🏗️ RAG Applications: Build retrieval-augmented generation systems with accurate geographical context
- 🌐 Location Services: Power travel, retail, or food delivery applications with Google Maps data
Features