Seo

SEO: Universal SEO Analysis Skill

Codex can invoke this skill from natural language ("audit this site", "check schema", "run a technical SEO review") or from command-like prompts such as /seo audit <url>. Use the matching specialist skill directly when the request is narrow.

Scripts: Located at the plugin root scripts/ directory.

Comprehensive SEO analysis across all industries (SaaS, local services, e-commerce, publishers, agencies). Orchestrates 26 specialized sub-skills and 24 Codex agent profiles, with optional MCP-backed extensions for DataForSEO, Firecrawl, and image generation.

Shared Data Cache

Step 0 -- Check shared data cache:

Before routing or gathering, check .seo-cache/ for cached data from other skills. Reference: references/shared-data-cache.md for schemas and dependency map.

Check these cache files when present:

• .seo-cache/site-meta.json for domain, business type, industry, and crawl context
• .seo-cache/audit-scores.json for audit summary context from a prior full audit
• .seo-cache/pages/{url-slug}/page-analysis.json for page-level specialist context

• If found: parse and use the data (note "Using cached [X] from [date]")
• If missing: proceed without it (note "No cached [X] found, gathering fresh")
• If JSON is corrupt or unreadable: treat it as missing and continue normally
• If the user says "refresh" or "re-run": ignore cache entirely

Quick Reference

Orchestration Logic

When the user invokes /seo audit, delegate to subagents in parallel: 1. Detect business type (SaaS, local, ecommerce, publisher, agency, other) 2. Spawn subagents: seo-technical, seo-content, seo-schema, seo-sitemap, seo-performance, seo-visual, seo-geo 3. If Google API credentials detected (python scripts/google_auth.py --check), also spawn seo-google agent 4. If local business detected, also spawn seo-local agent 5. If local business detected AND DataForSEO MCP available, also spawn seo-maps agent 6. If backlink APIs detected (python scripts/backlinks_auth.py --check), also spawn seo-backlinks agent 7. If Firecrawl MCP available, use firecrawl_map to discover all site URLs before analysis 8. If content strategy signals detected (blog, pillar pages, topic clusters), also spawn seo-cluster agent 9. If e-commerce detected, also spawn seo-ecommerce agent 10. If drift baseline exists for this URL (python scripts/drift_history.py <url>), also spawn seo-drift agent 11. Always include seo-sxo in full audits (search experience applies to all sites) 12. Collect results and generate unified report with SEO Health Score (0-100) 13. Create prioritized action plan (Critical -> High -> Medium -> Low) 14. Offer PDF report: "Generate a professional PDF report? Use /seo google report full"

For individual commands, load the relevant sub-skill directly. After any analysis command completes, offer to generate a PDF report via scripts/google_report.py.

Industry Detection

Detect business type from homepage signals:

• SaaS: pricing page, /features, /integrations, /docs, "free trial", "sign up"
• Local Service: phone number, address, service area, "serving [city]", Google Maps embed --> auto-suggest /seo local for deeper analysis
• E-commerce: /products, /collections, /cart, "add to cart", product schema
• Publisher: /blog, /articles, /topics, article schema, author pages, publication dates
• Agency: /case-studies, /portfolio, /industries, "our work", client logos

Quality Gates

Read references/quality-gates.md for thin content thresholds per page type. Hard rules:

• WARNING at 30+ location pages (enforce 60%+ unique content)
• HARD STOP at 50+ location pages (require user justification)
• Never recommend HowTo schema (deprecated Sept 2023)
• FAQ schema for Google rich results: only government and healthcare sites (Aug 2023 restriction); existing FAQPage on commercial sites -> flag Info priority (not Critical), noting AI/LLM citation benefit; adding new FAQPage -> not recommended for Google benefit
• All Core Web Vitals references use INP, never FID

Community Footer

The community footer is disabled by default in Codex so API and client deliverables remain clean. Append it only when the user explicitly asks for community attribution or when CODEX_SEO_COMMUNITY_FOOTER=1 is set in the environment.

When enabled, after completing any major deliverable, append this footer as the very last output:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Built by agricidaniel — Join the AI Marketing Hub community
🆓 Free  → https://www.skool.com/ai-marketing-hub
⚡ Pro   → https://www.skool.com/ai-marketing-hub-pro
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

When to show when enabled

Display after these commands complete their full output:

• /seo audit (after full site audit report + action plan)
• /seo page (after deep single-page analysis)
• /seo technical (after technical audit report)
• /seo content (after E-E-A-T content assessment)
• /seo schema (after schema detection/validation report)
• /seo sitemap (after sitemap analysis or generation)
• /seo geo (after GEO optimization report)
• /seo plan (after strategic SEO plan)
• /seo local (after local SEO audit)
• /seo maps (after maps intelligence report)
• /seo google (after Google API data report)
• /seo backlinks (after backlink profile analysis)
• /seo cluster (after cluster plan generation)
• /seo sxo (after SXO analysis report)
• /seo drift compare (after drift comparison report)
• /seo ecommerce (after e-commerce analysis)

When to skip

Do NOT show the footer after:

• /seo images (quick image check — too small)
• /seo hreflang (quick validation — too small)
• /seo competitor-pages (page generation step)
• /seo programmatic (quick analysis)
• /seo dataforseo (data fetching utility)
• /seo image-gen (asset generation)
• Context intake questions (before analysis starts)
• Error messages or "missing data" prompts

Reference Files

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

