Skip to content

Commit d370fd4

Browse files
cablateclaude
andauthored
docs: add Local SEO skill reference for Google Business Profile ranking analysis (#60)
New skill teaches AI agents how to audit business rankings, compare competitors, analyze area density, and scout locations using existing geo tools. Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 657cc4d commit d370fd4

4 files changed

Lines changed: 213 additions & 2 deletions

File tree

README.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -277,7 +277,8 @@ skills/
277277
│ ├── SKILL.md # Tool map, recipes, invocation
278278
│ └── references/
279279
│ ├── tools-api.md # Tool parameters + scenario recipes
280-
│ └── travel-planning.md # Travel planning methodology
280+
│ ├── travel-planning.md # Travel planning methodology
281+
│ └── local-seo.md # Local SEO / Google Business Profile ranking analysis
281282
└── project-docs/ # Project Skill — how to DEVELOP/MAINTAIN
282283
├── SKILL.md # Architecture overview + onboarding
283284
└── references/
@@ -341,6 +342,7 @@ These are the real-world scenarios driving our tool decisions:
341342
- **Disaster response** — "Nearest open hospitals? Am I in a flood zone?" (search-nearby + elevation)
342343
- **Content creation** — "Top 5 neighborhoods in Austin with restaurant density and airport distance" (explore-area + distance-matrix)
343344
- **Accessibility** — "Wheelchair-accessible restaurants, avoid steep routes" (search-nearby + place-details + elevation)
345+
- **Local SEO** — "Audit my restaurant's ranking vs competitors within 1km" (search-places + compare-places + explore-area)
344346

345347
## Changelog
346348

README.zh-TW.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -275,7 +275,8 @@ skills/
275275
│ ├── SKILL.md # 工具對照表、場景食譜、呼叫方式
276276
│ └── references/
277277
│ ├── tools-api.md # 工具參數 + 場景食譜
278-
│ └── travel-planning.md # 旅行規劃方法論
278+
│ ├── travel-planning.md # 旅行規劃方法論
279+
│ └── local-seo.md # Local SEO / Google 商家排名分析
279280
└── project-docs/ # Project Skill — 如何開發/維護
280281
├── SKILL.md # 架構概覽 + 入門指南
281282
└── references/
@@ -339,6 +340,7 @@ skills/
339340
- **災害應變** — 「最近有開的醫院?我在洪水區嗎?」(search-nearby + elevation)
340341
- **內容創作** — 「Austin 前 5 社區的餐廳密度和機場距離」(explore-area + distance-matrix)
341342
- **無障礙** — 「輪椅可達的餐廳,避開陡坡路線」(search-nearby + place-details + elevation)
343+
- **Local SEO** — 「分析我的餐廳在 1 公里內跟競爭對手的排名差距」(search-places + compare-places + explore-area)
342344

343345
## 更新日誌
344346

skills/google-maps/SKILL.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,5 +116,6 @@ npx @cablate/mcp-google-map exec <tool> '<json_params>' [-k API_KEY]
116116
|------|---------|--------------|
117117
| `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 |
118118
| `references/travel-planning.md` | Travel planning methodology — 6-layer model, Search Along Route, anti-patterns | When planning multi-day trips — **read before Recipe 1** |
119+
| `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 |
119120

120121
> For **project development** knowledge (architecture, API guide, GIS domain, design decisions), see `skills/project-docs/SKILL.md`.
Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
# Local SEO — Google 商家排名分析
2+
3+
## Core Principle
4+
5+
Local SEO is **competitive intelligence through public data**. Every business on Google Maps exposes its ranking signals: category, reviews, photos, hours, website. An AI agent with geo tools can audit a business's competitive position and identify actionable gaps — work that Local SEO consultants charge $30K–50K TWD for.
6+
7+
The Google Maps ranking algorithm weighs three factors:
8+
1. **Distance** — proximity to the searcher
9+
2. **Relevance** — how well the business matches the search query (categories, keywords in reviews/menus/services)
10+
3. **Prominence** — overall reputation (review count, rating, web mentions, citations)
11+
12+
Distance is fixed. Relevance and Prominence are what we analyze.
13+
14+
---
15+
16+
## The 5-Layer Analysis Model
17+
18+
### Layer 1: Keyword Landscape
19+
**What:** Understand what searchers type and who ranks for it.
20+
**Tool:** `maps_search_places("{keyword} in {area}")`
21+
**Example:**
22+
```
23+
maps_search_places("牛肉湯 台南") → who ranks for this keyword?
24+
maps_search_places("餐廳 台南中西區") → broader category competition
25+
maps_search_places("medical clinic Taipei") → English keyword landscape
26+
```
27+
**Output:** Top competitors list with place_ids for deeper analysis.
28+
29+
### Layer 2: Competitor Deep Dive
30+
**What:** Compare ranking signals across top competitors.
31+
**Tool:** `maps_compare_places` or `maps_place_details` per competitor
32+
**Signals to extract:**
33+
- Rating + review count (prominence)
34+
- Business categories (primary + secondary)
35+
- Has website / phone / hours (completeness)
36+
- Photo count (`photo_count` field)
37+
- Review content keywords
38+
39+
```
40+
maps_compare_places({
41+
query: "牛肉湯 台南",
42+
maxResults: 5,
43+
includeDistance: true,
44+
referenceLocation: "target business address"
45+
})
46+
```
47+
48+
**Key insight from practitioners:** A restaurant with category "日式餐廳" ranks differently than one with "餐廳". The primary category determines which search terms surface the business. Secondary categories add breadth.
49+
50+
### Layer 3: Gap Analysis
51+
**What:** Identify where the target business falls short vs competitors.
52+
**Tool:** `maps_place_details(target_place_id, maxPhotos: 5)` vs competitor details
53+
**Checklist:**
54+
55+
| Signal | Check | Fix if missing |
56+
|--------|-------|----------------|
57+
| Primary category | Matches highest-volume keyword? | Change to broader or more specific |
58+
| Review count | Within 80% of top competitor? | Review acquisition campaign |
59+
| Rating | ≥ 4.2? | Address negative reviews |
60+
| Photos | ≥ 10? With menu/interior/exterior? | Upload photos |
61+
| Website | Present? | Add website link |
62+
| Hours | Accurate? Special hours set? | Update hours |
63+
| Menu/Services | Complete? Keywords match search terms? | Add items with searchable names |
64+
65+
**Practitioner insight:** Menu item names must match what people search. If you sell 半熟蛋 (soft-boiled egg) but call it "大太陽" on your menu, the algorithm cannot match the search query to your business.
66+
67+
### Layer 4: Area Density & Opportunity
68+
**What:** Find underserved areas or oversaturated markets.
69+
**Tool:** `maps_explore_area` or `maps_search_nearby` with type filters
70+
```
71+
maps_explore_area({
72+
location: "大安區, 台北",
73+
types: ["restaurant", "cafe", "dentist"],
74+
radius: 1000
75+
})
76+
```
77+
**Analysis:**
78+
- High density + low avg rating = opportunity (bad competitors)
79+
- Low density = blue ocean (no competitors)
80+
- High density + high avg rating = red ocean (avoid or differentiate)
81+
82+
### Layer 5: Monitoring Snapshot
83+
**What:** Capture current ranking position for future comparison.
84+
**Tool:** `maps_search_places("{keyword}")` → record rank position of target business
85+
```
86+
maps_search_places("台南牛肉湯")
87+
→ Result: target business at position #4
88+
→ Baseline recorded. Re-run monthly to track movement.
89+
```
90+
91+
---
92+
93+
## Tool Call Sequences
94+
95+
### Scenario A: Full Competitor Audit (new client)
96+
```
97+
Phase 1 — Keyword Discovery (2-3 calls)
98+
maps_search_places("{primary keyword} {area}") → top competitors
99+
maps_search_places("{secondary keyword} {area}") → additional competitors
100+
maps_search_places("{category} near {address}") → proximity competitors
101+
102+
Phase 2 — Deep Comparison (1-2 calls)
103+
maps_compare_places(top 5 competitors + target) → side-by-side signals
104+
maps_place_details(target, maxPhotos: 5) → full target audit
105+
106+
Phase 3 — Area Analysis (1-2 calls)
107+
maps_explore_area(target location, multiple types) → neighborhood context
108+
maps_search_nearby(target coords, same type, 2km) → direct competitors within radius
109+
110+
Phase 4 — Visualize (1 call)
111+
maps_static_map(markers for all competitors + target) → competition map
112+
113+
Total: ~8-10 calls for a full audit
114+
```
115+
116+
### Scenario B: Quick Rank Check (existing client)
117+
```
118+
maps_search_places("{target keyword}") → find rank position
119+
maps_place_details(target_place_id) → current signals snapshot
120+
Total: 2 calls
121+
```
122+
123+
### Known Edge Case
124+
`maps_search_nearby` keyword parameter does not support Chinese category names (e.g., "日式餐廳"). Use English types (e.g., "japanese_restaurant") or use `maps_explore_area` / `maps_search_places` as alternatives — they handle Chinese queries correctly.
125+
126+
### Scenario C: New Location Scouting
127+
```
128+
maps_explore_area(candidate area, target business type) → competitor density
129+
maps_search_nearby(coords, type, radius: 2000) → detailed competitor list
130+
maps_distance_matrix(candidate locations, key landmarks) → accessibility analysis
131+
maps_static_map(area with competitor markers) → visual density map
132+
Total: 4 calls
133+
```
134+
135+
---
136+
137+
## Google Business Profile Signals Reference
138+
139+
### Signals the algorithm considers (from practitioner testing)
140+
141+
| Signal | Weight | How to check with our tools |
142+
|--------|--------|-----------------------------|
143+
| Primary business category | High | `place_details` → types |
144+
| Review count | High | `place_details` → user_ratings_total |
145+
| Average rating | High | `place_details` → rating |
146+
| Review content keywords | High | `place_details` → reviews text |
147+
| Photo count & quality | Medium | `place_details` → photo_count |
148+
| Business info completeness | Medium | `place_details` → website, phone, hours |
149+
| Menu/Service items | Medium (industry-specific) | `place_details` → check if present |
150+
| Review response rate | Medium | Not directly visible via API |
151+
| External citations (blogs, news) | Medium | Not available via Maps API |
152+
| NAP consistency (Name, Address, Phone) | Medium | `place_details` → verify across sources |
153+
| Google Posts activity | Low | Not available via API |
154+
155+
### What we CAN'T see (requires Business Profile backend access)
156+
- Search keyword impressions
157+
- Profile view breakdown (Maps vs Search, Mobile vs Desktop)
158+
- Direct vs Discovery search ratio
159+
- Call/direction/website click counts
160+
- Local 3-Pack appearance rate
161+
162+
### AI Mode recommendations
163+
Google's AI Mode pulls from:
164+
1. Business Profile data (hours, description, categories)
165+
2. Review content (specific mentions of products/services)
166+
3. External links (blogs, news, forums)
167+
4. Rating + review count (credibility signal)
168+
169+
High rating + high review count + keyword-rich reviews = higher chance of AI recommendation.
170+
171+
---
172+
173+
## Anti-Patterns
174+
175+
| Anti-Pattern | Symptom | Fix |
176+
|-------------|---------|-----|
177+
| Keyword stuffing in business name | "台北最好吃牛肉麵-王記牛肉麵" | Use real business name; keywords go in reviews/menu |
178+
| Ignoring secondary categories | Only one category set | Add relevant secondary categories |
179+
| Generic menu names | Creative names nobody searches for | Use searchable names that match queries |
180+
| Photo desert | 0-3 photos | Upload 10+ (exterior, interior, menu items, team) |
181+
| Review neglect | Many reviews with no owner reply | Reply to all reviews (affects activity score) |
182+
| Wrong primary category | "餐廳" when should be "日式餐廳" or vice versa | Match to highest-value keyword for your positioning |
183+
| Comparing wrong metrics | Comparing summer vs winter data | Compare year-over-year same period |
184+
185+
---
186+
187+
## Industry-Specific Notes
188+
189+
| Industry | Key ranking lever | Tool check |
190+
|----------|------------------|------------|
191+
| **Restaurants** | Menu completeness + review keywords about dishes | `place_details` → check menu presence |
192+
| **Medical/Clinics** | Review keywords about treatments + rating | `search_places("推薦 {specialty} {area}")` |
193+
| **Retail** | Product catalog + photos | `place_details` → photo_count |
194+
| **Hotels/B&B** | Amenity details + review sentiment | `place_details` → reviews |
195+
| **Services (plumber, lawyer, etc.)** | Service area coverage + review count | `search_nearby` to check competition density |
196+
| **Real estate** | Area expertise signals + review testimonials | `explore_area` for neighborhood analysis |
197+
198+
---
199+
200+
## When to Read This
201+
202+
- User asks to analyze a business's Google Maps ranking
203+
- User wants to compare competitors in an area
204+
- User says "Local SEO", "商家排名", "地圖行銷", "Google Business Profile"
205+
- User wants to scout a location for a new business
206+
- User asks "why does competitor X rank higher than me?"

0 commit comments

Comments
 (0)