SEO Audit

GET

Perform comprehensive SEO analysis with 50+ best practices across metadata, content, technical, accessibility, and performance categories. Get actionable recommendations with fix priorities, weighted scores, and Core Web Vitals performance metrics.

Endpoint

GET /seo-audit

Authentication

This endpoint requires API key authentication. Include your API key in the X-API-Key header:

X-API-Key: YOUR_API_KEY

Query Parameters

Parameter	Type	Required	Description
url	string	Yes	Target URL to audit
device	string	No	Device type: mobile or desktop (default: mobile)
vitals	string	No	Web Vitals mode: synthetic or none (default: synthetic)
compare	boolean	No	Compare with previous audit to show score deltas (default: false)
fields	string	No	Comma-separated field groups to include

Field Groups

Use the fields parameter to filter the response and only get the data you need:

scoring

Overall score and category scores

issues

Detailed list of SEO issues with recommendations

metrics

Quantitative metrics (title length, word count, etc.)

indexability

Indexability status and checks

http

HTTP response information

web_vitals

Estimated Core Web Vitals

structured_data

Schema.org validation

content

Content analysis (headings, language, reading time)

i18n

Internationalization (hreflang tags)

media

Image and media validation

summary

High-level summary for dashboards

context

Audit context (settings, timings)

diagnostics

DOM parsing diagnostics and technical details

diff

Comparison with previous audit (requires compare=true)

all

All available fields (default)

SEO Score Grades

Score	Grade	Description
90-100	A	Excellent SEO
80-89	B	Good SEO
70-79	C	Fair SEO
60-69	D	Poor SEO
0-59	F	Critical issues

Example Request

curl "https://api.webpeek.dev/seo-audit?url=https://example.com&device=mobile"

Example Response

{
  "schema_version": "2025.11.0",
  "url": "https://www.webpeek.dev/",
  "scoring": {
    "schema_version": "1.0.0",
    "rule_version": "2025.11.0",
    "version": "2025.11.0",
    "device": "mobile",
    "weights": {
      "metadata": 0.25,
      "content": 0.25,
      "technical": 0.20,
      "accessibility": 0.15,
      "performance": 0.15
    },
    "overall": 93,
    "grade": "A",
    "by_category": {
      "metadata": 80,
      "content": 100,
      "technical": 95,
      "accessibility": 100,
      "performance": 90
    },
    "category_status": {
      "performance": "heuristic"
    },
    "deductions": [
      {
        "category": "metadata",
        "reason": "Title is too long (63 characters)",
        "points": 10,
        "rule_id": "META_TITLE_TOO_LONG"
      }
    ],
    "scoring_explainer": {
      "method": "weighted_categories",
      "category_deductions": {
        "metadata": 20,
        "content": 0,
        "technical": 5,
        "accessibility": 0,
        "performance": 10
      }
    }
  },
  "issues": [...],
  "metrics": {...},
  "indexability": {...},
  "http": {...},
  "web_vitals": {...},
  "content": {...},
  "i18n": {...},
  "media": {...},
  "summary": {
    "passed": [
      "No critical issues found",
      "HTTPS enabled",
      "Title tag present",
      "Meta description present",
      "Viewport meta tag present",
      "All images have alt attributes"
    ],
    "top_fixes": [
      {
        "id": "meta-title-too-long",
        "impact": "medium",
        "why_it_matters": "Long titles get truncated in search results (after ~60 chars), reducing click-through rates and user clarity about page content.",
        "quick_fix": "Trim title to ≤60 chars to avoid SERP truncation.",
        "fixable": true
      }
    ],
    "critical_count": 0,
    "warning_count": 3,
    "info_count": 1,
    "rules": {
      "total": 36,
      "passed": 32,
      "failed": 4
    }
  },
  "context": {...},
  "diagnostics": {...},
  "technologies": [...],
  "diff": null,
  "scannedAt": "2025-11-06T19:25:26.426Z"
}

Detailed Field Group Examples

Here are detailed examples of what each field group returns:

Metrics Field Group

Returns quantitative SEO metrics including title length, description length, heading counts, link counts, and more.

{
  "metrics": {
    "title_length": 63,
    "description_length": 219,
    "headings": {
      "h1": 1,
      "h2": 7,
      "h3": 23,
      "h4": 3,
      "h5": 0,
      "h6": 0,
      "total": 34
    },
    "links": {
      "internal": 17,
      "external": 0,
      "broken": 0,
      "total": 17
    },
    "images": {
      "total": 5,
      "with_alt": 5,
      "without_alt": 0
    },
    "word_count": 544,
    "body_text_bytes": 4705
  }
}