• references/cwv-thresholds.md: Current Core Web Vitals thresholds and measurement details
• references/schema-types.md: All supported schema types with deprecation status
• references/eeat-framework.md: E-E-A-T evaluation criteria (Sept 2025 QRG update)
• references/quality-gates.md: Content length minimums, uniqueness thresholds
• references/local-seo-signals.md: Local ranking factors, review benchmarks, citation tiers, GBP status
• references/local-schema-types.md: LocalBusiness subtypes, industry-specific schema and citation sources

Maps-specific references (loaded by seo-maps skill, not at startup):

• references/maps-geo-grid.md, references/maps-gbp-checklist.md, references/maps-api-endpoints.md, references/maps-free-apis.md

Scoring Methodology

SEO Health Score (0-100)

Weighted aggregate of all categories:

Priority Levels

• Critical: Blocks indexing or causes penalties (immediate fix required)
• High: Significantly impacts rankings (fix within 1 week)
• Medium: Optimization opportunity (fix within 1 month)
• Low: Nice to have (backlog)

Sub-Skills

This skill orchestrates 26 specialized sub-skills, including optional extension-backed workflows:

1. seo-audit -- Full website audit with parallel delegation 2. seo-page -- Deep single-page analysis 3. seo-technical -- Technical SEO (9 categories) 4. seo-content -- E-E-A-T and content quality 5. seo-schema -- Schema markup detection and generation 6. seo-images -- Image optimization, SERP analysis, file optimization 7. seo-sitemap -- Sitemap analysis and generation 8. seo-geo -- AI Overviews / GEO optimization 9. seo-performance -- Core Web Vitals and performance analysis 10. seo-visual -- Screenshot, mobile, and above-the-fold UX analysis 11. seo-plan -- Strategic planning with templates 12. seo-programmatic -- Programmatic SEO analysis and planning 13. seo-competitor-pages -- Competitor comparison page generation 14. seo-hreflang -- Hreflang/i18n SEO audit, cultural profiles, content parity 15. seo-local -- Local SEO (GBP, NAP, citations, reviews, local schema, multi-location) 16. seo-maps -- Maps intelligence (geo-grid, GBP audit, reviews, competitor radius) 17. seo-google -- Google SEO APIs (GSC, PageSpeed, CrUX, Indexing API, GA4) 18. seo-backlinks -- Backlink profile analysis (free: Moz, Bing, CC; premium: DataForSEO) 19. seo-cluster -- SERP-based semantic clustering 20. seo-sxo -- Search Experience Optimization 21. seo-drift -- SEO drift monitoring 22. seo-ecommerce -- E-commerce SEO intelligence 23. seo-firecrawl -- Full-site crawling and site mapping via Firecrawl MCP (extension) 24. seo-dataforseo -- Live SEO data via DataForSEO MCP (extension) 25. seo-image-gen -- AI image generation for SEO assets via Gemini (extension) 26. seo-flow -- FLOW framework integration (Find -> Leverage -> Optimize -> Win, 41 AI prompts, CC BY 4.0)

Subagents

For parallel analysis during audits:

• seo-technical -- Crawlability, indexability, security, CWV
• seo-content -- E-E-A-T, readability, thin content
• seo-schema -- Detection, validation, generation
• seo-sitemap -- Structure, coverage, quality gates
• seo-performance -- Core Web Vitals measurement
• seo-visual -- Screenshots, mobile testing, above-fold
• seo-geo -- AI crawler access, llms.txt, citability, brand mention signals
• seo-local -- GBP signals, NAP consistency, reviews, local schema, industry-specific local factors (conditional: spawned when Local Service detected)
• seo-maps -- Geo-grid rank tracking, GBP audit, review intelligence, competitor radius mapping (conditional: spawned when Local Service detected AND DataForSEO MCP available)
• seo-google -- CWV field data, URL indexation status, organic traffic trends (conditional: spawned when Google API credentials detected)
• seo-backlinks -- Backlink profile data: DA/PA, referring domains, anchor text, toxic links (conditional: spawned when Moz/Bing API keys detected or always for CC domain-level metrics)
• seo-cluster -- Semantic clustering analysis (conditional: content strategy detected)
• seo-sxo -- Page-type mismatch, user stories, persona scoring (always in full audits)
• seo-drift -- Baseline comparison (conditional: drift baseline exists for URL)
• seo-ecommerce -- Product schema, marketplace intel (conditional: e-commerce detected)
• seo-dataforseo -- Live SERP, keyword, backlink, local SEO data (extension, optional)
• seo-image-gen -- SEO image audit and generation plan (extension, optional)
• seo-firecrawl -- Full-site crawl and site mapping (extension, optional; used by audit for URL discovery)

Error Handling

Backlink Quality Scoring Methodology

Toxic Link Indicators (30 Patterns)

Definite Spam (auto-flag)

1. Link from domain with 10,000+ outbound links per page 2. Link from domain with no indexed pages in Google 3. Link from domain registered <30 days ago with 100+ outbound links 4. Exact-match anchor text from 5+ unrelated domains 5. Links from doorway pages (thin content, keyword-stuffed) 6. Links from hacked sites (pharma/casino injections) 7. Links from known link networks (check against known PBN lists) 8. Footer/sidebar site-wide links from unrelated domains 9. Links from auto-generated content (spun articles) 10. Links from domains with manual Google penalties

Likely Spam (manual review)

