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 Permalink 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 Permalink 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 Permalink Blame History