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 <url> for website-level checks.

---

Quick Reference

---

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)

Audits the 25 fields that affect Google Business Profile quality and ranking.

Load: ../seo/references/maps-gbp-checklist.md for full checklist and scoring.

Tier 1 Workflow

1. Fetch business profile via DataForSEO My Business Info API (keyword or CID)
2. Map API response fields to 25-field checklist
3. Score each field: Present + Optimized = 2pts, Present = 1pt, Missing = 0pts
4. Apply industry-specific weight multipliers
5. Normalize to 0-100 scale

Tier 0 Workflow

1. Fetch the business website via WebFetch
2. Extract any visible GBP signals (Maps embed, place references, review widgets)
3. Apply static checklist based on detectable signals
4. Mark undetectable fields as "Unknown (requires DataForSEO for live data)"

---

Review Intelligence (Tier 1+)

Cross-platform review analysis: velocity, sentiment, rating distribution, fake detection.

Reference: ../seo/references/local-seo-signals.md for benchmarks (shared with seo-local).

Workflow

1. Fetch Google reviews via DataForSEO Reviews API (sort by newest)
2. Calculate review velocity: reviews per month over last 6 months
3. Check 18-day rule (Sterling Sky): any 3-week gap = ranking risk
4. Analyze rating distribution: healthy = bell curve skewed to 5-star
5. Calculate owner response rate: responses / total reviews
6. Fetch Tripadvisor and Trustpilot reviews (if available)
7. Cross-platform comparison table

Fake Review Detection Signals

Flag reviews matching 2+ of these patterns:

• Uniform timing (multiple reviews same day/hour)
• Reviewer accounts with limited history or single review
• Geographic inconsistencies (reviewer location vs business location)
• Exclusively 5-star velocity spike (vs historical baseline)
• Identical or near-identical text across reviews
• Sudden volume spike without corresponding marketing activity

---

Competitor Radius Mapping (Tier 0+)

Identify and analyze competitors within a defined radius.

Tier 0 (Overpass API)

Load: ../seo/references/maps-free-apis.md for query templates.

1. Geocode business address
2. Query Overpass API for businesses with same OSM tag within radius
3. Parse results: name, address, phone, website, distance from center
4. Sort by distance, present as competitor landscape table

Tier 1 (DataForSEO)

1. Use Maps SERP API with business keyword + location
2. Extract top 20 competitors with full profile data
3. Compare: rating, review count, categories, photos, attributes
4. Calculate competitive density score: competitors per km^2

---

Cross-Platform NAP Verification (Tier 0+)

Check business listing consistency across Google, Bing Places, Apple, and OSM.

Workflow

1. Search for business name on each platform:
   • Google: infer from GBP data or Maps SERP result
   • Bing: WebFetch https://www.bing.com/maps?q=BUSINESS+NAME+LOCATION
   • Apple: manual check (no public API -- recommend Apple Business Connect at businessconnect.apple.com)
   • OSM: Overpass or Nominatim search
2. Extract NAP (Name, Address, Phone) from each source
3. Compare for consistency: exact match, partial match, missing, or conflicting
4. Flag discrepancies as Critical (name mismatch), High (address mismatch), Medium (phone mismatch)
5. Recommend claiming unclaimed profiles

---

Schema Generation (Tier 0+)

Generate LocalBusiness JSON-LD markup from collected data.

Reference: ../seo/references/local-schema-types.md for industry subtypes (shared with seo-local).

Workflow

1. Determine most specific schema subtype for the industry
2. Populate required properties: @type, name, address, image
3. Add recommended properties: telephone, url, geo, openingHoursSpecification, priceRange
4. Add strategic properties for multi-location: branchOf, areaServed, sameAs
5. Add aggregateRating if review data available
6. Output valid JSON-LD block ready for implementation

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.

---

Reference Files

Load on-demand as needed (do NOT load all at startup):