11. Links from domains with >90% outbound link ratio 12. Foreign-language domains linking to English content (and vice versa) 13. Links from expired/auctioned domains repurposed for link building 14. Links from pages with >50 outbound links 15. Links from sites with no real traffic (parked domains) 16. Reciprocal link patterns across 10+ domains 17. Links from Web 2.0 properties with thin content 18. Links from article directories (EzineArticles, ArticleBase) 19. Links from low-quality guest post networks 20. Links from unrelated niches (e.g., pet site linking to SaaS)

Potentially Problematic (monitor)

21. Links from social bookmarking sites at scale 22. Links from forum profiles (not discussions) 23. Links from press release syndication networks 24. Links from coupon/deal aggregators 25. Links from generic directories (not industry-specific) 26. Links with hidden/invisible anchor text 27. Links from pages with cloaked content 28. Links from sites with thin affiliate content 29. Links from comment sections without editorial context 30. Links from nofollow-only domains (limited SEO value)

Anchor Text Ratio Benchmarks by Industry

Link Velocity Red Flags

Disavow Recommendations

When to disavow:

• Domain has received a manual penalty from Google
• Clear evidence of negative SEO attack
• Toxic link ratio exceeds 10% of total profile
• Specific domains identified as PBN or link farms

When NOT to disavow:

• Low-quality links that Google likely ignores anyway
• Nofollow links (already devalued by Google)
• Links from legitimate but low-authority sites
• Small number of spam links (<2% of profile)

Disavow file format:

# Toxic domains identified by Codex SEO backlink analysis
# Date: YYYY-MM-DD
# Total domains disavowed: X
domain:spamsite1.com
domain:linkfarm2.net
domain:pbn-network3.xyz

<!-- Updated: 2026-02-07 -->

Core Web Vitals Thresholds (February 2026)

Current Metrics

Key Facts

• INP replaced FID (First Input Delay) on March 12, 2024. FID was fully removed from all Chrome tools (CrUX API, PageSpeed Insights, Lighthouse) on September 9, 2024. INP is the sole interactivity metric.
• Evaluation uses the 75th percentile of real user data (field data from CrUX).
• Google assesses at the page level and the origin level.
• Core Web Vitals are a tiebreaker ranking signal: they matter most when content quality is similar between competitors.
• Thresholds unchanged since original definitions: ignore claims of "tightened thresholds" from SEO blogs.
• December 2025 core update appeared to weight mobile CWV more heavily.
• As of October 2025: 57.1% desktop sites and 49.7% mobile sites pass all three CWV.

LCP Subparts (February 2025 CrUX Addition)

LCP can now be broken into diagnostic subparts:

Total LCP = TTFB + Resource Load Delay + Resource Load Time + Element Render Delay

Use this breakdown to identify which phase is causing LCP issues.

Soft Navigations API (Experimental)

Chrome 139+ Origin Trial (July 2025): First step toward measuring CWV in SPAs.

• Addresses the long-standing SPA measurement blind spot
• Currently experimental, no ranking impact yet
• Detects "soft navigations" (URL changes without full page load)
• May affect future SPA CWV measurement

Detection: Check for SPA frameworks (React, Vue, Angular, Svelte) and warn about current CWV measurement limitations.

Measurement Sources

Field Data (Real Users)

• Chrome User Experience Report (CrUX)
• PageSpeed Insights (uses CrUX data)
• Search Console Core Web Vitals report

Lab Data (Simulated)

• Lighthouse
• WebPageTest
• Chrome DevTools

Field data is what Google uses for ranking. Lab data is useful for debugging.

Common Bottlenecks

LCP (Largest Contentful Paint)

• Unoptimized hero images (compress, use WebP/AVIF, add preload)
• Render-blocking CSS/JS (defer, async, critical CSS inlining)
• Slow server response (TTFB >200ms: use edge CDN, caching)
• Third-party script blocking (defer analytics, chat widgets)
• Web font loading delay (use font-display: swap + preload)

INP (Interaction to Next Paint)

• Long JavaScript tasks on main thread (break into smaller tasks <50ms)
• Heavy event handlers (debounce, use requestAnimationFrame)
• Excessive DOM size (>1,500 elements is concerning)
• Third-party scripts hijacking main thread
• Synchronous XHR or localStorage operations
• Layout thrashing (multiple forced reflows)

CLS (Cumulative Layout Shift)

• Images/iframes without width/height dimensions
• Dynamically injected content above existing content
• Web fonts causing layout shift (use font-display: swap + preload)
• Ads/embeds without reserved space
• Late-loading content pushing down the page

Optimization Priority

1. LCP: Most impactful for perceived performance 2. CLS: Most common issue affecting user experience 3. INP: Matters most for interactive applications

Tools

# PageSpeed Insights API
curl "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=URL&key=API_KEY"

# Lighthouse CLI
npx lighthouse URL --output json --output-path report.json

Performance Tooling Updates (2025)

• Lighthouse 13.0 (October 2025): Major audit restructuring with reorganized performance categories and updated scoring weights. Lighthouse is a lab tool (simulated conditions): always cross-reference with CrUX field data for real-world performance.
• CrUX Vis replaced the CrUX Dashboard (November 2025). The old Looker Studio dashboard was deprecated. Use CrUX Vis or the CrUX API directly.
• LCP subparts added to CrUX (February 2025): Time to First Byte (TTFB), resource load delay, resource load time, and element render delay are now available as sub-components of LCP in CrUX data.
• Google Search Console 2025 features (December 2025): AI-powered configuration for automated analysis. Branded vs. non-branded queries filter. Hourly data available in API. Custom chart annotations. Social channels tracking.