Issues Field Group

Returns detailed list of SEO issues with severity, category, recommendations, and priority.

{
  "issues": [
    {
      "id": "meta-title-too-long",
      "code": "META_TITLE_TOO_LONG",
      "severity": "warning",
      "priority": 2,
      "category": "metadata",
      "message": "Title is too long (63 characters)",
      "recommendation": "Trim title to ≤60 chars to avoid SERP truncation.",
      "selector": "head > title",
      "snippet": "<title>Web Intelligence API - Metadata, SEO Audits, Screenshots & M...</title>",
      "estimated_effort": "minutes",
      "docs_url": "https://docs.webpeek.dev/rules/meta-title-too-long",
      "impact": "medium",
      "why_it_matters": "Long titles get truncated in search results (after ~60 chars), reducing click-through rates and user clarity about page content.",
      "fixable": true,
      "source_rule": "META_TITLE_TOO_LONG"
    },
    {
      "id": "web-vitals-inp-needs-improvement",
      "code": "WEB_VITALS_INP_NEEDS_IMPROVEMENT",
      "severity": "warning",
      "priority": 2,
      "category": "performance",
      "message": "Interaction to Next Paint needs improvement (292ms)",
      "recommendation": "Optimize JavaScript to reduce input delay and improve responsiveness.",
      "selector": "n/a",
      "snippet": "<!-- Defer scripts -->\n<script src=\"...\" defer></script>",
      "estimated_effort": "hours",
      "docs_url": "https://docs.webpeek.dev/rules/web-vitals-inp-needs-improvement",
      "impact": "medium",
      "why_it_matters": "INP between 200-500ms can cause noticeable delays. Users expect instant feedback (<200ms) when interacting with UI elements.",
      "fixable": false,
      "evidence": [
        {
          "selector": null,
          "value": "INP: 292ms"
        }
      ],
      "source_rule": "WEB_VITALS_INP_NEEDS_IMPROVEMENT",
      "thresholds": {
        "good": "<=200ms",
        "needs_improvement": "200–500ms",
        "poor": ">500ms"
      }
    }
  ]
}

Indexability Field Group

Returns indexability status including robots meta tags, canonical URLs, and indexability checks.

{
  "indexability": {
    "robots_txt": {
      "url": "https://www.webpeek.dev/robots.txt",
      "allow": true,
      "matched_rule": "Allow: /",
      "crawl_delay": null
    },
    "meta_robots": "index, follow",
    "x_robots_tag": null,
    "canonical": {
      "href": "https://webpeek.dev/",
      "href_normalized": "https://webpeek.dev",
      "is_self_canonical": false,
      "matches_canonical": false,
      "resolves": true,
      "status": 200
    },
    "sitemaps": [
      "https://webpeek.dev/sitemap.xml"
    ],
    "is_indexable": true,
    "indexed_like_google": false,
    "reason": "Page canonicalizes to https://webpeek.dev/",
    "robots_effective": "index, follow",
    "effective_status": "canonicalized"
  }
}

Web Vitals Field Group

Returns estimated Core Web Vitals metrics with confidence levels.

{
  "web_vitals": {
    "source": "synthetic",
    "confidence": "heuristic",
    "lcp_ms": 352,
    "inp_ms": 292,
    "cls": 0,
    "fcp_ms": 152,
    "ttfb_ms": 152,
    "raw": {
      "lcp_ms": 352,
      "inp_ms": 292,
      "cls": 0,
      "ttfb_ms": 152
    },
    "opportunities": [
      {
        "id": "DEFER_SCRIPTS",
        "description": "Defer or async non-critical JavaScript",
        "potential_saving_ms": 3700,
        "items": [
          "37 render-blocking scripts"
        ]
      }
    ],
    "web_vitals_score": 80,
    "score_breakdown": {
      "lcp": 93,
      "inp": 35,
      "cls": 100,
      "ttfb": 91,
      "scale": "0–100 (higher is better)"
    }
  }
}

Content Field Group

Returns content analysis including heading structure, language, word count, and reading time.

{
  "content": {
    "language": "en",
    "word_count": 544,
    "read_time_min": 3,
    "has_schema": false,
    "headings": [
      {
        "tag": "h1",
        "text": "Peek inside any website",
        "level": 1
      },
      {
        "tag": "h2",
        "text": "Everything in one API",
        "level": 2
      },
      {
        "tag": "h3",
        "text": "Metadata & Previews",
        "level": 3
      },
      {
        "tag": "h3",
        "text": "SEO Audit",
        "level": 3
      }
    ]
  }
}

