zhongwei/gh-dnvriend-gemini-google-maps-tool-plugins-gemini-google-maps-tool

Files

Zhongwei Li 37dd213b6c Initial commit

2025-11-29 18:23:17 +08:00

13 KiB

Raw Blame History

name, description

name	description
skill-gemini-google-maps-tool	Query Gemini with Google Maps grounding

When to use

When you need location-aware AI responses about places
When you need recommendations for restaurants, hotels, attractions
When you need accurate, up-to-date information from Google Maps

Gemini Google Maps Tool Skill

Purpose

Comprehensive guide for using gemini-google-maps-tool, a CLI and Python library that connects Gemini to Google Maps' database of 250+ million places worldwide for location-aware responses with accurate, up-to-date information.

When to Use This Skill

Use this skill when:

Querying for location-based recommendations (restaurants, hotels, attractions)
Generating itineraries with place-specific information
Building applications that need location-aware AI responses
Integrating Google Maps data into AI workflows
Creating travel, food, or local business applications

Do NOT use this skill for:

General Gemini queries without location context
Tasks that don't involve places or geographical information
Direct Google Maps API queries (this uses Gemini with Maps grounding)

CLI Tool: gemini-google-maps-tool

A production-ready CLI and Python library for querying Gemini with Google Maps grounding.

Installation

# Install globally with uv tool
uv tool install gemini-google-maps-tool

# Or from source
git clone https://github.com/dnvriend/gemini-google-maps-tool.git
cd gemini-google-maps-tool
uv tool install .

Prerequisites

Python 3.14+
uv package manager
Gemini API Key from Google AI Studio

Quick Start

# Set API key
export GEMINI_API_KEY="your-api-key"

# Basic query
gemini-google-maps-tool query "Best coffee shops in Amsterdam"

# With location context
gemini-google-maps-tool query "Italian restaurants nearby" \
  --lat-lon "52.37,4.89"

# Markdown output with sources
gemini-google-maps-tool query "Museums in Paris" --text

Progressive Disclosure

📖 Core Commands (Click to expand)

query - Query Gemini with Google Maps Grounding

Query Gemini with Google Maps integration for location-aware information about places, businesses, directions, and attractions.

Usage:

gemini-google-maps-tool query "QUERY" [OPTIONS]

Arguments:

QUERY: The search query (required unless using --stdin)
--lat-lon LAT,LON: Location coordinates in format "lat,lon" (e.g., "37.78193,-122.40476")
--model {flash|flash-lite}: Model selection
- flash: gemini-2.5-flash (more powerful, higher cost)
- flash-lite: gemini-2.5-flash-lite (default, faster, cost-effective)
-v, --verbose: Enable INFO logging (operation-level details)
-vv: Enable DEBUG logging (detailed API calls, validation)
-vvv: Enable TRACE logging (full HTTP traces, library internals)
--text / -t: Output markdown text instead of JSON
--stdin / -s: Read query from stdin

Examples:

# Basic query
gemini-google-maps-tool query "Best coffee shops in Amsterdam"

# With location context
gemini-google-maps-tool query "Italian restaurants nearby" \
  --lat-lon "52.37,4.89"

# Using different model
gemini-google-maps-tool query "Plan a day in NYC" --model flash

# Markdown output with sources
gemini-google-maps-tool query "Best museums in Paris" --text

# Verbose mode with grounding metadata
gemini-google-maps-tool query "Sushi restaurants" -v

# Debug mode with full details
gemini-google-maps-tool query "Hotels in London" -vv

# Trace mode with HTTP details
gemini-google-maps-tool query "Attractions in Rome" -vvv

# Reading from stdin (for pipelines)
echo "Best bakeries in San Francisco" | \
  gemini-google-maps-tool query --stdin

# Pipeline with jq
gemini-google-maps-tool query "Coffee shops" | \
  jq '.response_text'

Output Formats:

JSON (default):

{
  "response_text": "Here are some great coffee shops...",
  "grounding_metadata": {
    "grounding_chunks": [
      {
        "title": "Blue Bottle Coffee",
        "uri": "https://maps.google.com/?cid=...",
        "place_id": "places/ChIJ..."
      }
    ]
  }
}

Markdown (with --text):

Here are some great coffee shops...

---

## Sources