Mobile-first indexing is 100% complete as of July 5, 2024. Google now crawls and indexes ALL websites exclusively with the mobile Googlebot user-agent. Ensure your mobile version contains all critical content, structured data, and meta tags.

E-E-A-T Evaluation Framework

Updated per Google Quality Rater Guidelines: September 11, 2025

Plus December 2025 Core Update Implications

Overview

E-E-A-T = Experience, Expertise, Authoritativeness, Trustworthiness

Trustworthiness is the most important factor. It is assessed based on the other three signals plus direct trust indicators.

CRITICAL: December 2025 Core Update

E-E-A-T now applies to ALL competitive queries, not just YMYL.

The December 2025 core update was described as a "watershed moment" that:

• Extended E-E-A-T evaluation to virtually all competitive queries
• Made author attribution standards tighter across all categories
• Penalized anonymous or generic authorship even for non-YMYL content
• Significantly improved AI content quality detection

Impact by industry:

Key takeaway: Even entertainment and lifestyle content now requires demonstrated expertise. Generic content no longer ranks.

YMYL (Your Money or Your Life)

Topics requiring highest E-E-A-T standards (but E-E-A-T now matters everywhere):

• Health and safety
• Financial advice and transactions
• Legal information
• News and current events
• Elections and civic trust (added Sept 2025)
• Democratic processes (added Sept 2025)
• Groups of people (potential for harm)

---

Experience (Weight: 20%)

First-hand knowledge and personal involvement with the topic.

Signals to Check

• [ ] Author has demonstrable first-hand experience with the topic
• [ ] Content includes original photos, screenshots, or data
• [ ] Case studies or real-world examples with specific details
• [ ] Personal process documentation or methodology descriptions
• [ ] Before/after results or outcome data
• [ ] Specific anecdotes that couldn't be fabricated

Scoring

• Strong: Multiple first-hand experience signals, original content
• Moderate: Some personal experience evident
• Weak: Generic information, no personal touch
• None: Clearly AI-generated or scraped content

---

Expertise (Weight: 25%)

Formal qualifications, training, and demonstrated knowledge.

Signals to Check

• [ ] Author credentials relevant to topic (bio, certifications)
• [ ] Technical accuracy and depth appropriate for audience
• [ ] Claims supported by evidence or sources
• [ ] Specialized vocabulary used correctly
• [ ] Up-to-date with current developments in the field
• [ ] Byline with author name and credentials visible

Scoring

• Strong: Verified credentials, deep technical accuracy
• Moderate: Demonstrable knowledge, some credentials
• Weak: Surface-level information, no credentials
• None: Factual errors, misinformation

---

Authoritativeness (Weight: 25%)

Recognition by others as a go-to source.

Signals to Check

• [ ] Site recognized as authority in its niche
• [ ] Author recognized as expert (external citations, speaking, publications)
• [ ] Content cited by other authoritative sources
• [ ] Industry awards, certifications, or accreditations
• [ ] Consistent publication history in the topic area
• [ ] Featured in reputable media outlets
• [ ] Professional affiliations

Scoring

• Strong: Widely recognized authority, cited by others
• Moderate: Growing recognition, some external validation
• Weak: No external recognition
• None: Negative reputation, known for misinformation

---

Trustworthiness (Weight: 30%)

The most important factor, overall reliability and transparency.

Signals to Check

• [ ] Clear contact information (physical address, phone, email)
• [ ] Privacy policy and terms of service
• [ ] HTTPS with valid certificate
• [ ] Transparent about who creates content and why
• [ ] Customer reviews and testimonials
• [ ] Corrections and update history visible
• [ ] No deceptive practices (hidden ads, clickbait)
• [ ] Secure payment processing (for e-commerce)
• [ ] Return/refund policy visible

Scoring

• Strong: Full transparency, verified business, positive reputation
• Moderate: Good trust signals, minor gaps
• Weak: Missing key trust signals
• None: Deceptive practices, scam indicators

---

September 2025 QRG Updates

AI Content Assessment

Raters now formally evaluate whether content appears AI-generated:

• AI content is acceptable if it demonstrates genuine E-E-A-T
• Low-quality AI content (generic, no unique value) is penalized
• The presence of AI-generated content is not inherently penalizing
• What matters: does the content provide unique value regardless of creation method?

Markers of Low-Quality AI Content

• Generic phrasing without specificity
• Lack of original insight or unique perspective
• No first-hand experience signals
• Factual inaccuracies
• Repetitive structure across multiple pages
• No author attribution or expertise signals

New Spam Categories

• Expired domain abuse: Buying expired domains for their backlinks
• Site reputation abuse: Using reputable site to host low-quality content
• Scaled content abuse: Mass-producing content without value

AI Overview Evaluation

Raters assess quality of AI-generated summaries in search results.

RSL 1.0 (Really Simple Licensing)

New machine-readable content licensing standard (December 2025) for AI training:

• Backed by: Reddit, Yahoo, Medium, Quora, Cloudflare, Akamai, Creative Commons
• Allows publishers to specify AI licensing terms
• Augments robots.txt for AI-specific permissions

---

Experience Signals Are Critical Differentiators

The December 2025 update elevated the "Experience" dimension as a key differentiator:

• First-person narrative ("I tested this...", "In my experience...")
• Original photos and screenshots (not stock images)
• Specific examples with verifiable details
• Process documentation showing actual work done