• ../seo/references/maps-api-endpoints.md: DataForSEO endpoint details, params, costs
• ../seo/references/maps-free-apis.md: Overpass, Geoapify, Nominatim query templates
• ../seo/references/maps-geo-grid.md: Grid algorithm, SoLV formula, heatmap rendering
• ../seo/references/maps-gbp-checklist.md: 25-field GBP audit with industry weights
• ../seo/references/local-seo-signals.md: Ranking factors, review benchmarks (shared)
• ../seo/references/local-schema-types.md: LocalBusiness subtypes by industry (shared)

---

Output

Generate MAPS-ANALYSIS-{domain}.md with:

1. Maps Health Score: XX/100 with dimension breakdown table
2. Capability tier detected (Tier 0 or Tier 1) with explanation of what's available
3. Geo-grid heatmap (Tier 1): ASCII grid with SoLV percentage and average rank
4. GBP profile audit: field-by-field scoring with industry-specific weights
5. Review intelligence: velocity chart, rating distribution, response rate, cross-platform comparison
6. Competitor landscape: count in radius, top 5 by rating/reviews, competitive density
7. Cross-platform presence: Google/Bing/Apple/OSM listing status
8. Schema recommendation: generated LocalBusiness JSON-LD (if missing or incomplete)
9. Top 10 prioritized actions (Critical > High > Medium > Low)
10. Cost report: DataForSEO credits consumed during analysis (Tier 1 only)
11. Limitations disclaimer: what could not be assessed at current tier

---

Cross-Skill Delegation

• Website on-page local signals: recommend /seo local <url>
• Full AI search visibility: recommend /seo geo <url>
• Schema validation and fixes: recommend /seo schema <url>
• Live SERP and keyword data: recommend /seo dataforseo [command]

---

Error Handling

---

Supporting file: LICENSE.txt

MIT License - see repository root LICENSE file for complete terms.

Copyright (c) 2026 AgriciDaniel
https://github.com/AgriciDaniel/claude-seo

---

Supporting file: skills/seo/references/local-schema-types.md

Local Schema Types & Industry-Specific Patterns (March 2026)

Schema is NOT a direct ranking factor (Confirmed: John Mueller, Gary Illyes). It indirectly impacts visibility through rich results (43% CTR increase, Webstix case study), better entity understanding, and AI search features.

---

Google-Supported LocalBusiness Subtypes

Food & Dining

Healthcare

Legal

Home Services

Real Estate

Automotive

Other Common Local Types

AnimalShelter, BeautySalon, ChildCare, DaySpa, DryCleaningOrLaundry, EmergencyService, EmploymentAgency, EntertainmentBusiness, FinancialService, FireStation, FurnitureStore, GasStation, GolfCourse, GovernmentOffice, HealthClub, Hotel, InsuranceAgency, Library, LodgingBusiness, NightClub, PetStore, PoliceStation, PostOffice, RecyclingCenter, ShoppingCenter, SkiResort, SportsActivityLocation, Store, TouristInformationCenter, TravelAgency, VeterinaryCare

---

Required vs Recommended Properties

Per Google Developers documentation (updated December 10, 2025, Confirmed).

Required (Minimum)

Recommended

SAB-Specific

---

Industry-Specific Schema Patterns

Restaurant

Restaurant (or specific subtype)
  + Menu > MenuSection > MenuItem (name, price, nutrition, suitableForDiet)
  + ReserveAction (booking capabilities)
  + OrderAction (takeout/delivery)
  + servesCuisine, acceptsReservations

Note: Google Food Ordering (GFO) direct checkout discontinued June 2024. "Order Online" button now redirects to third-party platforms.

Healthcare

MedicalClinic (or Hospital, Dentist)
  + Physician pages: Person + medicalSpecialty + hospitalAffiliation + hasCredential
  + MedicalSpecialty (helps match "hip replacement surgery" to relevant pages)
  + sameAs: link to NPI Registry entry and medical board page

HIPAA constraint: Cannot confirm/deny reviewer is a patient in review responses. Fine precedent: $30,000 (Manasa Health Center, 2023).

Legal

