SKILL.md
Maps Intelligence
This skill analyzes the business on maps platforms via APIs. claude-seo-local analyzes local signals on the website via HTML. Do not duplicate its on-page work, hand it off. Capability depends on which APIs are reachable, so detect the tier first and never promise data the tier cannot deliver.
Tier detection (do this first, tell the user)
| Tier | Detection | Adds |
|---|---|---|
| 0 (free) | No DataForSEO MCP tools | Overpass/Nominatim competitor discovery and geocoding, static GBP checklist, schema generation, NAP guidance |
| 1 | business_data_business_listings_search MCP tool available | Geo-grid rank tracking, live GBP audit, review intelligence, Tripadvisor/Trustpilot reviews |
| 2 | Tier 1 plus Google Maps API key in $GOOGLE_MAPS_API_KEY | Places details, real-time business status, place summaries. ToS: store only place_id, cache lat/lng 30 days max |
Task routing
| Task | Tier | Method |
|---|---|---|
| Full maps presence audit | 0+ | Run every workflow below the tier allows |
| Geo-grid rank scan | 1+ | Workflow below |
| Review intelligence | 1+ | Workflow below |
| Competitor radius map | 0+ | Overpass (Tier 0) or Maps SERP (Tier 1) |
| Cross-platform NAP check | 0+ | Google/Bing/Apple/OSM comparison |
| LocalBusiness schema from live data | 0+ | Schema workflow |
Read references/maps-workflows.md for the geo-grid algorithm, SoLV formula, GBP 25-field checklist, fake-review signals, and free-API query templates.
Geo-grid scans (Tier 1+)
Simulate Maps searches from a grid of GPS points to expose ranking variation across the service area.
- Geocode the business address to center coordinates.
- Generate the grid, default 7x7 at 5km radius.
- Show the cost estimate and get explicit confirmation: "Grid 7x7 (49 points) x N keywords, DataForSEO credits will be consumed. Proceed?" Never fire 49 paid calls unconfirmed.
- Query the Maps SERP per point with
location_coordinate, find the target business rank at each. - Compute SoLV: percentage of grid points where the business ranks top 3.
- Render the ASCII heatmap and report SoLV plus average rank.
Review intelligence (Tier 1+)
Pull Google reviews sorted newest first, compute velocity per month over 6 months, check for any 3-week gap (ranking risk), rating distribution, owner response rate, then compare with Tripadvisor and Trustpilot where available. Flag fake-review patterns per the signal list in references/maps-workflows.md, 2+ signals required before flagging.
Cross-platform NAP (Tier 0+)
Collect Name, Address, Phone from Google (GBP data or Maps SERP), Bing Maps (fetch the maps search page), Apple (no public API, recommend Apple Business Connect), and OSM (Overpass/Nominatim). Grade each field: exact match, partial, missing, conflicting. Severity: name mismatch Critical, address High, phone Medium. Recommend claiming anything unclaimed.
Schema generation (Tier 0+)
Build LocalBusiness JSON-LD from collected data: most specific industry subtype, required name/address/image, recommended telephone, url, geo, openingHoursSpecification, priceRange, plus branchOf, areaServed, sameAs for multi-location. Add aggregateRating only from real review data. Never generate self-serving review markup, Google ignores first-party review markup on LocalBusiness.
Output
MAPS-ANALYSIS-<domain>.md: health score /100 with dimension table, detected tier and what it could not assess, geo-grid heatmap with SoLV (Tier 1), GBP field-by-field audit, review intelligence tables, competitor landscape with density, cross-platform presence status, generated schema if missing, top 10 actions by severity, and credits consumed (Tier 1).
Verification
Before reporting, confirm the tier claim matches reality: at Tier 1, re-check that a DataForSEO business-data tool actually returned data this session; at Tier 0, confirm the report contains zero fields sourced from paid APIs. Expect every "Unknown (requires DataForSEO)" label to appear on fields the tier could not fetch. If a field has a value but no source, remove it or trace it.
Good vs bad
Good: "Tier 0 detected. Competitor radius via Overpass, GBP checklist from website signals only, 9 of 25 GBP fields marked Unknown. Install DataForSEO for the rest." Bad: "GBP score 78/100" at Tier 0 with no API data, scoring fields that were never observed. Unknown fields score as Unknown, not as guesses.
Footguns
- Unconfirmed geo-grid spend. A 7x7 grid is 49 paid calls per keyword. Always show the estimate and get a yes first.
- Google Maps data storage. ToS allows storing
place_idonly, lat/lng cached 30 days max. Do not write place details into long-lived reports as raw data dumps. - Business not found in Maps SERP. Try the business-info lookup by keyword before concluding absence, then report "not found in Google Maps for this location" rather than a zero rank.
- Multi-location ambiguity. Ask which location to analyze, or offer batch mode with a per-location cost estimate. Never silently pick one.
Completion checklist
- [ ] Tier detected and stated before analysis
- [ ] All paid scans confirmed by the user with cost estimate shown
- [ ] Unknowns labeled as Unknown, not scored
- [ ] NAP graded per field per platform with severities
- [ ] Schema generated only from observed data, no self-serving reviews
- [ ] On-page work handed to claude-seo-local, AI visibility to claude-seo-geo
Any box unchecked: not done. Fix or say so.