Why: AI can generate expertise-sounding content but cannot fabricate genuine experience.

---

Overall Scoring Guide

---

Improvement Recommendations by Score

0-29 (Critical)

1. Add contact information and about page 2. Establish author identity with credentials 3. Implement HTTPS 4. Remove deceptive elements

30-49 (Major)

1. Add author bios with credentials 2. Include first-hand experience content 3. Get external citations/mentions 4. Add customer testimonials

50-69 (Moderate)

1. Deepen content with original research 2. Build topical authority through content clusters 3. Pursue industry recognition 4. Document processes and methodologies

70-89 (Minor)

1. Maintain freshness with regular updates 2. Expand author presence across platforms 3. Pursue speaking/publication opportunities 4. Add video/multimedia demonstrating expertise

90-100 (Maintenance)

1. Continue publishing high-quality content 2. Monitor and respond to reputation issues 3. Keep credentials and certifications current

Free Backlink Data Sources

Reference for the seo-backlinks skill. Loaded on demand when analyzing backlinks with free sources.

Source Comparison

Confidence Weighting

When merging data from multiple sources, apply confidence weights to each metric:

Composite formula:

weighted_score = Σ(source_score × confidence × factor_weight) / Σ(confidence × factor_weight)

When only Common Crawl is available, cap the maximum health score at 70/100 and note "limited to domain-level metrics" in the report.

Source Details

Moz API (Tier 1)

• Endpoint: https://api.moz.com/jsonrpc (JSON-RPC 2.0)
• Free tier: 2,500 rows/month, 1 request per 10 seconds (verify current limits at https://moz.com/products/api — free tier limits may change)
• Signup: https://moz.com/products/api (credit card required, not charged)
• Data: Domain Authority (0-100), Page Authority, Spam Score (1-17%), link counts,

referring domains, anchor text distribution

• Script: scripts/moz_api.py
• Commands: metrics, domains, anchors, pages
• Blind spots: No link velocity, no toxic link patterns beyond Spam Score,

3-day update lag, smaller index than Ahrefs/Semrush

Bing Webmaster Tools (Tier 2)

• Endpoint: https://ssl.bing.com/webmaster/api.svc/json/
• Free tier: Unlimited for verified sites
• Signup: https://www.bing.com/webmasters (Microsoft account)
• Unique feature: Competitor backlink comparison (no other free tool offers this)
• Data: Inbound links with anchor text, source URL, discovery date
• Script: scripts/bing_webmaster.py
• Commands: links, counts, compare
• Blind spots: Only Bing-indexed pages (~15% of web), verified sites only,

no authority metrics, no spam scoring

Common Crawl Web Graph (Always Available)

• Data source: s3://commoncrawl/projects/hyperlinkgraph/
• Releases: Quarterly (e.g., cc-main-2025-18)
• No auth needed: Public data, free to download
• Data: Domain-level in-degree, PageRank, harmonic centrality, referring domains
• Script: scripts/commoncrawl_graph.py
• Cache: ~/.cache/codex-seo/commoncrawl/ (90-day TTL)
• Blind spots: No anchor text, no page-level data, monthly/quarterly freshness,

domain-level only (e.g., "nytimes.com links to example.com" but not which page)

Verification Crawler (Always Available)

• No auth needed: Uses existing fetch_page.py + parse_html.py
• Data: Binary verification (link exists/lost/moved), anchor text, rel attributes
• Script: scripts/verify_backlinks.py
• Input: JSON file with [{"source_url": "..."}] entries
• Polite crawling: 1-second delay between requests to same domain
• Best for: Checking if known backlinks still exist, monitoring link health

When to Recommend DataForSEO Upgrade

Suggest the paid DataForSEO extension when:

• User needs toxic link detection beyond Moz's basic Spam Score
• User needs competitor gap analysis at scale (Bing only compares verified sites)
• User needs link velocity trends (new/lost links over time)
• User needs real-time data (free sources update monthly at best)
• User manages multiple client sites (free tier limits are per-account)
• User needs disavow file generation with confidence scoring

Data Quality Reality Check

• Commercial tools index 35-45 trillion links across 500M+ referring domains
• Free sources combined capture 20-40% of raw backlink data
• But 60-70% of actionable intelligence since highest-authority links appear in free samples
• For sites with <500 backlinks, free sources can capture 50%+ of the meaningful profile
• Referring domain count matters more than raw backlink count for SEO
• Top 50-100 referring domains capture the majority of link authority

Five Systematic Biases in Free Data

1. Popularity bias: Free tools crawl popular sites more, underrepresenting niche sites 2. Truncation bias: All free tools cap at 100-1,000 links, hiding the long tail 3. Own-site restriction: GSC and Ahrefs Webmaster Tools only work for verified properties 4. Missing quality metrics: Raw CC data lacks authority/toxicity scores 5. Freshness lag: Free sources update monthly at best vs. minutes for commercial

<!-- Updated: 2026-03-23 -->

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 (DA~91, dofollow), Martindale-Hubbell (DA~84, 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

<!-- Updated: 2026-03-23 -->

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)

<!-- Updated: 2026-03-23 -->

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)

<!-- Updated: 2026-03-23 -->

Free Maps APIs for codex-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: codex-seo/1.7.0"

Reverse Geocoding

curl -s "https://nominatim.openstreetmap.org/reverse?lat=40.7128&lon=-74.0060&format=json" \
  -H "User-Agent: codex-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: codex-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

<!-- Updated: 2026-03-23 -->

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)