LegalService (NOT Attorney -- deprecated)
  + Person on attorney bio pages: jobTitle, worksFor, alumniOf, hasCredential (bar admissions)
  + makesOffer > Service (one per practice area)
  + Practitioner GBP: unique phone per attorney, not sole lawyer at firm

Note: Reviews follow practitioner listing when attorney changes firms.

Home Services

Specific subtype (Plumber, Electrician, etc.)
  + areaServed: named cities with sameAs to Wikipedia/Wikidata
  + Service on individual service pages, linked via provider
  + hasOfferCatalog for service listings

SAB note: Service area in GBP does NOT currently impact rankings -- rankings based on verification address (Sterling Sky, March 2025).

Real Estate

RealEstateAgent (for both agent and brokerage)
  + Person on agent pages: memberOf (brokerage), credentials
  + RealEstateListing + SingleFamilyResidence/Apartment + Offer (pricing)
  + Event for open houses with organizing agent

Note: No RealEstateBrokerage type exists on Schema.org.

Automotive

AutoDealer (sales)
  + Car/Vehicle: VIN, mileage, fuelType, vehicleTransmission
  + Offer: price, priceCurrency, availability
  + Separate GBP: AutoRepair (service), AutoPartsStore (parts)

VehicleListing deprecated June 12, 2025 (Confirmed). Use Car + Offer instead. Feed-based Vehicle Listings via Google Merchant Center still functional.

---

Industry-Specific Citation Sources

Restaurant

Yelp, TripAdvisor (1B+ reviews), OpenTable (DA + bookings), DoorDash, UberEats, Grubhub, Foursquare (powers Apple Maps, Uber)

Healthcare

Healthgrades (50% of Americans who see a doctor visit), Zocdoc (booking + lead gen), WebMD physician directory (high DA), Vitals, Doximity (80% of US physicians), NPI Registry (entity verification source of truth), state medical board directories

Legal

FindLaw (DA91, dofollow), Martindale-Hubbell (DA84, peer review since 1868), Avvo (1-10 ratings, auto-created from bar data), Justia (DA~70, free profiles), Super Lawyers (top 5%, selection-based), state bar directories (entity verification)

Note: Internet Brands (KKR) owns Avvo + Martindale + Lawyers.com + Nolo. Thomson Reuters owns FindLaw + Super Lawyers + LawInfo.

Home Services

Thumbtack ($400M revenue 2024, integrations with ChatGPT/Alexa/Zillow), BBB, Nextdoor, Yelp. Declining: Angi (revenue -30% from 2022 peak), Porch (pivoted to insurance), Houzz (pivoted to SaaS)

Real Estate

Zillow (44% of all RE search traffic, integrated into ChatGPT Oct 2025), Homes.com (#2, overtook Realtor.com, 100M monthly visitors), Realtor.com, Redfin (acquired by Rocket Companies Mar 2025), local MLS sites

Automotive

Cars.com, AutoTrader, CarGurus, DealerRater (reviews syndicate to Cars.com + OEM sites, supports salesperson ratings), Edmunds, Kelley Blue Book (pricing authority), OEM manufacturer dealer locators (entity verification)

---

Multi-Location Schema Pattern

// Homepage: Organization with branchOf references
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://example.com/#org",
  "name": "Brand Name",
  "url": "https://example.com"
}

// Each location page: individual LocalBusiness
{
  "@context": "https://schema.org",
  "@type": "Dentist",
  "@id": "https://example.com/locations/downtown/#location",
  "name": "Brand Name - Downtown",
  "branchOf": { "@id": "https://example.com/#org" },
  "address": { ... },
  "geo": { "latitude": "40.71234", "longitude": "-74.00567" },
  "telephone": "+1-555-123-4567",
  "openingHoursSpecification": [ ... ]
}

Use @id for unique identifiers per location. Subdirectory structure recommended: domain.com/locations/city-name/ (subdirectory consolidates link equity better than subdomain, Bruce Clay study: 50%+ traffic lift).

---

Deprecated/Invalid Local Schema

---

Supporting file: skills/seo/references/local-seo-signals.md

