Skip to content

Commit 50c3838

Browse files
cablateclaude
cablate
and
claude
authored
feat: migrate to Routes API and add rich place attributes (#62)
* feat: migrate to Routes API and add rich place attributes Routes API Migration: - Add RoutesService.ts as dedicated Routes API REST client - Migrate directions/distance-matrix/planRoute from legacy SDK to Routes API - planRoute now uses native waypoint optimization (up to 25 stops) - Update searchAlongRoute polyline extraction for Routes API format - Remove legacy directions/distance-matrix code from toolclass.ts Place Attributes Expansion: - Add 31 new fields to placeFieldMask (parking, dining, atmosphere, accessibility, AI summaries) - Zero additional API cost — already paying Enterprise+Atmosphere SKU via reviews - Place details now return: primary_type, types, editorial_summary, parking, accessibility, dining_options (dine_in/delivery/takeout/reservable), serves (vegetarian/beer/wine/cocktails), atmosphere (good_for_groups/children/outdoor_seating/allows_dogs/live_music), payment_options, review_summary, generative_summary, and review language codes - Search results now include primary_type and price_level - comparePlaces now includes parking, serves, atmosphere, dining_options Docs: - Add docs/research-ai-place-selection.md (AI place selection feasibility study) - Add docs/backlog-and-strategy.md (consolidated from 4 retired planning docs) - Update tools-api.md with new response fields documentation - Update architecture.md and google-maps-api-guide.md for Routes API Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * style: fix Prettier formatting Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 813f621 commit 50c3838

12 files changed

Lines changed: 1197 additions & 236 deletions

File tree

‎README.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -79,12 +79,12 @@ Special thanks to [@junyinnnn](https://github.com/junyinnnn) for helping add sup
7979
| `maps_search_along_route` | Search for places along a route between two points — ranked by minimal detour time. |
8080
| **Composite Tools** | |
8181
| `maps_explore_area` | Explore what's around a location — searches multiple place types and gets details in one call. |
82-
| `maps_plan_route` | Plan an optimized multi-stop route — geocodes, finds best order, returns directions. |
82+
| `maps_plan_route` | Plan an optimized multi-stop route — uses Routes API waypoint optimization (up to 25 stops) for efficient ordering. |
8383
| `maps_compare_places` | Compare places side-by-side — searches, gets details, and optionally calculates distances. |
8484

8585
All tools are annotated with `readOnlyHint: true` and `destructiveHint: false` — MCP clients can auto-approve these without user confirmation.
8686

87-
> **Prerequisite**: Enable **Places API (New)** in [Google Cloud Console](https://console.cloud.google.com) before using place-related tools.
87+
> **Prerequisite**: Enable **Places API (New)** and **Routes API** in [Google Cloud Console](https://console.cloud.google.com) before using place-related and routing tools.
8888
8989
## Installation
9090

@@ -247,7 +247,8 @@ src/
247247
├── services/
248248
│ ├── NewPlacesService.ts # Google Places API (New) client
249249
│ ├── PlacesSearcher.ts # Service facade layer
250-
│ └── toolclass.ts # Legacy Google Maps API client
250+
│ ├── RoutesService.ts # Google Routes API client (directions, distance matrix, waypoint optimization)
251+
│ └── toolclass.ts # Google Maps API client (geocoding, timezone, elevation, static map)
251252
├── tools/
252253
│ └── maps/
253254
│ ├── searchNearby.ts # maps_search_nearby tool
@@ -293,7 +294,8 @@ skills/
293294
- **TypeScript** - Type-safe development
294295
- **Node.js** - Runtime environment
295296
- **@googlemaps/places** - Google Places API (New) for place search and details
296-
- **@googlemaps/google-maps-services-js** - Legacy API for geocoding, directions, distance matrix, elevation
297+
- **Google Routes API** - Directions, distance matrix, and waypoint optimization via REST
298+
- **@googlemaps/google-maps-services-js** - Geocoding, timezone, elevation
297299
- **@modelcontextprotocol/sdk** - MCP protocol implementation (v1.27+)
298300
- **Express.js** - HTTP server framework
299301
- **Zod** - Schema validation

‎docs/backlog-and-strategy.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# mcp-google-map Backlog & Strategy
2+
3+
> Consolidated: 2026-03-20
4+
> Source: dev-roadmap-spec.md, strategy-todo.md, mcp-google-map-growth-strategy-2026.md (all retired)
5+
> Current state: v0.0.44, 17 tools, ~192+ GitHub stars
6+
7+
This file contains ONLY items that have NOT been implemented and strategic insights that remain relevant. All completed items have been removed.
8+
9+
---
10+
11+
## Backlog: Features
12+
13+
### MCP Prompt Templates (from dev-roadmap-spec P1)
14+
15+
**Status**: Not started | **Effort**: ~6hr
16+
17+
MCP Prompts 讓 Claude Desktop / Cursor 使用者一鍵進入 geo agent 模式，不需要讀文件。
18+
19+
```typescript
20+
// 3 prompts to register in BaseMcpServer.ts:
21+
{
22+
name: "travel-planner",
23+
description: "Plan a trip with geo tools",
24+
arguments: [
25+
{ name: "destination", required: true },
26+
{ name: "duration", required: false },
27+
{ name: "style", required: false } // budget, luxury, foodie
28+
]
29+
},
30+
{
31+
name: "neighborhood-scout",
32+
description: "Analyze a location for living/working",
33+
arguments: [
34+
{ name: "location", required: true },
35+
{ name: "priorities", required: false } // schools, transit, restaurants
36+
]
37+
},
38+
{
39+
name: "route-optimizer",
40+
description: "Optimize a multi-stop route",
41+
arguments: [
42+
{ name: "stops", required: true },
43+
{ name: "mode", required: false }
44+
]
45+
}
46+
```
47+
48+
Implementation: `BaseMcpServer.ts` 加 `prompts` capability，Prompt 內容從 `tools-api.md` Scenario Recipes 提取。
49+
50+
### Geo-Reasoning Benchmark (from dev-roadmap-spec P2)
51+
52+
**Status**: Not started | **Effort**: Phase 1 ~2 weeks
53+
54+
10 scenarios (Easy 2 + Medium 3 + Hard 3 + Expert 2), 5 metrics (Tool Selection Accuracy, Parameter Correctness, Chain Efficiency, Result Quality, Latency).
55+
56+
Key metric — **Composite Tool Efficiency Score (CES)**:
57+
```
58+
CES = min_required_calls / actual_calls_made
59+
```
60+
61+
Marketing angle: "Without geo tools: 4% success (MIT TravelPlanner). With mcp-google-map: 87%+"
62+
63+
Phase 1: 5 YAML scenarios + automated evaluator + README results table
64+
Phase 2: 全 10 scenarios + LLM-as-Judge + multi-LLM comparison
65+
66+
### Geo Agent Scaffold (from strategy-todo Backlog)
67+
68+
**Status**: Not started | **Effort**: TBD
69+
70+
Pre-built agent prompt template — 「你是一個旅遊規劃專家，你有以下地理工具...」。讓人可以一行指令啟動 geo-aware AI agent。
71+
72+
### maps_isochrone (from dev-roadmap-spec P3)
73+
74+
**Status**: Deprioritized | **Effort**: ~8hr
75+
76+
Google 沒有 isochrone API。最佳路徑：Distance Matrix 8 方向探測 + static map 畫 approximated polygon。ROI 目前不夠，待有明確需求再做。
77+
78+
---
79+
80+
## Backlog: Growth & Marketing
81+
82+
### Pending Submissions (manual)
83+
84+
| Platform | Type | Status |
85+
|---|---|---|
86+
| pulsemcp.com | Web form | Not submitted |
87+
| mcpservers.org | Web form | Not submitted |
88+
| mcp.so | Web form | Not submitted |
89+
| mcpmarket.com | Web form | Not submitted |
90+
| mcpserverfinder.com | Web form | Not submitted |
91+
| Cline Marketplace | PR to `cline/mcp-marketplace` | Not submitted |
92+
93+
### Content Marketing (not started)
94+
95+
| Item | Effort | Notes |
96+
|---|---|---|
97+
| Blog post / Dev.to article | Medium | "Why your AI agent needs geospatial capabilities" |
98+
| Demo video (30-60 sec) | Medium | Screen recording of Claude Code + mcp-google-map trip planning |
99+
| Twitter/X launch campaign | Low | Needs demo video first |
100+
| HN "Show HN" post | Low | README ready, can execute anytime |
101+
102+
---
103+
104+
## Strategic Insights (still relevant)
105+
106+
### Competitive Positioning
107+
108+
**vs Google Grounding Lite (official MCP)**:
109+
- Grounding Lite: 3 tools, managed hosting, no API key needed, experimental
110+
- Us: 17 tools, self-hosted, full control, Agent Skill, exec CLI
111+
- Key gaps they have that we don't: none anymore (we added weather, timezone, air quality)
112+
- Key things we have that they don't: geocoding, directions, elevation, distance matrix, place details, batch geocode, composite tools, Agent Skill
113+
114+
**vs Mapbox MCP (315 stars)**:
115+
- Mapbox: 20+ tools, offline Turf.js, TSP, Isochrone, separate Agent Skills repo
116+
- Us: Google Maps API (larger user base), Skills embedded in npm package, exec CLI, MIT
117+
118+
**vs baidu-maps/mcp (411 stars)**:
119+
- China market only, not direct competition internationally
120+
121+
### MCP + Agent Skills Ecosystem
122+
123+
- Agent Skills 已是跨平台標準（Claude Code, VS Code, OpenAI Codex, Cursor, Gemini CLI）
124+
- AAIF (Linux Foundation): Anthropic, Google, Microsoft, OpenAI 共同治理
125+
- Anthropic 的 anthropics/skills (92.9k stars) 目前沒有任何 geo/maps skill — 空白機會
126+
- 我們的 `skills/google-maps/` 已 90% 符合 skillpm 格式
127+
- PR #644 已提交到 anthropics/skills
128+
129+
### Geo-AI Market Signals
130+
131+
- Google "Ask Maps" (2026-03-12): Gemini 驅動的對話式地圖搜尋，驗證賽道
132+
- MIT 研究：LLM 無 tool 輔助時旅行規劃成功率只有 ~4%
133+
- 62% 年輕旅客已用 AI 工具做旅行規劃
134+
- ChatGPT 沒有原生 Maps 整合 — MCP 填補空白
135+
- UPS 每減少一英里/司機/天 = $50M/年 savings
136+
137+
### Our Moat (validated)
138+
139+
| Type | Advantage |
140+
|---|---|
141+
| Technical | StreamableHTTP multi-tenant, per-session API key, Tool Annotations |
142+
| Design | Agent Skill (教 AI 怎麼思考地理問題), exec CLI, chaining patterns |
143+
| Market | Google Maps category leader (192 vs #2 at 14), npm user base |
144+
145+
### High-Value Use Case Tiers (for marketing/positioning)
146+
147+
**Tier 1 (huge market + perfect tool coverage)**:
148+
- Real estate analysis ($47T market)
149+
- Logistics multi-stop optimization ($200B+)
150+
- B2B field sales optimization
151+
- E-commerce delivery estimation ($6.3T)
152+
153+
**Tier 2 (large market + good coverage)**:
154+
- Data enrichment (CSV batch geocoding, $15B+)
155+
- Disaster response ($30B+)
156+
- Content creation (travel/city guides, $600B+)
157+
- Accessible route planning (61M disabled users)
158+
159+
### README / Marketing Playbook
160+
161+
Key elements proven to work (from Figma 13.7k, Playwright 28.8k, Serena 21.5k analysis):
162+
1. One-click install badges (Playwright) — already partially done
163+
2. GitHub-native video demo (Serena) — NOT DONE
164+
3. 3-bullet value proposition (Serena) — done in current README
165+
4. Star History chart — done
166+
5. vs comparison table (Playwright) — done (vs Grounding Lite)
167+
6. GitHub alert boxes `[!TIP]` (Serena) — done
168+
169+
Still missing:
170+
- Demo video (highest ROI remaining item)
171+
- User testimonials / community feedback section
172+
173+
### Growth Projections (research-backed)
174+
175+
| Milestone | Timeline | Driver |
176+
|---|---|---|
177+
| 300+ stars | 2-4 weeks | Registry submissions + content |
178+
| 500+ stars | 1-2 months | HN/Reddit + blog post |
179+
| 1,000+ stars | 3-4 months | Sustained content + community |
180+
181+
Reference: HN front page averages +121 stars/24hr (median much lower). First 1000 is hardest, then organic discovery accelerates.
182+
183+
---
184+
185+
## Decided Not To Build
186+
187+
| Item | Reason | Source |
188+
|---|---|---|
189+
| maps_validate_address | $17/1000 too expensive, backend-only use case, geocode covers 60% | dev-roadmap-spec |
190+
| Spatial Context / Memory | Claude conversation history already solves this, composite tools reduce chaining | dev-roadmap-spec |
191+
| Language parameter for all tools | Existing behavior sufficient, deprioritized | strategy-todo |

0 commit comments

Comments
 (0)