These rules override all other instructions in this skill:
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).
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?"
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.
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
默认情况下，生成零密钥的 HTML 页面，使用 Google Maps 嵌入 iframe（output=embed）— 无需 API 密钥，无密钥暴露风险。仅当用户明确请求嵌入无法支持的高级交互功能（自定义标记、折线、聚类等）时，才使用 Maps JavaScript API（<script src="https://maps.googleapis.com/maps/api/js?key=...">）。
Returns: Universal Pollen Index (UPI) for 3 plant types and 15 species.
6. Solar
Building solar potential :
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
See "Street View in HTML" section below for details.
WARNING: Do NOT use the old shorthand format @{lat},{lng},3a,75y,{heading}h,90t — it is unreliable and often opens a zoomed-out world map instead of Street View. Always use the map_action=pano format above.
When the user asks location/geography/environment questions, use the appropriate command:
User Intent
Command
"Where is...?"
geocode
"What address is at...?"
reverse-geocode
"How do I get from A to B?"
directions
"How far is A from B?"
distance-matrix
"Find restaurants near..."
places-search or places-nearby
"What are the hours for...?"
place-details
"What's the air quality in...?"
air-quality
"Is the pollen bad today?"
pollen
"What's the weather in...?"
weather
"Is this address valid?"
validate-address
"What's the elevation of...?"
elevation
"What timezone is...?"
timezone
"Show me a map of..."
static-map
"Can I put solar panels on my roof?"
solar
"Optimize delivery routes"
route-optimize
"How many coffee shops in area?"
places-aggregate
Interactive HTML Output
IMPORTANT: Always ASK before generating HTML. Never start writing an HTML file without the user's explicit approval. After delivering results as text, ask:
"Want me to put this into an interactive HTML page you can open in the browser? Default theme is Warm Stone Sunrise (light, warm-toned, premium)."
If the user says yes (or explicitly asks for HTML/a page/a map), then generate it. If they don't respond or say no, just give them the text/JSON results.
By default, generate zero-key HTML pages using Google Maps embed iframes (output=embed) — no API key needed, no key exposure risk. Only use the Maps JavaScript API (<script src="https://maps.googleapis.com/maps/api/js?key=...">) when the user explicitly requests advanced interactive features (custom markers, polylines, clustering, etc.) that embeds can't support.
Zero-Key Embed Iframes (Default)
Use these iframe formats for maps — they require no API key and are free:
q — place name or address (URL-encoded, use + for spaces)
saddr / daddr — origin/destination for directions
z — zoom level (1-20, default ~12)
output=embed — required, makes it embeddable
ll — optional center coordinates lat,lng
WARNING: Do NOT use loading="lazy" on Google Maps embed iframes. Lazy loading prevents off-screen iframes from loading, causing maps below the fold to appear permanently blank. Always omit the loading attribute or use loading="eager".
Result Type
Default HTML Element
Street View
Direct Google Maps link (map_action=pano) — opens full interactive Street View in new tab. See "Street View in HTML" section.
Directions
Embed iframe with saddr/daddr + output=embed
Places search
Embed iframe with q=place+name + output=embed + info cards
Nearby search
Embed iframe centered on location + place cards
Static map
Embed iframe with q and z (zoomable, draggable)
Weather/Air Quality
Embed iframe for location + condition cards, icons, charts
Elevation
Elevation profile chart + embed iframe with path markers
Solar
Embed iframe for building location + solar potential stats
Trip plans
Combined multi-section page: embed iframe maps, place cards, weather widget
When generating HTML pages:
Use a single self-contained .html file (inline CSS/JS, no external dependencies)
Default to zero-key embed iframes (output=embed) for all maps — NO API key in HTML
NEVER usegoogle.maps.StreetViewPanorama or the Street View JS API in HTML pages. Always use direct Google Maps links with map_action=pano for Street View. This is a hard rule.
NEVER include a Google Maps JS API<script> tag unless the user explicitly requests advanced interactive features. The output=embed iframe approach handles most use cases without any API key.
Save to the current working directory with a descriptive name (e.g., marea-streetview.html, nyc-trip-plan.html)
Open automatically in the browser via open <file> (macOS) after creation
Street View in HTML — Zero Key Exposure
HARD RULE: Never embed Street View using the JavaScript API or Embed API in HTML pages. Both approaches expose the API key in client-side code. Instead, ALWAYS use a direct Google Maps link that opens the full interactive Street View experience in the user's browser — zero cost, zero API key exposure.
Direct link format (Google Maps URLs API — reliable):
viewpoint={lat},{lng} — coordinates of the Street View location
heading — compass heading in degrees (0=North, 90=East, 180=South, 270=West)
pitch — pitch angle (-90=down, 0=level, 90=up)
fov — field of view in degrees (10-100, default 90)
map_action=pano — required — explicitly triggers Street View panorama mode
WARNING: Do NOT use the old shorthand format @{lat},{lng},3a,75y,{heading}h,{pitch}t — it is unreliable and often fails to open Street View, instead showing a zoomed-out world map. Always use the map_action=pano format.
<a href="https://www.google.com/maps/@?api=1&map_action=pano&viewpoint=40.76545,-73.98115&heading=90&pitch=0&fov=90"
target="_blank" rel="noopener noreferrer"
style="display:inline-block; padding:12px 24px; background:#4f46e5; color:white;
border-radius:8px; text-decoration:none; font-weight:600;">
Open Street View →
</a>
For a JavaScript function (e.g., in trip plan pages with many locations):
function openStreetView(lat, lng, name) {
window.open(
`https://www.google.com/maps/@?api=1&map_action=pano&viewpoint=${lat},${lng}&heading=0&pitch=0&fov=90`,
'_blank'
);
}
For a card/preview with context:
<div class="streetview-card">
<div class="sv-preview">
<!-- Optional: use a static map or place photo as preview thumbnail -->
<div class="sv-overlay">
<span class="sv-icon">🔭</span>
<span>Interactive Street View</span>
</div>
</div>
<a href="https://www.google.com/maps/@?api=1&map_action=pano&viewpoint={lat},{lng}&heading=0&pitch=0&fov=90"
target="_blank" rel="noopener noreferrer" class="sv-button">
Open in Google Maps →
</a>
<p class="sv-note">Opens full 360° interactive Street View — pan, zoom, and walk around</p>
</div>
In consolidated trip plan pages , replace the former StreetViewPanorama section with a styled button/link card. The user clicks to open full Street View in a new tab — they get the complete interactive experience directly from Google Maps.
Why this approach:
Zero API key exposure — no key in HTML source at all
Zero cost — no API calls, no billing
Better experience — full Google Maps Street View with navigation, not a limited embed
Works for all deployment modes (personal, BYOK, platform key)
Consolidated One-Stop Pages
For multi-part requests (trip plans, location research, comparisons), always offer to generate a single consolidated HTML page that combines ALL collected data into one interactive dashboard. The user should be able to see everything in one stop rather than scrolling through terminal output.
A consolidated page should include every piece of data gathered during the conversation, for example a trip plan page might combine:
Interactive route map with driving directions polyline
Weather widget for the destination
Hotel/place cards with photos, ratings, hours
Restaurant recommendation with Street View link (opens full 360° view in Google Maps)
Timeline/itinerary section
Rental car & airport info
Design principles for consolidated pages:
Use a clean, modern dashboard layout with distinct sections
Each section should be visually rich: maps, cards, icons, badges — not just text
Include smooth scroll navigation (sticky frosted-glass nav with active link highlighting)
Scroll-reveal animations (IntersectionObserver fade-up on each section)
Fully responsive: desktop (>1024px), tablet (641-1024px), mobile (<=640px), small phone (<=380px)
Cards, buttons, travel chips, and stat grids stack to single column on mobile
Maps reduce height on mobile (280px), buttons go full-width
Default Theme: Warm Stone Sunrise
All HTML pages use this theme by default unless the user requests otherwise.
Hero:linear-gradient(160deg, #eef2ff, #faf5ff, #fff7ed) — indigo to lavender to peach
Maps: Default Google Maps style via embed iframes. When using Maps JS API (opt-in), apply light custom style — muted stone tones, soft blue water #c9d7e4, green parks #d4e9d4, white roads
Nav: Sticky frosted glass (rgba(255,255,255,0.85) + backdrop-filter: blur(20px)), active link underline animation
Interactions: Card lift on hover (translateY(-2px)), timeline dot fill + glow ring, step indent on hover, button lift with shadow increase
API Key Security & Production Architecture
The Problem
Any API key embedded in client-side HTML/JavaScript is visible to users via browser DevTools. This is fine for personal use but critical for production apps where you're serving multiple users.
Deployment Modes
This skill supports three deployment modes with different security profiles:
Mode 1: Personal / CLI Use (Single User)
The user's own API key in .env, used locally by gmaps.py. Key never leaves the machine.
User's Machine
├─ .env (GOOGLE_MAPS_API_KEY=...)
├─ gmaps.py → calls Google APIs directly
└─ HTML pages → zero-key embed iframes (preferred) or key embedded (acceptable)
Risk : Low — it's the user's own key on their own machine. Key restriction : None needed (or restrict to the APIs you use). Best practice : Even for personal use, prefer zero-key output=embed iframes for HTML pages. Only use Maps JS API when you need advanced features (custom markers, polylines, clustering).
Mode 2: Users Bring Their Own Key (Multi-User App)
Users configure their own Google API key. They control their own billing.
Your App
├─ User configures their own API key in app settings
├─ Key stored in user's profile (encrypted at rest)
├─ Used server-side for data queries
└─ Frontend key: user creates a separate domain-restricted key
Risk : Low-Medium — it's the user's key, their billing. Important : When generating shareable/exportable HTML pages, NEVER embed the user's key. Use static exports instead (see Shareable Export Mode below). Onboarding : Walk users through GCP Console setup and API enablement (see Setup section above).
Mode 3: Platform Key (Users Pay You) — CRITICAL
Users pay your platform. YOU provide the Google API key. Users must NEVER see it.
Architecture: Two-Key + Backend Proxy
┌─────────────────────────────────────────────────────┐
│ User's Browser │
│ │
│ HTML Page (served from app.yourdomain.com) │
│ ├─ Interactive Maps ← Frontend Key (domain-locked) │
│ ├─ Street View ← Frontend Key (domain-locked) │
│ └─ All data (weather, places, directions, etc.) │
│ ↑ pre-rendered from backend, NO key in browser │
│ │
└──────────────────┬────────────────────────────────────┘
│ /api/geocode, /api/directions, etc.
▼
┌──────────────────────────────────────────────────────┐
│ YOUR Backend Server │
│ │
│ Backend Key (env var, never sent to browser) │
│ ├─ Geocoding, Directions, Places, Weather, etc. │
│ ├─ Street View Static → returns image bytes │
│ └─ All data APIs proxied with your key server-side │
│ │
│ Key restricted by: Server IP address │
│ Even if leaked: won't work from other IPs │
└──────────────────┬────────────────────────────────────┘
│
▼
Google Maps Platform
Frontend Key (client-side, in the HTML):
Only enables: Maps JavaScript API (for interactive map rendering)
Even if someone copies it, it only works from your domain
Cannot call data APIs (geocoding, places, etc.) — those are disabled on this key
Backend Key (server-side, hidden):
Enables: ALL data APIs (geocoding, directions, places, weather, pollen, solar, etc.)
Restricted by: Server IP address
Never sent to the browser — lives in server environment variables only
Even if leaked, only works from your server's IP
How HTML pages work in this mode :
// UNSAFE — key exposed, data fetched client-side:
const service = new google.maps.DirectionsService();
service.route({ origin: 'JFK', destination: 'The Plaza' });
// SAFE — data pre-fetched by backend, only map rendering in browser:
const routeData = /* injected by server from backend API call */;
const path = google.maps.geometry.encoding.decodePath(routeData.polyline);
new google.maps.Polyline({ path: path, map: map });
Setting Up Two Keys in GCP Console
Step 1: Create the Frontend Key
Go to APIs & Services > Credentials in GCP Console
Click Create Credentials > API Key
Click the key to edit it
Under Application restrictions : select HTTP referrers
Add your domain: https://app.yourdomain.com/*
Under API restrictions : select Restrict key
Enable ONLY: Maps JavaScript API
Save
Step 2: Create the Backend Key
Click Create Credentials > API Key again
Click the key to edit it
Under Application restrictions : select IP addresses
Add your server IP(s)
Under API restrictions : select Restrict key
Enable: Geocoding, Routes, Places (New), Weather, Air Quality, Pollen, Solar, Elevation, Time Zone, Address Validation, Roads, Street View Static, Geolocation, Aerial View, Route Optimization
Save
Step 3: Configure Your App
# Backend server environment
GOOGLE_MAPS_BACKEND_KEY=AIzaSy...xxx # Server-side only, IP-restricted
GOOGLE_MAPS_FRONTEND_KEY=AIzaSy...yyy # Injected into HTML, domain-restricted
Shareable Export Mode
When users want to download or share HTML pages (email, Slack, etc.), generate a static export with NO API keys:
Element
In-App (interactive)
Shareable Export
Maps
Maps JavaScript API (frontend key)
Maps Embed API <iframe> (free, no key abuse risk)
Street View
Direct Google Maps link (no key needed)
Direct Google Maps link (no key needed)
Route lines
DirectionsRenderer (frontend key)
Static map image with path overlay (base64)
Data (weather, places)
Pre-rendered from backend
Same pre-rendered HTML — no API calls needed
API key exposure
Frontend key, domain-locked
No key at all
To generate embed URLs (free, unlimited):
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py embed-url --mode place --query "Marea Restaurant NYC"
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py embed-url --mode directions --origin "JFK" --destination "The Plaza Hotel NYC"
python3 ~/.claude/skills/google-maps-api/scripts/gmaps.py embed-url --mode streetview --lat 40.76545 --lng -73.98115
Security Summary
Deployment
Data APIs
Map Rendering
Key Exposure
Shareable
Personal CLI
User's key locally
Zero-key embed iframes (default)
None
Yes (no key)
Personal CLI (advanced)
User's key locally
Maps JS API (opt-in for polylines, clustering, etc.)
User's own risk
No (key leaks)
BYOK (user's key)
User's key on server
User creates frontend key
User's own risk
Static export only
Platform key (you pay)
Backend key (IP-locked)
Frontend key (domain-locked)
Safe
Static export only
Rate Limiting & Abuse Prevention (Platform Mode)
When serving multiple users with your key, also implement:
Per-user rate limits : Cap API calls per user per hour/day
Authentication : Only authenticated, paying users can trigger API calls
Usage tracking : Log which user triggered which API call for billing
Quota alerts : Set up GCP billing alerts to catch unexpected spikes
Budget caps : Set maximum daily spend in GCP Console
Error Handling & Guided API Setup
CRITICAL: When ANY command fails, you MUST tell the user immediately. Do NOT silently fall back to web search or other workarounds. The user needs to know what's broken so they can decide how to fix it.
When a command fails, detect the error type and respond accordingly:
403 Forbidden / API not enabled : STOP. Tell the user. Offer Playwright walkthrough (see below)
REQUEST_DENIED : STOP. Tell the user. Offer Playwright walkthrough (see below)
400 Bad Request : Invalid parameters — check the API docs
429 Rate Limited : Too many requests — add a short delay
ZERO_RESULTS : No results found — try broader search
INVALID_REQUEST : Missing required parameters
Key not found : Ensure GOOGLE_MAPS_API_KEY is set in .env or environment
RefererNotAllowedMapError : Frontend key's HTTP referrer restriction doesn't match the current domain
Guided API Enablement (Playwright Walkthrough)
This is the PRIMARY response when an API is not enabled. Do not skip this. Do not silently work around it.
When a user's API call fails with 403 , REQUEST_DENIED , or an "API not enabled" error:
Tell the user what happened in plain language:
"It looks like the [API Name] isn't enabled on your Google Cloud project yet. No worries — I can walk you through enabling it right now in your browser. Want me to go ahead?"
If the user says yes , use Playwright MCP to automate the enablement:
Step 1: Navigate to the specific API's enablement page:
https://console.cloud.google.com/apis/library/[API_ENDPOINT]
Step 2: If a project selector appears, let the user pick their project
(or auto-select if there's only one)
Step 3: Click the "Enable" button
Step 4: Wait for the confirmation (loading spinner → "API enabled" or
the button changes to "Manage")
Step 5: Confirm to the user: "Done! [API Name] is now enabled.
Let me retry your request."
Step 6: Retry the original command automatically
API endpoint URLs for Playwright navigation (use these exact paths):
API
GCP Library URL path
Geocoding
geocoding-backend.googleapis.com
Routes
routes-backend.googleapis.com
Places (New)
places-backend.googleapis.com
Elevation
elevation-backend.googleapis.com
Time Zone
timezone-backend.googleapis.com
Air Quality
airquality.googleapis.com
Pollen
pollen.googleapis.com
Solar
solar.googleapis.com
Weather
weather.googleapis.com
Address Validation
addressvalidation.googleapis.com
Roads
roads.googleapis.com
Street View Static
street-view-image-backend.googleapis.com
Maps Static
static-maps-backend.googleapis.com
Maps JavaScript
maps-backend.googleapis.com
Maps Embed
maps-embed-backend.googleapis.com
Geolocation
geolocation.googleapis.com
Aerial View
aerialview.googleapis.com
Route Optimization
routeoptimization.googleapis.com
Full URL pattern: https://console.cloud.google.com/apis/library/[path_from_table]
If the user says no (prefers to do it manually), give them the direct URL:
Batch enablement : If the user is setting up for the first time and multiple APIs need enabling, offer to enable them all in one go:
"I can enable all the commonly used APIs for you in one pass — Geocoding, Routes, Places, Weather, Elevation, Time Zone, and Maps JavaScript. Want me to set them all up?"
Then loop through each API page via Playwright, clicking Enable on each.
Important notes for Playwright walkthrough :
The user must already be logged into Google Cloud Console in their browser