Local SEO Ranking Signals & Benchmarks (March 2026)

Source Key

• Confirmed: Google official documentation or employee statements
• Study: Data-driven industry research from recognized firms
• Consensus: Practitioner agreement without controlled testing
• Caution: Single-source or unverified claims

---

Whitespark 2026 Local Search Ranking Factors

Published November 6, 2025. 47 experts surveyed across 187 factors. (Study)

Local Pack/Maps Factor Groups

Top 15 Individual Local Pack Factors

1. Primary GBP category (score: 193)
2. Keywords in GBP business title (score: 181)
3. Proximity of address to search point (score: 176)
4. Verified GBP
5. Business open at time of search (Sterling Sky controlled study)
6. High numerical Google ratings
7. Quantity of native Google reviews
8. Additional GBP categories
9. Review recency/velocity
10. Dedicated service pages
11. Domain authority
12. NAP consistency
13. Spam listing removal
14. Quality backlinks
15. Review sentiment

Top Negative Factors

1. Incorrect primary category (score: 176) -- single worst mistake
2. Duplicate profiles at same address (score: 142)

---

Search Atlas ML Study (August 2025)

XGBoost regression model, explains 92-93% of variance. (Study)

---

Review Benchmarks

Sterling Sky Findings (2025, Study)

• Magic 10 threshold: Significant ranking boost at 10 reviews. 9-to-10 = noticeable increase. 10-to-11 = no similar bump.
• 18-Day Rule: Rankings "fall off a cliff" if no new reviews for 3 weeks. Velocity > volume.

BrightLocal LCRS 2026 (February 2026, Study)

Review Platform Usage (BrightLocal 2026)

Enforcement

• Google blocked/removed 240M+ policy-violating reviews in 2024 (Confirmed, 40% increase over 2023)
• Review deletion rates up 600%+ Jan-Jul 2025; 38% of deleted were 5-star (Study, GMBapi.com)
• FTC Consumer Review Rule effective Oct 21, 2024: penalties up to $53,088/violation (Confirmed, US law)
• Review gating prohibited by both Google (fake engagement policy) and FTC (Confirmed)

---

Citation Source Tiers

Tier 1 (Universal, All Industries)

Tier 2 (Broad Directories)

BBB, YellowPages, Manta, Superpages, Foursquare, Nextdoor

Tier 3 (Data Aggregators)

Industry-specific directories: see local-schema-types.md

---

GBP Feature Status (March 2026)

Deprecated/Removed

Active Features

Posts (with scheduling), Services menu, Attributes (including identity: Women-led, Eco-friendly), Photos/Video, Local Lists (Local Gems, Trending, Top List), AI-generated "Suggest Description", Google Verified badge (replaced Guaranteed/Screened Oct 2025)

Key GBP Insights

• Posts: No direct ranking impact (WebFX empirical testing). Can trigger Post Justifications. (Study)
• Photos: "Likely a ranking benefit adding some vs none, but not continued benefit adding more" (WebFX). Geotagging has NO impact. 45% more direction requests with photos. (Study/Confirmed mix)
• Attributes: Identity attributes have minor, targeted impact for attribute-specific searches only (WebFX/Sterling Sky). General attributes are filter/informational, NOT direct ranking factors. (Study)

---

Algorithm Updates Affecting Local (2025-2026)

---

Voice Search & Assistants

• 58% of voice searches are for local business information (Study, BusinessDasher)
• Voice queries typically 4-7 words, phrased as complete questions (Consensus)
• 80%+ of Google Assistant voice answers come from top 3 search results (Study)

---

AI Search Impact on Local

ChatGPT sources: Bing web index (primary), Yelp, TripAdvisor, BBB, Reddit. Does NOT access GBP directly. (Study, Search Engine Land)

Perplexity sources: Authority-first. 40% more from high-authority sites. Averages 21.87 citations per question. (Study, Qwairy)

---

Local Pack Structure

