API Documentation

Integrate SEO analysis directly into your applications, dashboards, or automation pipelines. The REST API gives you full access to the same 310+ check audit engine used by the web tool.

RESTful JSON API Streaming support API key auth

Authentication

All API requests require an API key. Include it as a query parameter or in the request header:

GET /api/audit/123?api_key=YOUR_API_KEY
— or —
Authorization: Bearer YOUR_API_KEY

Find your API key in Account Settings. You can regenerate it at any time.

Rate Limits

Plan	Audits/Day	Comparisons/Day	Site Crawl Pages
Anonymous	2	0	10
Free (registered)	5	1	50
Pro	Unlimited	Unlimited	Unlimited

Endpoints

POST /api/audit Run an SEO audit

Request Body JSON

{
  "url": "https://example.com",
  "mode": "single",     // "single" or "site"
  "maxPages": 50        // For site mode only
}

Parameters

Field	Type	Required	Description
`url`	string	Yes	The URL to audit (must include protocol)
`mode`	string	No	`single` (default) or `site` (whole site crawl)
`maxPages`	integer	No	Max pages to crawl (site mode only, subject to plan limits)

Response 200 OK

All audits run in the background. Poll /api/audit-status?id=<auditId> for progress and results.

{
  "success": true,
  "data": {
    "mode": "single",
    "background": true,
    "auditId": 123,
    "url": "https://example.com",
    "message": "Audit started in background",
    "statusUrl": "/api/audit-status?id=123"
  }
}

Status Polling Response (complete) 200 OK

{
  "success": true,
  "data": {
    "status": "complete",
    "auditId": 123,
    "url": "https://example.com",
    "score": 78,
    "title": "Example Domain",
    "mode": "single",
    "expiresAt": "2026-02-25 15:30:00",
    "meta": {
      "httpStatus": 200,
      "responseTimeMs": 450,
      "htmlSize": 45230,
      "wordCount": 320,
      "isHttps": true,
      "hasCanonical": true,
      "isNoindex": false,
      "internalLinks": 15,
      "externalLinks": 4,
      "imagesMissingAlt": 2
    },
    "issues": { ... },
    "issuesSummary": {
      "PASS": 180, "INFO": 30,
      "WARN": 20, "FAIL": 8,
      "total": 238
    }
  }
}

GET /api/audit/{id} Retrieve an audit result

Path Parameters

Parameter	Type	Description
`id`	integer	The audit ID returned from the POST request

Response 200 OK

Returns the same structure as the POST response. Audit results expire after 15 minutes.

POST /api/compare Compare two URLs

Request Body JSON

{
  "url1": "https://yoursite.com",
  "url2": "https://competitor.com"
}

Response

Returns a detailed comparison with scores, issues, and category-by-category breakdown for both URLs.

GET /api/export Export audit as PDF or CSV

Query Parameters

Parameter	Type	Description
`id`	integer	The audit ID to export
`format`	string	`pdf` (default) or `csv`

Returns the file as a download. For site audits, includes all crawled pages.

GET /api/history Get audit history

Returns a list of recent audits for the authenticated user. Requires API key.

GET /api/status API health check

Response

{
  "success": true,
  "data": {
    "status": "ok",
    "version": "2.1.1"
  }
}

Error Responses

All errors follow this format:

{
  "success": false,
  "error": "Description of what went wrong"
}

HTTP Status Codes

Code	Meaning
`200`	Success
`400`	Bad request (missing/invalid parameters)
`401`	Unauthorized (invalid API key)
`403`	Forbidden (insufficient permissions)
`404`	Resource not found
`422`	Unprocessable (could not fetch URL)
`429`	Rate limit exceeded
`500`	Internal server error

Background Processing & Polling

All audits run asynchronously in the background. Poll the statusUrl returned in the initial response to track progress:

// Progress updates:
{"success":true,"data":{"status":"running","step":"links","message":"Checking links..."}}
{"success":true,"data":{"status":"running","step":"pagespeed","message":"Running PageSpeed analysis..."}}

// Final result:
{"success":true,"data":{"status":"complete","auditId":123,"score":78,"mode":"single",...}}

Poll every 2 seconds. The final response will have "status": "complete" or "status": "failed".

Code Examples

cURL

curl -X POST https://localseoaudittool.com/api/audit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"url": "https://example.com"}'

JavaScript (Fetch)

const response = await fetch('https://localseoaudittool.com/api/audit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({ url: 'https://example.com' })
});
const data = await response.json();
console.log(data.data.score); // e.g., 78

Python (requests)

import requests

response = requests.post(
    'https://localseoaudittool.com/api/audit',
    json={'url': 'https://example.com'},
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
result = response.json()
print(f"SEO Score: {result['data']['score']}")