# SEO maps Human Guide ## What This Is For Maps platform analysis for local businesses. It gives the agent a clearer input/output frame for search and SEO workflows: what context to ask for, what decisions to make, and what usable artifact to return. Use this as a human-readable version of the SEO maps agent skill. It is meant for marketers, operators, founders, and other non-coders who want the workflow without reading agent-specific implementation instructions. ## When To Use This - Use this when you need a repeatable process for SEO maps. - Use this when the task needs judgment, examples, constraints, or a clear output format rather than a one-off prompt. - Use this when you want to hand an AI assistant enough context to produce a usable marketing artifact. ## When Not To Use This - Do not use this when you only need a quick factual answer. - Do not use this when the work depends on private data you cannot share with the assistant. - Do not use this as a replacement for legal, compliance, financial, or medical review. ## What You Need Before Starting - The goal or business outcome you want. - The audience, customer segment, or market context. - Any source material the assistant should respect, such as notes, briefs, examples, URLs, or brand guidance. - Constraints such as tone, length, channel, deadline, region, or approval requirements. - A clear definition of what a good final answer should look like. ## Step-By-Step Workflow 1. State the job clearly: "Use the SEO maps guide to help me with..." 2. Add context: audience, goal, offer, channel, source material, and constraints. 3. Ask the assistant to identify missing inputs before producing the final output. 4. Have the assistant follow the skill-specific guidance below. 5. Review the result against the final checklist and ask for revisions where needed. ## Skill-Specific Guidance - Geocode business address to get center lat/lng - Generate grid points (default: 7x7, 5km radius) using Haversine offset formula - Display cost estimate and ask for confirmation before proceeding - Fire DataForSEO Maps SERP API calls with `location_coordinate` per grid point - Find target business rank at each point - Calculate SoLV: `(top_3_count / total_points) * 100` - Render ASCII heatmap in output - Fetch business profile via DataForSEO My Business Info API (keyword or CID) - Map API response fields to 25-field checklist - Score each field: Present + Optimized = 2pts, Present = 1pt, Missing = 0pts - Apply industry-specific weight multipliers - Fetch the business website via WebFetch ## Decision Points And Nuance The original skill emphasizes: Quick Reference, Three-Tier Capability Detection, Tier 0 (Free), Tier 1 (DataForSEO), Tier 2 (DataForSEO + Google Maps Platform), Geo-Grid Rank Tracking (Tier 1+), Workflow, Cost Warning (REQUIRED), GBP Profile Audit (Tier 1 preferred, Tier 0 manual), Tier 1 Workflow. Use these questions to steer the work: - What is the intended audience or buyer? - What source material must be preserved? - What should the assistant optimize for: clarity, persuasion, accuracy, speed, creativity, or conversion? - What examples represent the desired quality bar? - What should the assistant avoid? ## Common Mistakes - Do not duplicate seo-local on-page analysis. Recommend `/seo local ` for - Populate required properties: `@type`, `name`, `address`, `image` - **Do NOT generate self-serving review markup** -- Google ignores LocalBusiness review markup from the business itself. Only mark up third-party reviews visible on the page. - Load on-demand as needed (do NOT load all at startup): - | `FoodEstablishment` | Generic food (avoid if specific subtype exists) | - | `MedicalBusiness` | Generic medical (avoid if specific subtype exists) | - | `HomeAndConstructionBusiness` | Generic (avoid if specific subtype exists) | - Required vs Recommended Properties ## Copy-And-Paste Prompt ```text Use the SEO maps human guide. My goal: [Describe the business outcome] Audience: [Describe who this is for] Context and source material: [Paste notes, examples, links, or existing copy] Constraints: [Tone, length, channel, timeline, must-include items, must-avoid items] Before producing the final output, ask me for any missing information that would materially improve the result. ``` ## Final Checklist - [ ] The output matches the original goal. - [ ] The audience and context are reflected in the answer. - [ ] Important constraints and source material were preserved. - [ ] The assistant made the relevant decisions explicit. - [ ] The final artifact is ready to use, review, or hand to the next person. ## Source This guide was generated from the agricidaniel/claude-seo skill entry for `seo-maps`. ## Source Skill Notes These notes preserve the nuance from the original skill. Use them as supporting reference when the workflow above feels too generic. # Maps Intelligence (March 2026) Maps platform analysis for local businesses. Works with external APIs to assess how a business appears on Google Maps, Bing Places, Apple Maps, and OpenStreetMap. **Boundary with seo-local:** This skill analyzes the business on maps PLATFORMS (via APIs). seo-local analyzes local SEO signals on the WEBSITE (via HTML fetch). Do not duplicate seo-local on-page analysis. Recommend `/seo local ` for website-level checks. --- ## Quick Reference | Command | What it does | Tier | |---------|-------------|------| | `/seo maps ` | Full maps presence audit (auto-selects tier) | 0+ | | `/seo maps grid ` | Geo-grid rank scan (7x7, 1 keyword default) | 1+ | | `/seo maps reviews ` | Cross-platform review intelligence | 1+ | | `/seo maps competitors ` | Competitor radius mapping | 0+ | | `/seo maps nap ` | Cross-platform NAP verification | 0+ | | `/seo maps schema ` | Generate LocalBusiness JSON-LD from data | 0+ | | `/seo maps gbp ` | GBP completeness audit | 1+ | --- ## Three-Tier Capability Detection Before any analysis, detect the available capability tier: ### Tier 0 (Free) **Detection:** DataForSEO MCP tools NOT available. **Capabilities:** Overpass API competitor discovery, Geoapify POI search, Nominatim geocoding, static GBP checklist, schema generation, cross-platform NAP guidance. **Load:** `../seo/references/maps-free-apis.md` ### Tier 1 (DataForSEO) **Detection:** `business_data_business_listings_search` MCP tool IS available. **Capabilities:** Everything in Tier 0 PLUS geo-grid rank tracking, live GBP profile audit, review intelligence (velocity, sentiment, distribution), GBP post activity, Q&A data, Tripadvisor/Trustpilot reviews. **Load:** `../seo/references/maps-api-endpoints.md` ### Tier 2 (DataForSEO + Google Maps Platform) **Detection:** Tier 1 available AND Google Maps API key in environment. **Capabilities:** Everything in Tier 1 PLUS Google Places details, real-time business status, AI-powered place summaries, photo analysis. **Note:** Google ToS restricts storage to `place_id` only. Lat/lng cached 30 days max. **Always communicate the detected tier to the user** at the start of analysis. --- ## Geo-Grid Rank Tracking (Tier 1+) Simulates Google Maps searches from multiple GPS coordinates to show ranking variation across a geographic area. Requires DataForSEO. **Load:** `../seo/references/maps-geo-grid.md` for algorithm, SoLV formula, heatmap format. **Load:** `../seo/references/maps-api-endpoints.md` for Maps SERP endpoint details. ### Workflow 1. Geocode business address to get center lat/lng 2. Generate grid points (default: 7x7, 5km radius) using Haversine offset formula 3. **Display cost estimate and ask for confirmation before proceeding** 4. Fire DataForSEO Maps SERP API calls with `location_coordinate` per grid point 5. Find target business rank at each point 6. Calculate SoLV: `(top_3_count / total_points) * 100` 7. Render ASCII heatmap in output ### Cost Warning (REQUIRED) Before every geo-grid scan, display: ``` Geo-Grid Scan: [keyword] at [location] Grid: 7x7 (49 points) | Keywords: [N] | Est. cost: $[amount] DataForSEO credits will be consumed. Proceed? ``` --- ## GBP Profile Audit (Tier 1 preferred, Tier 0 manual)