<!-- Updated: 2026-03-23 -->

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]

Premium Report Standard

Use this as the default brief whenever generating a premium report. Apply it across audit, page, schema, GEO, performance, visual, planning, programmatic, competitor, hreflang, and image deliverables unless the user gives stronger instructions.

Deliverable Policy

• Generate HTML as an internal intermediate artifact when it helps produce the final PDF.
• Treat the PDF as the primary user-facing deliverable by default.
• Do not present, recommend, or link the HTML artifact unless the user explicitly asks for it.
• If HTML is generated, save it to an internal path rather than the main deliverable surface when possible.

Core Requirements

• Include all relevant findings, data points, supporting evidence, and recommendations.
• Embed relevant screenshots inline near the sections they support.
• Add charts or graphs where comparisons clarify the findings.
• Preserve proper chart aspect ratios; never squish or stretch charts.
• Add captions and labels for every screenshot, chart, or visual element.

Layout and Formatting

• Use a clean, professional layout with a title page, table of contents, and clear section headers.
• Use consistent fonts, colors, spacing, and styling throughout.
• Add section dividers and page numbers in the print/PDF output.
• Ensure all text, images, tables, and charts fit within page boundaries.
• Review the final HTML and PDF for clipping, overflow, overlap, or broken pagination before delivery.

Visual Rules

• Use bar, pie, or line charts where metric comparisons or score breakdowns are relevant.
• Size screenshots and visuals to fit within page boundaries with clear margins.
• Keep screenshots readable and proportional.
• Prefer one strong visual per section over cluttered multi-visual layouts.

Content Structure

1. Title page 2. Table of contents 3. Executive summary 4. Findings by section 5. Recommendations / action plan 6. Supporting visuals, charts, and evidence

Adaptation Rules

• Adapt the exact section naming to the report type.
• For HTML and PDF, the content should be the same deliverable in two formats, but the PDF is the default shareable output.
• If some requested visual or chart would be misleading due to weak data, omit it and say why.
• When screenshots are available, use them rather than describing visual issues abstractly.
• When quantitative metrics exist, prefer charts over dense prose lists.

Final Response Rule

• In your final response, reference the PDF deliverable with its absolute filesystem path so it is clickable in Codex CLI.
• Reference the internal HTML artifact only if the user explicitly asks for the HTML file.

Content Quality Gates

Minimum Word Counts by Page Type

---

Location Page Thresholds

Warning Level (30+ pages)

• ⚠️ WARNING at 30+ location pages
• Enforce 60%+ unique content per page
• Content must include:
• Unique local information (landmarks, neighborhoods)
• Location-specific services or offerings
• Local team or staff information
• Genuine customer testimonials from that area

Hard Stop (50+ pages)

• 🛑 HARD STOP at 50+ location pages
• Require explicit user justification
• Must demonstrate:
• Legitimate business presence in each location
• Unique content strategy for each page
• Local signals (Google Business Profile, local reviews)

Why This Matters

Google's doorway page algorithm penalizes programmatic location pages with thin/duplicate content. Signs of doorway pages:

• Only city/state name changed between pages
• No unique local information
• No local business signals
• Keyword-stuffed URLs

---

Safe vs. Risky Programmatic Pages

Safe at Scale ✅

Penalty Risk ❌

---

Title Tag Requirements

Good Examples

• "Emergency Plumbing Services in Austin | ABC Plumbing"
• "How to Fix a Leaky Faucet: Step-by-Step Guide"
• "Enterprise SEO Software | Comprehensive Platform"

Bad Examples

• "Home" (too short, not descriptive)
• "Best Plumbing Services for All Your Plumbing Needs in Austin Texas and Surrounding Areas" (too long)
• "ABC Plumbing - Plumbing - Plumber - Plumbing Services" (keyword stuffing)

---

Meta Description Requirements

---

Image Alt Text Requirements

Good Examples

• "Professional plumber repairing kitchen sink faucet"
• "Red 2024 Toyota Camry sedan front view"
• "Team meeting in modern office conference room"

Bad Examples

• "image.jpg" (filename, not description)
• "plumber plumbing plumber services" (keyword stuffing)
• "Click here" (not descriptive)

---

Internal Linking Guidelines

Anchor Text Rules