1. [Blue Bottle Coffee](https://maps.google.com/?cid=...)
2. [Philz Coffee](https://maps.google.com/?cid=...)

completion - Generate Shell Completion Scripts

Generate shell completion scripts for Bash, Zsh, or Fish to enable tab-completion for commands and options.

Usage:

gemini-google-maps-tool completion {bash|zsh|fish}

Arguments:

SHELL: Shell type (required) - bash, zsh, or fish

Examples:

# Bash - temporary (current session)
eval "$(gemini-google-maps-tool completion bash)"

# Bash - persistent
echo 'eval "$(gemini-google-maps-tool completion bash)"' >> ~/.bashrc

# Zsh - temporary
eval "$(gemini-google-maps-tool completion zsh)"

# Zsh - persistent
echo 'eval "$(gemini-google-maps-tool completion zsh)"' >> ~/.zshrc

# Fish - install to completions directory
gemini-google-maps-tool completion fish > \
  ~/.config/fish/completions/gemini-google-maps-tool.fish

# File-based (better performance)
gemini-google-maps-tool completion bash > \
  ~/.gemini-google-maps-tool-complete.bash
echo 'source ~/.gemini-google-maps-tool-complete.bash' >> ~/.bashrc

Output: Shell-specific completion script that can be evaluated or saved to a file.

⚙️ Advanced Features (Click to expand)

Multi-Level Verbosity Logging

Progressive detail control for debugging and monitoring:

No flag (default): WARNING level - only critical issues
-v: INFO level - high-level operations, important events
-vv: DEBUG level - detailed operations, API calls, validation steps
-vvv: TRACE level - full request/response, library internals, HTTP traces

Examples:

# INFO: See which files are processed
gemini-google-maps-tool query "Best restaurants" -v

# DEBUG: See API call details and validation
gemini-google-maps-tool query "Hotels nearby" -vv

# TRACE: See full HTTP requests/responses
gemini-google-maps-tool query "Museums" -vvv

Google Maps Grounding

What is it? Google Maps grounding connects Gemini to Google Maps' database of 250+ million places worldwide, providing:

Location-aware responses with accurate, up-to-date information
Personalized recommendations tailored to specific areas
Automatic citation generation with structured sources
Seamless integration via Gemini's API

Grounding Metadata: With -v or --text, responses include:

Grounding Chunks: Google Maps sources (title, URI, place_id)
Grounding Supports: Text segments linked to sources
Widget Context Token: For interactive maps integration

Example:

gemini-google-maps-tool query "Best pizza in Brooklyn" -v

Returns JSON with:

{
  "response_text": "...",
  "grounding_metadata": {
    "grounding_chunks": [
      {
        "title": "Roberta's Pizza",
        "uri": "https://maps.google.com/?cid=...",
        "place_id": "places/ChIJ..."
      }
    ],
    "grounding_supports": [...],
    "google_maps_widget_context_token": "..."
  }
}

Location Context

Provide location coordinates for personalized, location-aware responses:

Format: --lat-lon "latitude,longitude"

Examples:

# Amsterdam center
gemini-google-maps-tool query "Coffee shops nearby" \
  --lat-lon "52.37,4.89"

# San Francisco
gemini-google-maps-tool query "Italian restaurants" \
  --lat-lon "37.78,-122.40"

# Tokyo
gemini-google-maps-tool query "Sushi restaurants" \
  --lat-lon "35.68,139.76"

Coordinate Ranges:

Latitude: -90 to 90
Longitude: -180 to 180

Model Selection

Choose between two Gemini models:

flash-lite (default):

Model: gemini-2.5-flash-lite
Faster, more cost-effective
Best for simple location queries
Recommended for most use cases

flash:

Model: gemini-2.5-flash
More powerful and capable
Best for complex queries and itinerary planning
Higher cost

Examples:

# Default (flash-lite)
gemini-google-maps-tool query "Best restaurants"

# Explicit flash-lite
gemini-google-maps-tool query "Hotels" --model flash-lite

# Use flash for complex queries
gemini-google-maps-tool query "Plan a 3-day trip to Paris" \
  --model flash

Python Library Usage

Import and use programmatically in Python applications:

Basic Usage:

from gemini_google_maps_tool import get_client, query_maps

# Initialize client
client = get_client()

# Execute query
result = query_maps(
    client=client,
    query="Best coffee shops near me",
)

print(result.response_text)

With Location and Grounding:

from gemini_google_maps_tool import get_client, query_maps

client = get_client()

result = query_maps(
    client=client,
    query="Italian restaurants nearby",
    lat_lon=(37.78193, -122.40476),
    model="gemini-2.5-flash",
    include_grounding=True,
)

# Access response
print(result.response_text)

# Access grounding metadata
if result.grounding_metadata:
    for chunk in result.grounding_metadata.grounding_chunks:
        print(f"Source: {chunk.title} - {chunk.uri}")

Error Handling:

from gemini_google_maps_tool import (
    get_client,
    query_maps,
    ClientError,
    QueryError,
)

try:
    client = get_client()
    result = query_maps(client, "Best restaurants")
    print(result.response_text)
except ClientError as e:
    print(f"Client error: {e}")
except QueryError as e:
    print(f"Query error: {e}")

🔧 Troubleshooting (Click to expand)

Common Issues

Issue: GEMINI_API_KEY not set

Error: GEMINI_API_KEY environment variable is required.

Solution:

# Set for current session
export GEMINI_API_KEY="your-api-key"

# Or add to shell profile
echo 'export GEMINI_API_KEY="your-api-key"' >> ~/.zshrc
source ~/.zshrc

# Or retrieve from macOS Keychain
export GEMINI_API_KEY=$(security find-generic-password \
  -a "production" -s "GEMINI_API_KEY" -w)

Issue: Invalid lat-lon format

ValueError: Invalid lat-lon format

Solution:

Use format: "latitude,longitude"
Latitude range: -90 to 90
Longitude range: -180 to 180

# Correct
gemini-google-maps-tool query "restaurants" --lat-lon "52.37,4.89"

# Incorrect
gemini-google-maps-tool query "restaurants" --lat-lon "52.37 4.89"
gemini-google-maps-tool query "restaurants" --lat-lon "200,50"

Issue: API returns no response candidates

QueryError: API returned no response candidates

Possible causes:

Rate limiting (too many requests)
API service issues
Query content filtering
Insufficient API quota

Solution:

Wait a few seconds and retry
Rephrase your query
Check API quota in Google Cloud Console
Verify API key is valid and active

Issue: Empty response text

QueryError: API returned empty response text

Possible causes:

Content filtering or safety blocks
Query processing issues
Incomplete API response

Solution:

Rephrase query with different wording
Try simpler or more specific query
Wait and retry
Check if query violates content policies

Getting Help

# Main help
gemini-google-maps-tool --help

# Command-specific help
gemini-google-maps-tool query --help
gemini-google-maps-tool completion --help

# Version information
gemini-google-maps-tool --version

Debug Mode

Enable verbose logging to diagnose issues:

# INFO level
gemini-google-maps-tool query "test" -v

# DEBUG level (detailed)
gemini-google-maps-tool query "test" -vv

# TRACE level (full HTTP traces)
gemini-google-maps-tool query "test" -vvv

Output Formats

JSON (default):

Structured data with response_text field
Optional grounding_metadata with -v
Easy to parse and pipe to other tools
Logs to stderr, JSON to stdout

Markdown (--text):

Human-readable text
Automatic source citations
Clean formatting
Includes "Sources" section with links

Best Practices

Use location context for better results: Provide --lat-lon when asking about specific areas
Choose appropriate model: Use flash-lite (default) for simple queries, flash for complex tasks
Enable verbosity for debugging: Use -v, -vv, or -vvv to understand what's happening
Secure API key storage: Use environment variables or keychain instead of hardcoding
Monitor API usage: Google Maps grounding costs $25 per 1,000 prompts
Use JSON for automation: Default JSON output is perfect for scripts and pipelines
Cache completion scripts: Generate to file instead of eval for better performance

Pricing

Google Maps Grounding: $25 per 1,000 grounded prompts
Free Tier: Up to 500 requests per day
Monitor usage: Google Cloud Console

Learn more: Gemini API Pricing

Resources

GitHub: https://github.com/dnvriend/gemini-google-maps-tool
Google Maps Grounding Docs: https://ai.google.dev/gemini-api/docs/maps-grounding
Gemini API Documentation: https://ai.google.dev/gemini-api/docs
Get API Key: https://aistudio.google.com/app/apikey
Google AI Studio: https://aistudio.google.com/

13 KiB Raw Blame History

When to use

Gemini Google Maps Tool Skill

Purpose

When to Use This Skill

CLI Tool: gemini-google-maps-tool

Installation

Prerequisites

Quick Start

Progressive Disclosure

query - Query Gemini with Google Maps Grounding

completion - Generate Shell Completion Scripts

Multi-Level Verbosity Logging

Google Maps Grounding

Location Context

Model Selection

Python Library Usage

Common Issues

Getting Help

Debug Mode

Output Formats

Best Practices

Pricing

Resources

13 KiB

Raw Blame History