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.