• Standard: 3 results (universal)
• New: Curated Local Lists (Local Gems, Trending) around position 4 (SOCi, Nov 2025)
• AI-powered local packs (mobile US): Only 1-2 businesses, 32% fewer businesses shown (Sterling Sky)
• Local pack ads grew from ~1% to 22% of tracked mobile keywords in 12 months (Sterling Sky/Places Scout)
• Zero-click rate for local-intent searches: up to 78% on mobile (Similarweb)

---

Proximity & Search Behavior

• 46% of all Google searches seek local information (Study)
• 76% of mobile "near me" searches lead to visit within 24 hours (Confirmed, Google)
• 900% increase in "near me" searches over two years (Confirmed/Study, Google)
• Proximity varies: urban 1-2 miles, rural 5-10+ miles, specialty/niche = wider (Consensus)
• Google uses dynamic weighting per query: "emergency plumber near me" = proximity-dominant; "best plastic surgeon" = prominence-dominant (Consensus)

---

Supporting file: skills/seo/references/maps-api-endpoints.md

DataForSEO Maps & Business Data API Endpoints

Source Key

• Docs: docs.dataforseo.com (official API documentation)
• Pricing: dataforseo.com/pricing (official pricing pages)

---

Authentication & Limits

• HTTP Basic Auth (login:password)
• Rate limit: 2,000 API calls/minute across all endpoints
• Each POST supports up to 100 tasks in a single request
• Minimum deposit: $50. $1 free trial credit. Credits never expire.

---

Google Maps SERP API (Geo-Grid Backbone)

Endpoint: POST https://api.dataforseo.com/v3/serp/google/maps/live/advanced Pricing source: https://dataforseo.com/pricing/serp-api

Request Parameters

Critical for geo-grid: Use location_coordinate to simulate searches from specific GPS points. Format: "40.7128,-74.0060,15z".

Response Fields (per business item)

cid, place_id, feature_id, title, domain, url, category, additional_categories, address, phone (via contact_info array), rating.value, rating.votes_count, rating.rating_distribution (1-5 star breakdown), price_level, attributes (grouped: accessibility, payments, children), work_time (per-day timetable + current_status), popular_times (hourly by day), latitude, longitude, local_business_links (booking, menu, order URLs)

Pricing

Search operators in keyword multiply cost by 5x.

---

Google My Business Info API (Single Business Deep-Dive)

Endpoint: POST https://api.dataforseo.com/v3/business_data/google/my_business_info/live Pricing source: https://dataforseo.com/pricing/business-data

Input Options

• keyword: Business name + location (e.g., "Starbucks Austin TX")
• "cid:XXXX": Direct CID lookup
• "place_id:XXXX": Direct Place ID lookup

Response Fields

Full profile: title, description, category, additional_categories, category_ids, attributes (available + unavailable, grouped by type), contact_info (phone array), domain, url, work_hours (per-day with open/close times), popular_times, cid, place_id, rating (with distribution), address_info (full breakdown), latitude/longitude, photos_count, main_image

Cost: $0.0015 per profile (standard queue)

Use case: Deep-dive on the TARGET business. Maps SERP for competitor discovery.

---

Google Reviews API (Sentiment & Velocity)

Endpoint: POST https://api.dataforseo.com/v3/business_data/google/reviews/task_post Pricing source: https://dataforseo.com/pricing/business-data

Parameters

Response Fields (per review)

review_text, original_review_text, time_ago, timestamp, rating.value, review_id, profile_name, profile_url, profile_image_url, owner_answer (text + timestamp), review_images

Pricing

Optimization: Always use place_id or cid input (4x cheaper than keyword).

---

Google Q&A API

Endpoint: POST https://api.dataforseo.com/v3/business_data/google/questions_and_answers/live

Returns questions, answers, upvotes, dates, answer sources. Live and standard methods available.

Use case: Identify unanswered questions, FAQ gap analysis.

Note: Google deprecated GBP Q&A in Dec 2025 (replaced by Ask Maps Gemini AI). This endpoint returns historical data.

---

Business Listings Search (Pre-Indexed Database)

