Imported from amoai-tech/mdeai (.claude/skills/mde-maps/SKILL.md). Install upstream with npx skills add amoai-tech/mdeai --skill mde-maps. Copyright stays with the author.

mde-maps — Google Maps Platform

When NOT to use

• Generic GIS / spatial math with no Google Maps Platform APIs
• Mapbox-only or Leaflet/OpenStreetMap-only stacks (no GMP)
• Unrelated mapping tutorials or homework off the mdeai repo
• Non-mdeAI products—still read-only here; prefer not to expand scope in this skill

Load order (keep context small)

1. This SKILL.md — Quick routing table + Consolidated sibling note.
2. GMP doc questions — MCP Maps Code Assist first (§ Code Assist workflow below); then one references/*.md for the task.
3. One references/*.md file for implementation (do not bulk-load google-offline/ unless grepping mirrors).
4. references/all-apis.md only when running or editing gmaps.py batch CLI work.

Cursor rule: .cursor/rules/mdeai-google-maps.mdc · MCP setup: .cursor/MCP-GOOGLE-MAPS.md · Project: .mcp.json key google-maps-code-assist

Maps Code Assist MCP workflow

Official: developers.google.com/maps/ai/code-assist · Source: github/maps/platform-ai/ (GEMINI.md)

Use hosted HTTP only — https://mapscodeassist.googleapis.com/mcp. The npm package @googlemaps/code-assist-mcp is deprecated 2026-07-01 per platform-ai README.

Not for production runtime — no live search_places. For live geo tools use Grounding Lite (mapstools.googleapis.com) — references/maps-grounding.md § Mode 2.

Full setup: references/maps-ai-code-assist.md

Canonical github/maps/ clones (read-only)

Index: github/maps/README.md · Scores: index.md §4

Never copy vendor src/ into mdeapp/ — read patterns, install npm packages.

Quick routing

Consolidated sibling skills (read once)

These top-level skills are thin stubs (or archived names) that point here — one maintenance surface for mdeai:

Offline Google documentation (local mirror)

Google Maps / Grounding / MCP pages exported as Markdown live under references/google-offline/ — each file has YAML frontmatter (doc_type: google_offline_mirror). Use for local search and air-gapped reading; they are not authoritative.

• Index + conflict rules: references/official-docs-mirror.md
• Do not treat mirrors as SoT for billing, tool schemas, or launch gates — cross-check live developers.google.com and grounding-lite-mcp-sample-app when implementing GROUNDING-001 / 057 / 065.

mdeAI environment

VITE_GOOGLE_MAPS_API_KEY    — Frontend (browser) — Maps JS API, AdvancedMarkerElement
GOOGLE_PLACES_API_KEY       — Server-side only — Places API (New), enrichment scripts
GOOGLE_MAPS_API_KEY         — Edge functions — Directions, Routes
GOOGLE_ROUTES_API_KEY       — Edge functions — Routes API

Medellín anchor: { latitude: 6.2442, longitude: -75.5812 } — default locationBias center and Maps grounding latLng.

Never put GOOGLE_PLACES_API_KEY in a VITE_ var — visible in browser DevTools.

Interactive MCP tools

Use these when answering location questions in a Claude session (not for mdeAI production code). Tools call Google Maps APIs live.

Tools available

search_places(query, location?, radius?, type?, open_now?, language?)
  query     — text query ("restaurants in Laureles")
  location  — "lat,lng" center (optional)
  radius    — meters, max 50000 (optional)
  type      — place type filter ("restaurant", "tourist_attraction", "hotel")
  open_now  — boolean, default false
  language  — language code, default "en"

search_nearby_places(location, radius, keyword?, type?, rank_by?, open_now?, language?)
  location  — "lat,lng" (required)
  radius    — meters (required, max 50000)
  rank_by   — "prominence" (default) or "distance"

get_place_details(place_id, language?, reviews_sort?)
  place_id  — from search results
  reviews_sort — "most_relevant" (default) or "newest"

get_directions(origin, destination, mode?, alternatives?, avoid?, language?)
  mode      — "driving" (default), "walking", "bicycling", "transit"
  avoid     — "tolls", "highways", or "ferries"

geocode_address(address, language?, region?)
  region    — country code for regional bias

reverse_geocode(latlng, language?)
  latlng    — "lat,lng"

show_on_map(map_type, markers?, directions?, center?, zoom?)
  map_type  — "markers", "directions", or "area"
  markers   — array of {lat, lng} objects

Response pattern — Text → Map → Text

Always follow this sequence. Never call show_on_map in parallel with other calls.

1. Text — introduce what you'll show ("Here are top restaurants near Poblado:")
2. Map — call show_on_map to render results
3. Text — explain results in plain language (names, ratings, notes)

Multiple categories: sequential maps — events then restaurants, not parallel.

Never echo raw map_data JSON (coordinates, markers, zoom) in your text response. The map renders visually; describe places by name and quality only.

Intent → tool mapping

Preserve place_id from search results for use in get_place_details.

Places API (New) — field masks for mdeAI

Every request uses X-Goog-FieldMask header. Only request fields you need — billing is field-mask driven.

Enrichment mask (PLACES-005-010)

places.id,places.displayName,places.googleMapsLinks,places.location,places.generativeSummary

generativeSummary constraints

• Coverage: English only; US and India only currently
• Attribution required: Display disclosureText ("Summarized with Gemini") wherever ai_summary appears — ToS requirement
• Cache in DB: Fetch once at seeding time. Never call per chat turn.

googleMapsLinks — currently free

googleMapsLinks is in preview and free as of 2026-05. Use placeUri (not lat/lng-constructed URLs) — it's stable and canonical.

Node.js client — enrichment script pattern

import { PlacesClient } from '@googlemaps/places';

const client = new PlacesClient({ apiKey: process.env.GOOGLE_PLACES_API_KEY });

const [response] = await client.searchText(
  {
    textQuery: `${venueName} ${neighborhood} Medellín Colombia`,
    locationBias: {
      circle: { center: { latitude: 6.2442, longitude: -75.5812 }, radius: 30000 },
    },
  },
  { otherArgs: { headers: { 'X-Goog-FieldMask': 'places.id,places.displayName,places.googleMapsLinks,places.location,places.generativeSummary' } } },
);

Gemini Maps grounding — summary

Full pattern: references/maps-grounding.md

Kill switch: MAPS_GROUNDING_DAILY_LIMIT=0 → fall back to Supabase immediately.

Sequential calls for structured output: grounded call (no responseMimeType) → structured output call (no grounding). Maps + custom function declarations CAN be combined in one call (March 2026 update).

Maps JavaScript API — ChatMap.tsx summary

Full pattern: references/maps-js-api.md

• Loader: @googlemaps/js-api-loader with libraries: ['marker']
• mapId required for AdvancedMarkerElement
• data-testid="map-pin" on every pin content element (MASTRA-045 smoke spec)
• Per-category pin merge: setPins(prev => [...prev.filter(p => p.category !== cat), ...newPins])
• Frontend key restricted to HTTP referrers + Maps JS API only

Session tokens — autocomplete billing

Use UUID v4 session tokens to group autocomplete keystrokes + final Place Details into one billing event:

import { v4 as uuidv4 } from 'uuid';
const sessionToken = uuidv4(); // new UUID per search session
// Pass as sessionToken on each Autocomplete call
// Generate fresh UUID after user selects a place

GCP key setup — quick reference

Full 2-key security architecture → references/security-and-optimization.md

Enable "Places API (New)" in GCP Console — NOT "Places API" (legacy). Different billing, different endpoints, different field names.

Event discovery — Maps / Places / ADK (plan 10 §11)

Plans: 10-event-discover-plan.md · Routing: event-discovery-skill-routing.md

Golden rule: Places enriches DB once; grounding answers live geo questions — never invent event listings from Maps.

MASTRA task references

Canonical numbered specs live under tasks/mastra/maps/tasks/ (runtime/, grounding/, places/, …). Index: tasks/mastra/maps/tasks/index-maps-tasks.md and places/README.md.

Common gotchas