commit 37dd213b6c45bfbb82412a4c1311a4e692cda4f3 Author: Zhongwei Li Date: Sat Nov 29 18:23:17 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..dcafbcf --- /dev/null +++ b/.claude-plugin/plugin.json @@ -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" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..1a5f9b2 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# gemini-google-maps-tool + +CLI tool for querying Gemini with Google Maps grounding diff --git a/commands/completion.md b/commands/completion.md new file mode 100644 index 0000000..a92290e --- /dev/null +++ b/commands/completion.md @@ -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. diff --git a/commands/query.md b/commands/query.md new file mode 100644 index 0000000..506028d --- /dev/null +++ b/commands/query.md @@ -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. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..ed8fd6e --- /dev/null +++ b/plugin.lock.json @@ -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": [] + } +} \ No newline at end of file diff --git a/skills/gemini-google-maps-tool/SKILL.md b/skills/gemini-google-maps-tool/SKILL.md new file mode 100644 index 0000000..80fafbe --- /dev/null +++ b/skills/gemini-google-maps-tool/SKILL.md @@ -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 + +
+📖 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:** +```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. + +
+ +
+⚙️ 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:** +```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}") +``` + +
+ +
+🔧 Troubleshooting (Click to expand) + +### 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 +``` + +
+ +## 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/