Endpoint: POST https://api.dataforseo.com/v3/business_data/business_listings/search/live

Queries DataForSEO's pre-indexed database (not live Google). Faster for bulk category-based queries. Up to 700+ results per query.

Categories Aggregation: /v3/business_data/business_listings/categories_aggregation/live provides category taxonomy.

MCP tool name: business_data_business_listings_search

---

Cross-Platform Review APIs

Tripadvisor

• Search: /v3/business_data/tripadvisor/search/task_post
• Reviews: /v3/business_data/tripadvisor/reviews/task_post
• Billed per 30 reviews. Standard method only.

Trustpilot

• Search: /v3/business_data/trustpilot/search/task_post
• Reviews: /v3/business_data/trustpilot/reviews/task_post
• ~$0.00075/task. Standard method only.

---

Cost Estimation Table

Formula: grid_size^2 x keywords x $0.002 (live) or x $0.0006 (standard)

---

Supporting file: skills/seo/references/maps-free-apis.md

Free Maps APIs for claude-seo

Source Key

• Docs: Official API documentation for each service
• Policy: Official usage policies and terms

---

Overpass API (Best Free Option for Competitor Discovery)

Base URL: https://overpass-api.de/api/interpreter Docs: https://wiki.openstreetmap.org/wiki/Overpass_API License: ODbL (attribution required: "Data from OpenStreetMap")

Rate Limits

• Slot-based: ~2 concurrent queries per IP
• Guideline: ~10,000 requests/day, ~1 GB/day download
• Default timeout: 180 seconds, 512 MiB memory per query
• Use [timeout:25] for lighter queries

Query Templates

Restaurants within 5km radius:

curl -s "https://overpass-api.de/api/interpreter" \
  --data-urlencode 'data=[out:json][timeout:25];(node["amenity"="restaurant"](around:5000,LAT,LNG);way["amenity"="restaurant"](around:5000,LAT,LNG););out body;>;out skel qt;'

All businesses on a street:

curl -s "https://overpass-api.de/api/interpreter" \
  --data-urlencode 'data=[out:json][timeout:25];way["name"="STREET_NAME"]["addr:city"="CITY"];(._;>;);out body;'

Competitor POIs by category in bounding box:

curl -s "https://overpass-api.de/api/interpreter" \
  --data-urlencode 'data=[out:json][timeout:25];(node["amenity"="dentist"](SOUTH,WEST,NORTH,EAST);way["amenity"="dentist"](SOUTH,WEST,NORTH,EAST););out body;>;out skel qt;'

Key OSM Tags for Local SEO

Response Fields

Each element returns: id, lat, lon, tags object containing name, phone, website, opening_hours, addr:street, addr:housenumber, addr:city, addr:postcode, cuisine, brand, etc.

Limitations

• No reviews, ratings, or popularity data
• No GBP-specific information
• Data quality varies by region (excellent in Europe, inconsistent elsewhere)
• Volunteer-contributed data; may be outdated
• Interactive tester: https://overpass-turbo.eu/

---

Geoapify Places API (Structured POI Search)

Base URL: https://api.geoapify.com/v2/places Docs: https://apidocs.geoapify.com/docs/places/ Pricing: https://www.geoapify.com/pricing

Free Tier

• 3,000 credits/day (1 credit = 20 places returned)
• 5 requests/second
• Requires API key (free registration, no credit card)
• Caching and storage explicitly permitted (unlike Google)

Query Template

curl -s "https://api.geoapify.com/v2/places?categories=catering.restaurant&filter=circle:LNG,LAT,5000&limit=20&apiKey=YOUR_KEY"

Category Hierarchy

Uses dot-separated categories: catering.restaurant, commercial.supermarket, healthcare.dentist, service.financial.accounting, commercial.vehicle.car_dealer

Response Format

GeoJSON FeatureCollection. Each feature has properties: name, city, state, postcode, country, street, housenumber, phone, website, categories, lat, lon, place_id, formatted (full address string)

Advantages Over Raw Overpass

