skill-gemini-google-maps-tool

What this skill does

# 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
- Rec