google-maps-api

What this skill does

# Google Maps Platform - Universal API Skill

## Critical Behavior Rules

**These rules override all other instructions in this skill:**

1. **Communicate blockers immediately.** When ANY API call fails (403, REQUEST_DENIED, "not enabled", etc.), STOP and tell the user what happened in plain language. Do NOT silently work around it with web search or other fallbacks. Offer to fix it via Playwright (see "Guided API Enablement" section below).

2. **Ask before generating HTML.** NEVER start writing an HTML page without asking the user first. They may just want a text answer, JSON output, or a quick summary. Ask: "Want me to make an interactive HTML page for this, or is a text summary enough?"

3. **Ask before choosing output format.** When the user's request could be answered as text, JSON, or a visual page, ask which they prefer. Don't assume.

## Overview

Full-featured CLI client for **every** Google Maps Platform REST API. Unlike the browser-based google-maps skill, this skill calls Google's APIs directly for fast, structured JSON responses. Covers 20+ APIs across maps, routes, places, environment, and geospatial services.

## Setup

### 1. Get a Google Maps API Key

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create or select a project
3. Enable the APIs you need (see API list below)
4. Go to **APIs & Services > Credentials** and create an API key
5. (Recommended) Restrict the key to only the APIs you need

### 2. Save the API Key

Add to your `.env` file in any of these locations (searched in order):

```bash
# Option 1: Project directory .env
echo 'GOOGLE_MAPS_API_KEY=your_key_here' >> .env

# Option 2: Home directory .env
echo 'GOOGLE_MAPS_API_KEY=your_key_here' >> ~/.env

# Option 3: Environment variable
export GOOGLE_MAPS_API_KEY=your_key_here
```

### 3. Enable Required APIs

In Google Cloud Console > APIs & Services > Library, enable the APIs you need:

| API Name | Console Name |
|----------|-------------|
| Geocoding | Geocoding API |
| Routes | Routes API |
| Places | Places API (New) |
| Elevation | Elevation API |
| Time Zone | Time Zone API |
| Air Quality | Air Quality API |
| Pollen | Pollen API |
| Solar | Solar API |
| Weather | Weather API |
| Address Validation | Address Validation API |
| Roads | Roads API |
| Street View | Street View Static API |
| Static Maps | Maps Static API |
| Geolocation | Geolocation API |
| Aerial View | Aerial View API |
| Route Optimization | Route Optimization API |
| Places Aggregate | Places Insights API |

## Script Location

```
~/.claude/skills/google-maps-api/scripts/gmaps.py
```

No external dependencies required - uses only Python standard library (`urllib`, `json`, `ssl`).

## Complete API Reference

### 1. Geocoding

**Forward geocode** - address to coordinates:
```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py geocode "1600 Amphitheatre Parkway, Mountain View, CA"
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py geocode "Tokyo Tower" --language ja --region jp
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py geocode "Paris" --components "country:FR"
```

**Reverse geocode** - coordinates to address:
```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py reverse-geocode 37.4224 -122.0856
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py reverse-geocode 48.8584 2.2945 --language fr
```

### 2. Routes & Directions

**Get directions** between two locations:
```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py directions "New York, NY" "Boston, MA"
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py directions "LAX" "SFO" --mode transit
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py directions "Seattle" "Portland" --alternatives --avoid-tolls
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py directions "A" "D" --waypoints "B" "C"
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py directions "Home" "Work" --mode bicycling --units imperial
```

**Distance matrix** - multiple origins/destinations:
```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py distance-matrix \
  --origins "New York" "Boston" \
  --destinations "Philadelphia" "Washington DC"
```

### 3. Places

**Text search** - find places by query:
```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py places-search "best pizza in Chicago"
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py places-search "pharmacy" --location "40.714,-74.006" --radius 1000
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py places-search "5-star hotels" --min-rating 4.5 --open-now
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py places-search "EV charging" --type "electric_vehicle_charging_station"
```

**Nearby search** - find places near coordinates:
```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py places-nearby 40.7128 -74.0060 --type restaurant --radius 800
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py places-nearby 34.0522 -118.2437 --type cafe --max-results 5
```

**Place details** - full info for a place:
```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py place-details ChIJN1t_tDeuEmsRUsoyG83frY4
```

**Autocomplete** - type-ahead suggestions:
```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py autocomplete "star" --location "37.7749,-122.4194"
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py autocomplete "central p" --types "park"
```

**Place photo** - get photo URL:
```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py place-photo "places/PLACE_ID/photos/PHOTO_REF" --max-width 800
```

### 4. Air Quality

**Current conditions**:
```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py air-quality 40.7128 -74.0060
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py air-quality 40.7128 -74.0060 --health --pollutants
```

**Historical data** (up to 30 days):
```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py air-quality-history 40.7128 -74.0060 --hours 48
```

**Forecast** (up to 96 hours):
```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py air-quality-forecast 40.7128 -74.0060
```

### 5. Pollen

**Pollen forecast** (up to 5 days, grass/weed/tree):
```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py pollen 40.7128 -74.0060
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py pollen 34.0522 -118.2437 --days 5
```
Returns: Universal Pollen Index (UPI) for 3 plant types and 15 species.

### 6. Solar

**Building solar potential**:
```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py solar 37.4219 -122.0841
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py solar 37.4219 -122.0841 --quality HIGH
```
Returns: roof area, sunlight hours, optimal panel layout, energy/cost estimates.

**Solar data layers** (DSM, flux, shade rasters):
```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py solar-layers 37.4219 -122.0841 --radius 100
```

### 7. Weather

**Current conditions**:
```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py weather 40.7128 -74.0060
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py weather 40.7128 -74.0060 --mode current
```

**Hourly forecast** (up to 240 hours):
```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py weather 40.7128 -74.0060 --mode hourly --hours 48
```

**Daily forecast** (up to 10 days):
```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py weather 40.7128 -74.0060 --mode daily --days 7
```

**Recent history** (up to 24 hours):
```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py weather 40.7128 -74.0060 --mode history --hours 12
```

### 8. Elevation

```bash
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py elevation 39.7392 -104.9903
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py elevation --locations "39.7392,-104.9903|36.4555,-116.8666"
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py elevat