• Cleaner, structured responses
• Aggregated data (OSM + OpenAddresses + WhosOnFirst + GeoNames)
• Hierarchical category taxonomy
• No rate limit surprises (clear credit system)

---

Nominatim (Geocoding Only)

Base URL: https://nominatim.openstreetmap.org Docs: https://nominatim.org/release-docs/latest/api/Overview/ Policy: https://operations.osmfoundation.org/policies/nominatim/

Rate Limits (STRICT)

• 1 request/second (absolute)
• Must include valid User-Agent header (stock library agents rejected)
• Auto-complete queries forbidden
• Bulk geocoding forbidden on public instance
• Repeated identical queries trigger bans (cache results)

Forward Geocoding

curl -s "https://nominatim.openstreetmap.org/search?q=123+Main+St+Austin+TX&format=json&addressdetails=1" \
  -H "User-Agent: claude-seo/1.7.0"

Reverse Geocoding

curl -s "https://nominatim.openstreetmap.org/reverse?lat=40.7128&lon=-74.0060&format=json" \
  -H "User-Agent: claude-seo/1.7.0"

Response Fields

place_id, lat, lon, display_name, importance, category, type, address object (house_number, road, city, state, postcode, country)

Best Use

• Address-to-coordinates conversion for geo-grid center point
• Reverse geocoding to validate business addresses
• NOT suitable for business listing discovery (use Overpass or Geoapify)

---

Rate Limit Enforcement Pattern

# Nominatim: enforce 1 req/sec with sleep
for addr in "${addresses[@]}"; do
  curl -s "https://nominatim.openstreetmap.org/search?q=${addr}&format=json" \
    -H "User-Agent: claude-seo/1.7.0"
  sleep 1.1
done

# Overpass: no explicit rate limit, but use reasonable timeouts
# If HTTP 429 returned, implement exponential backoff

# Geoapify: 5 req/sec on free tier, no explicit enforcement needed

---

Comparison Table

---

Supporting file: skills/seo/references/maps-gbp-checklist.md

GBP Profile Completeness Checklist (Via API)

This checklist scores a Google Business Profile using data retrieved from the DataForSEO My Business Info API. It measures profile completeness on the maps PLATFORM, not on-page signals (seo-local handles on-page).

Sources

• Google official: https://support.google.com/business/answer/7091
• Whitespark 2026 Local Search Ranking Factors (Study)
• BrightLocal LCRS 2026 (Study)

---

Scoring System

Each field: Present + Optimized = 2pts, Present = 1pt, Missing = 0pts

Total possible: 50 points. Normalize to 0-100 scale: (score / 50) * 100

---

Critical Fields (Direct Ranking Impact)

Subtotal: 16 points (8 fields)

---

Important Fields (Significant Influence)

Subtotal: 16 points (8 fields)

---

Supplementary Fields (Supporting Signals)

Subtotal: 18 points (9 fields)

---

Industry-Specific Weight Adjustments

When scoring, apply multipliers to fields that matter more for specific industries:

Restaurant

• Menu/services link: x2 (critical for food-related searches)
• Photos: x1.5 (food photos drive engagement)
• Booking link: x1.5 (reservation systems expected)
• Attributes: x1.5 (dietary, dine-in/takeout/delivery critical)

Healthcare

• Business hours: x1.5 (patients need accurate hours)
• Attributes: x1.5 (insurance, accessibility, telehealth)
• Services list: x2 (insurance and procedure matching)

Legal

• Business description: x1.5 (practice area clarity)
• Services list: x2 (practice area matching drives visibility)
• Photos: x0.5 (less impactful for legal)

Home Services

• Service areas: x2 (SAB model depends on this)
• Business hours: x1.5 (emergency availability)
• Photos: x1.5 (before/after project photos)

Real Estate

• Photos: x2 (property photos critical)
• Social profiles: x1.5 (agent branding)
• Posts: x1.5 (listing updates)

Automotive

• Products: x2 (vehicle inventory)
• Photos: x2 (vehicle photos)
• Services list: x1.5 (sales + service departments)

