zhongwei/gh-dnvriend-gemini-google-maps-tool-plugins-gemini-google-maps-tool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:23:17 +08:00
commit 37dd213b6c
6 changed files with 691 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,14 @@
{
"name": "gemini-google-maps-tool",
"description": "CLI tool for querying Gemini with Google Maps grounding",
"version": "0.1.0",
"author": {
"name": "Dennis Vriend"
},
"skills": [
"./skills"
],
"commands": [
"./commands"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# gemini-google-maps-tool
CLI tool for querying Gemini with Google Maps grounding

34
commands/completion.md Normal file
View File

@@ -0,0 +1,34 @@
---
description: Generate shell completion scripts
argument-hint: shell
---
Generate shell completion scripts for Bash, Zsh, or Fish to enable tab-completion.
## Usage
```bash
gemini-google-maps-tool completion {bash|zsh|fish}
```
## Arguments
- `SHELL`: Shell type - bash, zsh, or fish (required)
## Examples
```bash
# Generate Bash completion
eval "$(gemini-google-maps-tool completion bash)"
# Generate Zsh completion
eval "$(gemini-google-maps-tool completion zsh)"
# Install Fish completion
gemini-google-maps-tool completion fish > \
~/.config/fish/completions/gemini-google-maps-tool.fish
```
## Output
Shell-specific completion script that can be evaluated or saved to a file.

45
commands/query.md Normal file
View File

@@ -0,0 +1,45 @@
---
description: Query Gemini with Google Maps location data
argument-hint: query
---
Query Gemini with Google Maps grounding for location-aware information about places, businesses, and attractions.
## Usage
```bash
gemini-google-maps-tool query "QUERY" [OPTIONS]
```
## Arguments
- `QUERY`: Search query (required)
- `--lat-lon LAT,LON`: Location coordinates (e.g., "52.37,4.89")
- `--model {flash|flash-lite}`: Model selection (default: flash-lite)
- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE)
- `--text` / `-t`: Output markdown instead of JSON
- `--stdin` / `-s`: Read query from stdin
## Examples
```bash
# 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
# Verbose mode with full metadata
gemini-google-maps-tool query "Best sushi" -v
# From stdin for pipeline
echo "Best hotels in NYC" | gemini-google-maps-tool query --stdin
```
## Output
JSON (default) with `response_text` and optional `grounding_metadata`, or markdown text with citations.

53
plugin.lock.json Normal file
View File

@@ -0,0 +1,53 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:dnvriend/gemini-google-maps-tool:plugins/gemini-google-maps-tool",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "112d8631ccc363579211c2fd094a03076e7b9e38",
"treeHash": "bac53f7562b28581c8284ba830b3eb2e63d3ca80224fc9a01b2ba61389663ec0",
"generatedAt": "2025-11-28T10:16:35.528800Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "gemini-google-maps-tool",
"description": "CLI tool for querying Gemini with Google Maps grounding",
"version": "0.1.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "280f9b9634562dc13c75226c0706e932b3bc6ff88f927dda482b85342ff328ca"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "3b78b85f758c58387a9d64f26cd4bc97676e501b1833b2001fec5d86ebdd36aa"
},
{
"path": "commands/completion.md",
"sha256": "aafe2f723052e1eb9d7088e7f4249ec57cec10df97cea0a23bb52d968448b734"
},
{
"path": "commands/query.md",
"sha256": "dd12580ec68cd29b8f4a9a1dd417ff1069e41aae80e62f856e1e198c42e53abd"
},
{
"path": "skills/gemini-google-maps-tool/SKILL.md",
"sha256": "e56cc02fe9747ba62a923bf829cb34ba6ae0c2eda51583a591258918fd32e532"
}
],
"dirSha256": "bac53f7562b28581c8284ba830b3eb2e63d3ca80224fc9a01b2ba61389663ec0"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

542
skills/gemini-google-maps-tool/SKILL.md Normal file
View File

@@ -0,0 +1,542 @@
---
name: skill-gemini-google-maps-tool
description: 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
```bash
# 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](https://github.com/astral-sh/uv) package manager
- Gemini API Key from [Google AI Studio](https://aistudio.google.com/app/apikey)
### Quick Start
```bash
# 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
<details>
<summary><strong>📖 Core Commands (Click to expand)</strong></summary>
### query - Query Gemini with Google Maps Grounding
Query Gemini with Google Maps integration for location-aware information about places, businesses, directions, and attractions.
**Usage:**
```bash
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:**
```bash
# 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):
```json
{
"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):
```markdown
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:**
```bash
gemini-google-maps-tool completion {bash|zsh|fish}
```
**Arguments:**
- `SHELL`: Shell type (required) - bash, zsh, or fish
**Examples:**
```bash
# 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.
</details>
<details>
<summary><strong>⚙️ Advanced Features (Click to expand)</strong></summary>
### 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:**
```bash
# 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:**
```bash
gemini-google-maps-tool query "Best pizza in Brooklyn" -v
```
Returns JSON with:
```json
{
"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:**
```bash
# 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:**
```bash
# 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:**
```python
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:**
```python
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:**
```python
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}")
```
</details>
<details>
<summary><strong>🔧 Troubleshooting (Click to expand)</strong></summary>
### Common Issues
**Issue: GEMINI_API_KEY not set**
```bash
Error: GEMINI_API_KEY environment variable is required.
```
**Solution:**
```bash
# 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**
```bash
ValueError: Invalid lat-lon format
```
**Solution:**
- Use format: "latitude,longitude"
- Latitude range: -90 to 90
- Longitude range: -180 to 180
```bash
# 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**
```bash
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**
```bash
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
```bash
# 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:
```bash
# 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
```
</details>
## 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
1. **Use location context for better results**: Provide `--lat-lon` when asking about specific areas
2. **Choose appropriate model**: Use `flash-lite` (default) for simple queries, `flash` for complex tasks
3. **Enable verbosity for debugging**: Use `-v`, `-vv`, or `-vvv` to understand what's happening
4. **Secure API key storage**: Use environment variables or keychain instead of hardcoding
5. **Monitor API usage**: Google Maps grounding costs $25 per 1,000 prompts
6. **Use JSON for automation**: Default JSON output is perfect for scripts and pipelines
7. **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](https://console.cloud.google.com/)
Learn more: [Gemini API Pricing](https://ai.google.dev/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/