• Use descriptive anchor text (not "click here")
• Vary anchor text (don't always use exact match keywords)
• Link to relevant, related content
• Ensure no orphan pages (every page linked from at least one other page)

---

Content Freshness Signals

Required Elements

• Publication date visible (for articles/blogs)
• Last updated date (if significantly revised)
• Changelog for major updates (optional but good)

<!-- Updated: 2026-02-07 -->

Schema.org Types: Status & Recommendations (February 2026)

Schema.org Version: 29.4 (December 8, 2025)

Format Preference

Always use JSON-LD (<script type="application/ld+json">). Google's documentation explicitly recommends JSON-LD over Microdata and RDFa.

AI Search Note: Content with proper schema has ~2.5× higher chance of appearing in AI-generated answers (confirmed by Google and Microsoft, March 2025).

---

Active: Recommend freely

---

Restricted: Only for specific site types

Google severely limited FAQ rich results in August 2023. Only authoritative sources (government, health organizations) receive FAQ rich results.

>

GEO nuance: FAQPage schema still benefits AI/LLM citation visibility (ChatGPT, Perplexity, Google AI Overviews), even without Google rich results.

- Existing FAQPage on commercial site: Flag at Info priority, not Critical. Removal removes GEO citation upside.

- Adding new FAQPage: Not recommended for Google benefit; acceptable if AI search visibility is a priority.

---

Deprecated: Never recommend

---

Recent Additions (2024-2026)

E-commerce Requirements (Updated)

Note: Content API for Shopping sunsets August 18, 2026. Migrate to Merchant API.

---

Validation Checklist

For any schema block, verify:

1. ✅ @context is "https://schema.org" (not http) 2. ✅ @type is a valid, non-deprecated type 3. ✅ All required properties are present 4. ✅ Property values match expected data types 5. ✅ No placeholder text (e.g., "[Business Name]") 6. ✅ URLs are absolute, not relative 7. ✅ Dates are in ISO 8601 format 8. ✅ Images have valid URLs

Testing Tools

• Google Rich Results Test
• Schema.org Validator

Shared Data Cache Reference

This reference defines the shared .seo-cache/ system used across codex-seo skills. All cache files are optional performance optimizations. If a cache is missing, stale, corrupt, or unreadable, the skill proceeds with normal gathering.

Core Rules

• Cache location: .seo-cache/
• Reference this file from each skill Step 0 block
• No cache file is required for a skill to run
• Corrupt JSON should be treated as missing cache
• Permission errors should be skipped silently
• Users can force fresh gathering by saying refresh or re-run
• Cache freshness does not auto-expire; each file should include an analysis timestamp
• Never commit .seo-cache/ contents

Directory Layout

.seo-cache/
  site-meta.json
  plan.json
  audit-scores.json
  sitemap.json
  hreflang.json
  programmatic.json
  competitors.json
  backlinks.json
  google.json
  local.json
  maps.json
  cluster.json
  sxo.json
  drift.json
  ecommerce.json
  flow.json
  dataforseo.json
  firecrawl.json
  pages/
    {url-slug}/
      technical.json
      content.json
      schema.json
      geo.json
      performance.json
      visual.json
      images.json
      page-analysis.json

URL Slug Resolution Algorithm

Use this algorithm for all page-level cache paths:

1. Parse the URL and extract the path component 2. Strip protocol, domain, query string, fragment, and trailing slash 3. If the path is empty or /, use homepage 4. Replace / with -- 5. Strip leading and trailing hyphens 6. Lowercase the result 7. Truncate to 80 characters; if possible, break at the last -- before the limit

Examples:

• https://example.com → homepage
• https://example.com/blog/seo-guide → blog--seo-guide
• https://example.com/about/team → about--team

Freshness Rules

• No automatic expiry window
• Cache represents the state at analysis time
• Each cache file should include analyzed_at
• If the user asks to refresh or re-run, ignore cache reads and overwrite on write
• If downstream cache context conflicts with live findings, prefer fresh evidence and note the mismatch

Step 0 Template

Use this at the beginning of each skill process or gather section:

**Step 0 — Check shared data cache:**

Before gathering, check `.seo-cache/` for cached data from other skills.
Reference: `seo/references/shared-data-cache.md` for schemas and dependency map.

[List specific cache files this skill checks]

- If found: parse and use the data (note "Using cached [X] from [date]")
- If missing: proceed without it (note "No cached [X] found, gathering fresh")
- If the user says "refresh" or "re-run": ignore cache entirely

Cache Write Template

Use this at the end of each skill delivery section:

**Write to shared data cache:**

After completing all work, write results to `.seo-cache/`.

mkdir -p .seo-cache/pages/{url-slug} mkdir -p .seo-cache

Write the JSON file per the schema in `seo/references/shared-data-cache.md`.
Add `.seo-cache/` to `.gitignore` if not already present:

grep -qxF '.seo-cache/' .gitignore 2>/dev/null || echo '.seo-cache/' >> .gitignore

Error Handling Rules

• Missing cache file: continue normally
• Invalid JSON: treat as missing cache
• Permission denied: skip cache silently
• Partial cache payloads: use only clearly valid fields
• Unknown fields: ignore unless the active skill explicitly needs them

Dependency Map

JSON Schemas

Each schema below is intentionally lightweight and additive. Skills may include extra fields when useful, but should preserve the documented top-level structure.

1. site-meta.json

{
  "cache_type": "site-meta",
  "analyzed_at": "2026-01-15T12:34:56Z",
  "domain": "example.com",
  "homepage_url": "https://example.com/",
  "business_type": "local service business",
  "industry": "home services",
  "language": "en",
  "country": "US",
  "notes": []
}

2. audit-scores.json

{
  "cache_type": "audit-scores",
  "analyzed_at": "2026-01-15T12:34:56Z",
  "domain": "example.com",
  "overall_score": 78,
  "category_scores": {
    "technical": 74,
    "content": 80,
    "schema": 71,
    "sitemap": 83,
    "geo": 79
  },
  "priority_issues": [
    {
      "severity": "high",
      "issue": "Missing Organization schema on homepage"
    }
  ]
}

3. plan.json

{
  "cache_type": "plan",
  "analyzed_at": "2026-01-15T12:34:56Z",
  "domain": "example.com",
  "goals": ["Increase qualified organic traffic"],
  "priority_tracks": ["technical cleanup", "location pages"],
  "target_pages": ["/services/roof-repair"],
  "competitors": ["competitor-a.com", "competitor-b.com"]
}

4. sitemap.json

{
  "cache_type": "sitemap",
  "analyzed_at": "2026-01-15T12:34:56Z",
  "domain": "example.com",
  "sitemap_urls": ["https://example.com/sitemap.xml"],
  "coverage_summary": {
    "indexed_candidates": 120,
    "missing_key_pages": 3
  },
  "recommendations": ["Add location pages to sitemap"]
}

5. hreflang.json

{
  "cache_type": "hreflang",
  "analyzed_at": "2026-01-15T12:34:56Z",
  "domain": "example.com",
  "language_targets": ["en-us", "es-us"],
  "implementation_status": "missing",
  "issues": ["No hreflang annotations detected"]
}

6. programmatic.json

{
  "cache_type": "programmatic",
  "analyzed_at": "2026-01-15T12:34:56Z",
  "domain": "example.com",
  "templates": ["city-service landing page"],
  "data_sources": ["internal inventory"],
  "risks": ["thin near-duplicate location pages"]
}

7. competitors.json

{
  "cache_type": "competitors",
  "analyzed_at": "2026-01-15T12:34:56Z",
  "domain": "example.com",
  "competitors": [
    {
      "domain": "competitor-a.com",
      "reason": "Overlaps on core service terms"
    }
  ],
  "content_gaps": ["commercial intent comparison pages"]
}

8. pages/{slug}/technical.json

{
  "cache_type": "technical",
  "analyzed_at": "2026-01-15T12:34:56Z",
  "url": "https://example.com/services/roof-repair",
  "url_slug": "services--roof-repair",
  "score": 76,
  "findings": {
    "indexability": "indexable",
    "canonicals": "self-referential",
    "mobile": "pass",
    "cwv": "needs improvement"
  },
  "issues": ["Render-blocking CSS on mobile"]
}

9. pages/{slug}/content.json

{
  "cache_type": "content",
  "analyzed_at": "2026-01-15T12:34:56Z",
  "url": "https://example.com/services/roof-repair",
  "url_slug": "services--roof-repair",
  "score": 81,
  "eeat_summary": "Strong expertise signals, limited first-hand proof",
  "ai_citation_readiness": "moderate",
  "issues": ["Missing author or reviewer attribution"]
}

10. pages/{slug}/schema.json

{
  "cache_type": "schema",
  "analyzed_at": "2026-01-15T12:34:56Z",
  "url": "https://example.com/services/roof-repair",
  "url_slug": "services--roof-repair",
  "score": 70,
  "detected_types": ["Service", "FAQPage"],
  "validation": "warnings",
  "issues": ["Missing provider details on Service schema"]
}

11. pages/{slug}/geo.json

{
  "cache_type": "geo",
  "analyzed_at": "2026-01-15T12:34:56Z",
  "url": "https://example.com/services/roof-repair",
  "url_slug": "services--roof-repair",
  "score": 73,
  "ai_crawler_access": "allowed",
  "local_signals": ["city mentioned in title tag"],
  "issues": ["No llms.txt detected"]
}

12. pages/{slug}/performance.json

{
  "cache_type": "performance",
  "analyzed_at": "2026-01-15T12:34:56Z",
  "url": "https://example.com/services/roof-repair",
  "url_slug": "services--roof-repair",
  "score": 68,
  "core_web_vitals": {
    "lcp": "3.1s",
    "inp": "240ms",
    "cls": "0.08"
  },
  "issues": ["Large hero image delays LCP"]
}

13. pages/{slug}/visual.json

{
  "cache_type": "visual",
  "analyzed_at": "2026-01-15T12:34:56Z",
  "url": "https://example.com/services/roof-repair",
  "url_slug": "services--roof-repair",
  "score": 75,
  "layout_summary": "Clear hierarchy with weak CTA contrast",
  "issues": ["Primary CTA blends into hero background"]
}

14. pages/{slug}/images.json

{
  "cache_type": "images",
  "analyzed_at": "2026-01-15T12:34:56Z",
  "url": "https://example.com/services/roof-repair",
  "url_slug": "services--roof-repair",
  "score": 72,
  "image_summary": {
    "missing_alt": 4,
    "oversized_images": 2
  },
  "issues": ["Four decorative images missing explicit empty alt text"]
}

15. pages/{slug}/page-analysis.json

{
  "cache_type": "page-analysis",
  "analyzed_at": "2026-01-15T12:34:56Z",
  "url": "https://example.com/services/roof-repair",
  "url_slug": "services--roof-repair",
  "summary_score": 79,
  "inputs_used": ["schema", "content"],
  "top_actions": ["Add reviewer credentials", "Expand FAQ coverage"]
}

16. Root-level specialist summaries

Use this shared shape for backlinks.json, google.json, local.json, maps.json, cluster.json, sxo.json, drift.json, ecommerce.json, flow.json, dataforseo.json, firecrawl.json, and image-gen.json:

{
  "cache_type": "backlinks",
  "analyzed_at": "2026-01-15T12:34:56Z",
  "domain": "example.com",
  "url": "https://example.com/",
  "score": 72,
  "data_sources": ["Common Crawl"],
  "findings": {
    "summary": "Domain-level backlink data available; API credentials missing."
  },
  "issues": ["No Moz or Bing credentials configured"],
  "recommendations": ["Configure backlink API credentials for higher confidence"],
  "limitations": ["Free-tier data is directional, not exhaustive"]
}

Set cache_type to the skill family (google, local, maps, cluster, sxo, drift, ecommerce, flow, dataforseo, firecrawl, or image-gen). If a workflow is unavailable because an MCP server or credential is missing, still write a summary when useful with status: "setup_required" and clear limitations.