Google Maps - Geospatial Query Capabilities
Overview
Gives an AI Agent the ability to reason about physical space — understand locations, distances, routes, and elevation, and naturally weave that information into conversation.
Without this Skill, the agent can only guess or refuse when asked "how do I get from Taipei 101 to the National Palace Museum?". With it, the agent returns exact coordinates, step-by-step routes, and travel times.
Core Principles
| Principle |
Explanation |
| Chain over single-shot |
Most geo questions require 2-5 tool calls chained together. See Scenario Recipes in references/tools-api.md for the full patterns. |
| Match recipe to intent |
Map the user's question to a recipe (Trip Planning, Local Discovery, Route Comparison, Neighborhood Analysis, Multi-Stop, Place Comparison, Along the Route) before calling any tool. |
| Precise input saves trouble |
Use coordinates over address strings when available. Use place_id over name search. More precise input = more reliable output. |
| Output is structured |
Every tool returns JSON. Use it directly for downstream computation or comparison — no extra parsing needed. |
| Present as tables |
Users prefer comparison tables and scorecards over raw JSON. Format results for readability. |
Tool Map
17 tools in five categories — pick by scenario:
Place Discovery
| Tool |
When to use |
Example |
maps_geocode |
Have an address/landmark, need coordinates |
"What are the coordinates of Tokyo Tower?" |
maps_reverse_geocode |
Have coordinates, need an address |
"What's at 35.65, 139.74?" |
maps_search_nearby |
Know a location, find nearby places by type |
"Coffee shops near my hotel" |
maps_search_places |
Natural language place search |
"Best ramen in Tokyo" |
maps_place_details |
Have a place_id, need full info (+ optional photo URLs via maxPhotos) |
"Opening hours and reviews for this restaurant?" |
maps_batch_geocode |
Geocode multiple addresses at once (max 50) |
"Get coordinates for all these offices" |
Routing & Distance
| Tool |
When to use |
Example |
maps_directions |
How to get from A to B, including drive-only avoid-tolls/highways controls |
"Route from Taipei Main Station to airport avoiding tolls" |
maps_distance_matrix |
Compare distances across multiple points, including drive-only avoid-tolls/highways controls |
"Which of these 3 hotels is closest to airport without highways?" |
maps_search_along_route |
Find places along a route (meals, stops) ranked by detour time |
"Restaurants between Fushimi Inari and Kiyomizu-dera" |
Environment
| Tool |
When to use |
Example |
maps_elevation |
Query altitude |
"Elevation profile along this hiking trail" |
maps_timezone |
Need local time at a destination |
"What time is it in Tokyo?" |
maps_weather |
Weather at a location (current or forecast) |
"What's the weather in Paris?" |
maps_air_quality |
AQI, pollutants, health recommendations |
"Is the air safe for jogging?" |
Visualization
| Tool |
When to use |
Example |
maps_static_map |
Show locations/routes on a map image |
"Show me these places on a map" |
Composite (one-call shortcuts)
| Tool |
When to use |
Example |
maps_explore_area |
Overview of a neighborhood |
"What's around Tokyo Tower?" |
maps_plan_route |
Multi-stop optimized itinerary (Routes API waypoint optimization, up to 25 stops) with drive-only avoid-tolls/highways controls |
"Visit these 5 places efficiently without tolls" |
maps_compare_places |
Side-by-side comparison |
"Which ramen shop near Shibuya?" |
maps_local_rank_tracker |
Local SEO grid rank tracking |
"How does this dentist rank across the area?" |
Known API Limitations
| Tool |
Limitation |
Workaround |
maps_weather |
Unsupported regions: Japan, China, South Korea, Cuba, Iran, North Korea, Syria |
Use web search for weather in these regions |
maps_distance_matrix |
Transit mode may return null in some regions |
Fall back to driving or walking mode, or use maps_directions for transit |
maps_plan_route |
Transit mode does not support waypoint optimization |
Set optimize: false for transit mode |
maps_air_quality |
Works globally including Japan (unlike weather) |
— |
Invocation
npx @cablate/mcp-google-map exec <tool> '<json_params>' [-k API_KEY]
- API Key:
-k flag or GOOGLE_MAPS_API_KEY environment variable
- Output: JSON to stdout, errors to stderr
- Stateless: each call is independent
- Tool names: CLI accepts both
maps_geocode and geocode short forms
- Tool filtering: Set
GOOGLE_MAPS_ENABLED_TOOLS env var to a comma-separated list of tool names to limit registered tools (reduces MCP client context usage). Omit or set to * for all tools.
When to Update This Skill
| Trigger |
What to update |
| New tool added to the package |
Tool Map table + references/tools-api.md |
| Tool parameters changed |
references/tools-api.md |
| New chaining pattern discovered in practice |
references/tools-api.md chaining section |
Reference
| File |
Content |
When to read |
references/tools-api.md |
Full parameter specs, response formats, 7 scenario recipes, and decision guide |
When you need exact parameters, response shapes, or multi-tool workflow patterns |
references/travel-planning.md |
Travel planning methodology — 6-layer model, Search Along Route, anti-patterns |
When planning multi-day trips — read before Recipe 1 |
references/local-seo.md |
Local SEO / Google Business Profile ranking analysis — competitor audit, keyword landscape, gap analysis |
When analyzing business rankings, comparing competitors, or scouting locations |
For project development knowledge (architecture, API guide, GIS domain, design decisions), see skills/project-docs/SKILL.md.
1---2name: google-maps3description: Geospatial query capabilities — geocoding, nearby search, routing, place details, elevation. Trigger when the user mentions locations, addresses, coordinates, navigation, "what's nearby", "how to get there", distance/duration, or any question that inherently involves geographic information — even if they don't explicitly say "map". Update when new tools are added or tool parameters change.4license: MIT5---67# Google Maps - Geospatial Query Capabilities89## Overview1011Gives an AI Agent the ability to reason about physical space — understand locations, distances, routes, and elevation, and naturally weave that information into conversation.1213Without this Skill, the agent can only guess or refuse when asked "how do I get from Taipei 101 to the National Palace Museum?". With it, the agent returns exact coordinates, step-by-step routes, and travel times.1415---1617## Core Principles1819| Principle | Explanation |20|-----------|-------------|21| Chain over single-shot | Most geo questions require 2-5 tool calls chained together. See Scenario Recipes in references/tools-api.md for the full patterns. |22| Match recipe to intent | Map the user's question to a recipe (Trip Planning, Local Discovery, Route Comparison, Neighborhood Analysis, Multi-Stop, Place Comparison, Along the Route) before calling any tool. |23| Precise input saves trouble | Use coordinates over address strings when available. Use place_id over name search. More precise input = more reliable output. |24| Output is structured | Every tool returns JSON. Use it directly for downstream computation or comparison — no extra parsing needed. |25| Present as tables | Users prefer comparison tables and scorecards over raw JSON. Format results for readability. |2627---2829## Tool Map303117 tools in five categories — pick by scenario:3233### Place Discovery34| Tool | When to use | Example |35|------|-------------|---------|36| `maps_geocode` | Have an address/landmark, need coordinates | "What are the coordinates of Tokyo Tower?" |37| `maps_reverse_geocode` | Have coordinates, need an address | "What's at 35.65, 139.74?" |38| `maps_search_nearby` | Know a location, find nearby places by type | "Coffee shops near my hotel" |39| `maps_search_places` | Natural language place search | "Best ramen in Tokyo" |40| `maps_place_details` | Have a place_id, need full info (+ optional photo URLs via `maxPhotos`) | "Opening hours and reviews for this restaurant?" |41| `maps_batch_geocode` | Geocode multiple addresses at once (max 50) | "Get coordinates for all these offices" |4243### Routing & Distance44| Tool | When to use | Example |45|------|-------------|---------|46| `maps_directions` | How to get from A to B, including drive-only avoid-tolls/highways controls | "Route from Taipei Main Station to airport avoiding tolls" |47| `maps_distance_matrix` | Compare distances across multiple points, including drive-only avoid-tolls/highways controls | "Which of these 3 hotels is closest to airport without highways?" |48| `maps_search_along_route` | Find places along a route (meals, stops) ranked by detour time | "Restaurants between Fushimi Inari and Kiyomizu-dera" |4950### Environment51| Tool | When to use | Example |52|------|-------------|---------|53| `maps_elevation` | Query altitude | "Elevation profile along this hiking trail" |54| `maps_timezone` | Need local time at a destination | "What time is it in Tokyo?" |55| `maps_weather` | Weather at a location (current or forecast) | "What's the weather in Paris?" |56| `maps_air_quality` | AQI, pollutants, health recommendations | "Is the air safe for jogging?" |5758### Visualization59| Tool | When to use | Example |60|------|-------------|---------|61| `maps_static_map` | Show locations/routes on a map image | "Show me these places on a map" |6263### Composite (one-call shortcuts)64| Tool | When to use | Example |65|------|-------------|---------|66| `maps_explore_area` | Overview of a neighborhood | "What's around Tokyo Tower?" |67| `maps_plan_route` | Multi-stop optimized itinerary (Routes API waypoint optimization, up to 25 stops) with drive-only avoid-tolls/highways controls | "Visit these 5 places efficiently without tolls" |68| `maps_compare_places` | Side-by-side comparison | "Which ramen shop near Shibuya?" |69| `maps_local_rank_tracker` | Local SEO grid rank tracking | "How does this dentist rank across the area?" |7071---7273## Known API Limitations7475| Tool | Limitation | Workaround |76|------|-----------|------------|77| `maps_weather` | Unsupported regions: Japan, China, South Korea, Cuba, Iran, North Korea, Syria | Use web search for weather in these regions |78| `maps_distance_matrix` | Transit mode may return null in some regions | Fall back to `driving` or `walking` mode, or use `maps_directions` for transit |79| `maps_plan_route` | Transit mode does not support waypoint optimization | Set `optimize: false` for transit mode |80| `maps_air_quality` | Works globally including Japan (unlike weather) | — |8182---8384## Invocation8586```bash87npx @cablate/mcp-google-map exec <tool> '<json_params>' [-k API_KEY]88```8990- **API Key**: `-k` flag or `GOOGLE_MAPS_API_KEY` environment variable91- **Output**: JSON to stdout, errors to stderr92- **Stateless**: each call is independent93- **Tool names**: CLI accepts both `maps_geocode` and `geocode` short forms94- **Tool filtering**: Set `GOOGLE_MAPS_ENABLED_TOOLS` env var to a comma-separated list of tool names to limit registered tools (reduces MCP client context usage). Omit or set to `*` for all tools.9596---9798## When to Update This Skill99100| Trigger | What to update |101|---------|----------------|102| New tool added to the package | Tool Map table + references/tools-api.md |103| Tool parameters changed | references/tools-api.md |104| New chaining pattern discovered in practice | references/tools-api.md chaining section |105106---107108## Reference109110| File | Content | When to read |111|------|---------|--------------|112| `references/tools-api.md` | Full parameter specs, response formats, 7 scenario recipes, and decision guide | When you need exact parameters, response shapes, or multi-tool workflow patterns |113| `references/travel-planning.md` | Travel planning methodology — 6-layer model, Search Along Route, anti-patterns | When planning multi-day trips — **read before Recipe 1** |114| `references/local-seo.md` | Local SEO / Google Business Profile ranking analysis — competitor audit, keyword landscape, gap analysis | When analyzing business rankings, comparing competitors, or scouting locations |115116> For **project development** knowledge (architecture, API guide, GIS domain, design decisions), see `skills/project-docs/SKILL.md`.
cablate