Analytics

{
  "summary": {
    "total_audits": 45,
    "completed_audits": 38,
    "running_audits": 4,
    "failed_audits": 3,
    "success_rate": 84.44
  },
  "metrics": {
    "unique_domains": 12,
    "total_issues": 487,
    "average_issues_per_audit": 12.8
  }
}

GET /api/v1/analytics/audit/{audit_id}

{
  "audit_id": 123,
  "domain": "example.com",
  "total_pages": 45,
  "is_ymyl": false,
  "category": "Software",
  "issues": {
    "critical": 3,
    "high": 8,
    "medium": 15,
    "low": 22,
    "total": 48
  },
  "scores": {
    "h1_score": 8.2,
    "structure_score": 7.5,
    "content_score": 6.8,
    "eeat_score": 7.0,
    "schema_score": 5.5,
    "overall_score": 7.0
  },
  "pages": [
    {
      "url": "https://example.com/products",
      "path": "/products",
      "overall_score": 7.5,
      "issues": {
        "critical": 0,
        "high": 2,
        "medium": 3,
        "low": 5
      }
    }
  ]
}

interface IssueDistribution {
  critical: number;  // Requires immediate action
  high: number;      // Important optimization
  medium: number;    // Recommended improvement
  low: number;       // Nice-to-have enhancement
}

GET /api/v1/analytics/competitors/{audit_id}

{
  "audit_id": 123,
  "total_competitors": 5,
  "your_geo_score": 7.2,
  "average_competitor_score": 6.8,
  "position": "Por encima del promedio",
  "competitors": [
    {
      "domain": "competitor1.com",
      "url": "https://competitor1.com",
      "geo_score": 8.5
    },
    {
      "domain": "competitor2.com",
      "url": "https://competitor2.com",
      "geo_score": 7.2
    }
  ],
  "identified_gaps": [
    "Schema faltante: Product, FAQPage",
    "Lower citation rate in AI responses",
    "Missing author credentials on articles"
  ]
}

interface KeywordMetrics {
  keyword: string;
  volume: number;           // Monthly search volume
  difficulty: number;       // 0-100 difficulty score
  position: number;         // Current ranking (1-100+)
  position_change: number;  // Change from last check
  url: string;             // Ranking page URL
  last_checked: string;    // ISO timestamp
}

{
  "rank_distribution": {
    "top_3": 5,      // Page 1, positions 1-3
    "top_10": 12,    // Page 1, positions 1-10
    "top_20": 18,    // Positions 11-20
    "top_50": 25,    // Positions 21-50
    "beyond_50": 10  // Position 51+
  },
  "trend": "stable",  // "improving", "stable", "declining"
  "average_position": 15.3
}

interface BacklinkProfile {
  total_backlinks: number;
  referring_domains: number;
  dofollow_links: number;
  nofollow_links: number;
  average_domain_authority: number;
  top_backlinks: TopBacklink[];
}

interface TopBacklink {
  source_url: string;
  source_domain: string;
  domain_authority: number;  // 0-100
  target_url: string;
  anchor_text: string;
  link_type: 'dofollow' | 'nofollow';
  first_seen: string;
}

{
  "llm_visibility": {
    "total_queries_tested": 50,
    "total_mentions": 18,
    "citation_rate": 36.0,
    "by_llm": {
      "chatgpt": {
        "mentions": 8,
        "citation_rate": 40.0,
        "average_position": 2.3
      },
      "gemini": {
        "mentions": 5,
        "citation_rate": 25.0,
        "average_position": 3.1
      },
      "perplexity": {
        "mentions": 5,
        "citation_rate": 25.0,
        "average_position": 2.8
      }
    },
    "sentiment_breakdown": {
      "positive": 12,
      "neutral": 5,
      "negative": 1
    }
  }
}

interface CitationTrend {
  month: string;           // "March", "April", etc.
  year: number;
  citations: number;       // Total citations
  queries_tracked: number; // Queries tested
  citation_rate: number;   // Percentage
  top_queries: string[];   // Queries where cited
}

GET /api/v1/analytics/issues/{audit_id}

{
  "audit_id": 123,
  "total_issues": 48,
  "by_priority": {
    "CRITICAL": [
      {
        "page_path": "/products/widget",
        "issue_code": "MISSING_H1",
        "description": "Page missing H1 heading",
        "suggestion": "Add descriptive H1 with primary keyword"
      }
    ],
    "HIGH": [
      {
        "page_path": "/blog/article",
        "issue_code": "NO_AUTHOR_INFO",
        "description": "Author information not found",
        "suggestion": "Add author bio with credentials"
      }
    ],
    "MEDIUM": [...],
    "LOW": [...]
  }
}

interface WebVitals {
  lcp: {
    mobile: number;   // Largest Contentful Paint (seconds)
    desktop: number;
    status: 'good' | 'needs-improvement' | 'poor';
  };
  inp: {
    mobile: number;   // Interaction to Next Paint (ms)
    desktop: number;
    status: 'good' | 'needs-improvement' | 'poor';
  };
  cls: {
    mobile: number;   // Cumulative Layout Shift
    desktop: number;
    status: 'good' | 'needs-improvement' | 'poor';
  };
  performance_score: {
    mobile: number;   // 0-100
    desktop: number;
  };
}

{
  "opportunities": [
    {
      "title": "Defer offscreen images",
      "estimated_savings": "1.5s",
      "impact": "High"
    },
    {
      "title": "Remove unused JavaScript",
      "estimated_savings": "0.8s",
      "impact": "Medium"
    },
    {
      "title": "Optimize web fonts",
      "estimated_savings": "0.3s",
      "impact": "Low"
    }
  ]
}

# Main dashboard
GET /api/v1/analytics/dashboard

# Audit analytics
GET /api/v1/analytics/audit/{audit_id}

# Competitor analysis
GET /api/v1/analytics/competitors/{audit_id}

# Issues breakdown
GET /api/v1/analytics/issues/{audit_id}

# Complete GEO overview
GET /api/v1/geo/dashboard/{audit_id}