API Documentation

Public REST API for accessing university scores and rankings data.

Base URL: /api/v1/ — All responses return JSON. No authentication required.

OpenAPI Spec

GET /api/v1/universities

List all scanned universities with pagination.

Parameters: page (default: 1), limit (default: 20, max: 100), search (filter by name/domain), country (filter by country), sort (name|domain|country|created_at), order (asc|desc)

Code Examples

curl -s 'https://unirankscanner.cyber-aab.com/api/v1/universities?page=1&limit=20'

const res = await fetch('/api/v1/universities?page=1&limit=20');
const data = await res.json();
console.log(data);

import requests

res = requests.get('http://localhost/api/v1/universities',
                   params={'page': 1, 'limit': 20})
data = res.json()
print(data)

Response Schema

{
    "success": true,
    "data": [
        {
            "id": 1,
            "domain": "example.edu",
            "name": "Example University",
            "country": "US",
            "created_at": "2025-01-10 08:00:00"
        }
    ],
    "meta": {
        "page": 1,
        "limit": 20,
        "total": 45
    }
}

GET /api/v1/universities/{id}

Get details for a specific university.

Parameters: id (required)

Code Examples

curl -s 'https://unirankscanner.cyber-aab.com/api/v1/universities/1'

const res = await fetch('/api/v1/universities/1');
const data = await res.json();
console.log(data);

import requests

res = requests.get('http://localhost/api/v1/universities/1')
data = res.json()
print(data)

Response Schema

{
    "success": true,
    "data": {
        "id": 1,
        "domain": "example.edu",
        "name": "Example University",
        "country": "US",
        "created_at": "2025-01-10 08:00:00",
        "scan_count": 3
    }
}

GET /api/v1/universities/{id}/scores

Get all computed scores for the latest scan of a university.

Parameters: id (required)

Code Examples

curl -s 'https://unirankscanner.cyber-aab.com/api/v1/universities/1/scores'

const res = await fetch('/api/v1/universities/1/scores');
const data = await res.json();
console.log(data);

import requests

res = requests.get('http://localhost/api/v1/universities/1/scores')
data = res.json()
print(data)

Response Schema

{
    "success": true,
    "data": {
        "scan_id": 42,
        "overall_score": 72.5,
        "webo_composite_score": 68.2,
        "tech_composite_score": 75.1,
        "research_composite_score": 80.3,
        "presence_composite_score": 65.9,
        "tech_ssl_score": 95,
        "tech_speed_desktop_score": 82,
        "...": "30+ sub-scores"
    }
}

GET /api/v1/rankings

Get all universities ranked by overall score.

Parameters: page (default: 1), limit (default: 50), country (filter), min_score, max_score, sort (overall|webometrics|technical|research|presence)

Code Examples

curl -s 'https://unirankscanner.cyber-aab.com/api/v1/rankings'

const res = await fetch('/api/v1/rankings');
const data = await res.json();
console.log(data);

import requests

res = requests.get('http://localhost/api/v1/rankings')
data = res.json()
print(data)

Response Schema

{
    "success": true,
    "data": [
        {
            "rank": 1,
            "id": 5,
            "domain": "top-uni.edu",
            "name": "Top University",
            "country": "US",
            "overall_score": 89.2,
            "webometrics_score": 68.2,
            "technical_score": 75.1,
            "research_score": 80.3,
            "presence_score": 65.9
        }
    ]
}

GET /api/v1/stats

Get platform-wide statistics.

Code Examples

curl -s 'https://unirankscanner.cyber-aab.com/api/v1/stats'

const res = await fetch('/api/v1/stats');
const data = await res.json();
console.log(data);

import requests

res = requests.get('http://localhost/api/v1/stats')
data = res.json()
print(data)

Response Schema

{
    "success": true,
    "data": {
        "total_universities": 45,
        "total_scans": 312,
        "average_score": 54.8
    }
}

GET /api/v1/compare

Compare universities side by side using their IDs.

Parameters: ids (required) — comma-separated IDs (2-10)

Code Examples

curl -s 'https://unirankscanner.cyber-aab.com/api/v1/compare?ids=1,2'

const res = await fetch('/api/v1/compare?ids=1,2');
const data = await res.json();
console.log(data);

import requests

res = requests.get('http://localhost/api/v1/compare',
                   params={'ids': '1,2'})
data = res.json()
print(data)

Response Schema

{
    "success": true,
    "data": [
        {
            "university": {
                "id": 1,
                "domain": "uni-a.edu",
                "name": "University A"
            },
            "scan_date": "2025-01-10",
            "scores": {
                "overall_score": 72.5
            }
        }
    ]
}

GET /api/v1/universities/{id}/export

Export all university data as JSON (scores, history, recommendations).

Parameters: id (required)

Code Examples

curl -s 'https://unirankscanner.cyber-aab.com/api/v1/universities/1/export'

const res = await fetch('/api/v1/universities/1/export');
const data = await res.json();
console.log(data);

import requests

res = requests.get('http://localhost/api/v1/universities/1/export')
data = res.json()
print(data)

Response Schema

{
    "success": true,
    "data": {
        "exported_at": "2025-01-10T08:00:00+00:00",
        "university": {
            "id": 1,
            "domain": "example.edu"
        },
        "latest_scores": {
            "overall_score": 72.5
        },
        "recommendations": [],
        "scan_history": []
    }
}

GET /health

Check system health status (database, disk, cache).

Code Examples

curl -s 'https://unirankscanner.cyber-aab.com/health'

const res = await fetch('/health');
const data = await res.json();
console.log(data.status);

import requests

res = requests.get('http://localhost/health')
data = res.json()
print(data['status'])

Response Schema

{
    "status": "healthy",
    "version": "3.7.0",
    "timestamp": "2025-01-10T08:00:00+00:00",
    "checks": {
        "database": {
            "status": "ok"
        },
        "disk": {
            "status": "ok",
            "free_gb": 45.2
        },
        "logs": {
            "status": "ok",
            "writable": true
        },
        "cache": {
            "status": "ok",
            "entries": 150
        }
    }
}

Webhooks

Get automatic notifications when a scan completes. Configure webhooks from Admin → Webhooks.

Events

Event	Description
`scan.completed`	Scan completed successfully

Payload Format

{
  "event": "scan.completed",
  "timestamp": "2025-01-10T08:00:00+00:00",
  "data": {
    "scan_id": 42,
    "university_id": 5,
    "domain": "example.edu",
    "overall_score": 72.5,
    "completed_at": "2025-01-10T08:00:00+00:00"
  }
}

Signature Verification

Every webhook request includes the header X-Webhook-Signature: sha256=<hmac>

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $payload, $your_secret);
if (!hash_equals($expected, $signature)) {
    http_response_code(403);
    exit('Invalid signature');
}

Rate Limiting

The public API has a limit of 100 requests per hour per IP.

Header	Description
`X-RateLimit-Remaining`	Number of remaining requests