Structured Data Field Group

Returns Schema.org structured data validation and found schemas.

{
  "structured_data": {
    "valid": true,
    "errors": [],
    "warnings": [],
    "schemas_found": [
      {
        "@type": "Organization",
        "name": "Example Company"
      },
      {
        "@type": "WebSite",
        "name": "Example Company"
      }
    ],
    "count": 2
  }
}

I18n Field Group

Returns internationalization information including hreflang tags.

{
  "i18n": {
    "hreflang": [],
    "duplicates_or_conflicts": false
  }
}

Issue Severity Levels

Error

Critical Issues

Major problems that significantly impact SEO and should be fixed immediately. Examples: missing title tags, no H1 heading, blocked by robots.txt.

Warning

Important Issues

Issues that could hurt SEO performance and should be addressed soon. Examples: long title tags, missing alt text, duplicate headings.

Info

Optimization Tips

Suggestions for improvement that can enhance SEO over time. Examples: add Schema.org markup, optimize images, improve internal linking.

Use Cases

SEO audit tools and dashboards
Website monitoring and alerts
Client SEO reporting
Pre-launch SEO checklists
Competitor SEO analysis
Automated SEO testing in CI/CD

Code Examples

Here's how to use the SEO audit endpoint in different languages:

JavaScript / Node.js

seo-audit.js

async function auditSEO(url, device = 'mobile') {
  const response = await fetch(
    `https://api.webpeek.dev/seo-audit?url=${encodeURIComponent(url)}&device=${device}`
  );

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const audit = await response.json();
  return audit;
}

// Example usage
const audit = await auditSEO('https://example.com', 'mobile');
console.log(`SEO Score: ${audit.scoring.overall}/100 (Grade: ${audit.scoring.grade})`);
console.log(`Issues found: ${audit.issues.length}`);

// Display critical issues
audit.issues
  .filter(issue => issue.severity === 'error')
  .forEach(issue => {
    console.log(`[ERROR] ${issue.message}`);
    console.log(`  Fix: ${issue.recommendation}`);
  });

Python

seo_audit.py

import requests

def audit_seo(url, device='mobile'):
    response = requests.get(
        'https://api.webpeek.dev/seo-audit',
        params={
            'url': url,
            'device': device
        }
    )
    response.raise_for_status()
    return response.json()

# Example usage
audit = audit_seo('https://example.com', 'mobile')
print(f"SEO Score: {audit['scoring']['overall']}/100 (Grade: {audit['scoring']['grade']})")
print(f"Issues found: {len(audit['issues'])}")

# Display critical issues
for issue in audit['issues']:
    if issue['severity'] == 'error':
        print(f"[ERROR] {issue['message']}")
        print(f"  Fix: {issue['recommendation']}")

PHP

seo-audit.php

<?php

function auditSEO($url, $device = 'mobile') {
    $apiUrl = 'https://api.webpeek.dev/seo-audit?' . http_build_query([
        'url' => $url,
        'device' => $device
    ]);

    $response = file_get_contents($apiUrl);
    $audit = json_decode($response, true);

    if ($audit === null) {
        throw new Exception('Failed to decode JSON response');
    }

    return $audit;
}

// Example usage
$audit = auditSEO('https://example.com', 'mobile');
echo "SEO Score: {$audit['scoring']['overall']}/100 (Grade: {$audit['scoring']['grade']})\n";
echo "Issues found: " . count($audit['issues']) . "\n";

// Display critical issues
foreach ($audit['issues'] as $issue) {
    if ($issue['severity'] === 'error') {
        echo "[ERROR] {$issue['message']}\n";
        echo "  Fix: {$issue['recommendation']}\n";
    }
}
?>

Best Practices

Run Audits Regularly

Schedule automated audits weekly or monthly to catch SEO issues early. Monitor score trends over time to measure improvement.

Prioritize Critical Issues

Focus on fixing error-level issues first, as these have the biggest impact on SEO. Use the priority field to determine order of fixes.

Test Mobile and Desktop

Run audits for both mobile and desktop devices, as SEO requirements can differ. Mobile-first indexing makes mobile audits especially important.

Use Field Filtering

Request only the fields you need to reduce response size and improve performance. For dashboards, use fields=scoring,summary.

Track Historical Data

Store audit results over time to track SEO improvements and identify recurring issues. Compare scores to measure the impact of fixes.