Re-normalization After Multipliers

After applying industry multipliers, re-normalize so the total remains 0-100:

final_score = (weighted_raw_score / max_possible_weighted_score) * 100

This ensures consistent scoring regardless of which industry multipliers are active.

---

Score Interpretation

---

Data Mapping (DataForSEO → Checklist)

---

Supporting file: skills/seo/references/maps-geo-grid.md

Geo-Grid Rank Tracking Algorithm

Concept

Geo-grid rank tracking simulates Google Maps searches from multiple GPS coordinates around a business to show how rankings vary across a geographic area. The output is a heatmap revealing where the business ranks well (green) and where competitors dominate (red).

---

Grid Generation (Haversine-Based)

Algorithm

1. Take center coordinates (business location): center_lat, center_lng
2. Define grid size (e.g., 7x7 = 49 points) and radius in km
3. Calculate spacing: step = (2 * radius_km) / (grid_size - 1)
4. Generate grid points using offset formula:

For each row i (0 to grid_size-1) and column j (0 to grid_size-1):
  dy = (i - center_index) * step_km
  dx = (j - center_index) * step_km
  new_lat = center_lat + (dy / 111.32)
  new_lng = center_lng + (dx / (111.32 * cos(center_lat * pi/180)))

Where center_index = (grid_size - 1) / 2 and 111.32 km = 1 degree latitude.

Grid Sizes and Use Cases

Radius guidelines: Urban dense = 2-5 km, suburban = 5-10 km, rural = 10-25 km.

---

DataForSEO Integration

Use the Google Maps SERP API with location_coordinate parameter:

{
  "keyword": "dentist",
  "location_coordinate": "30.2672,-97.7431,15z",
  "language_code": "en",
  "device": "mobile",
  "depth": 20
}

For each grid point, fire one API call with the point's lat/lng. Parse the items array to find the target business rank (position in results).

Rate optimization: DataForSEO allows up to 100 tasks per POST. For a 7x7 grid, batch all 49 tasks into a single request to minimize HTTP overhead.

---

Share of Local Voice (SoLV)

Metric pioneered by Local Falcon. Measures visibility across the grid.

Calculation

SoLV = (points_in_top_3 / total_grid_points) * 100

Interpretation

Extended Metrics

• Average Rank: Mean position across all grid points (lower = better)
• Visibility Score: Weighted average where top 3 = 3pts, 4-10 = 1pt, 10+ = 0pts
• Worst Quadrant: Identify which compass direction has weakest rankings

---

ASCII Heatmap Rendering

For terminal/Markdown output, render a grid using rank-position symbols:

Format

Geo-Grid: "dentist" (7x7, 5km radius, center: 30.267, -97.743)

     W -------- E
  N  1  1  2  3  5  8  -
  |  1  1  1  2  3  6  9
  |  2  1  [1] 1  2  4  7
  |  3  2  1  1  1  3  5
  |  5  3  2  1  2  4  8
  |  8  5  3  2  3  6  -
  S  -  8  5  4  5  9  -

Legend: [1]=center, 1-3=top 3 (strong), 4-10=visible, -=not ranked
SoLV: 57% (28/49 grid points in top 3)
Avg Rank: 3.4 | Weakest: NE quadrant (avg rank 7.2)

Color Mapping (for enhanced output)

---

Multi-Keyword Grid

For comprehensive analysis, scan 2-3 keywords on the same grid:

1. Primary service keyword (e.g., "dentist")
2. Brand + location (e.g., "Smith Dental Austin")
3. Long-tail intent (e.g., "emergency dentist near me")

Cost for 3-keyword 7x7 scan: 147 API calls = ~$0.29 (live) or ~$0.088 (standard)

---

Cost Warning Template

Before running a geo-grid scan, display:

Geo-Grid Scan Estimate:
  Grid: 7x7 (49 points)
  Keywords: 3
  API calls: 147
  Estimated cost: $0.09 (standard) - $0.29 (live)
  Proceed? [DataForSEO credits will be consumed]